Skip to content

Start vnumber call

Call to a virtual number

Method start.vnumber_call
API version v4.0
Description Call to a virtual number.
Return to list of methods

Request parameters

Name Type Required Valid values Description
access_token string yes Authentication session key
virtual_phone_number string yes

Virtual number rented by the client. The number format must comply with the international E.164 standard (for example, 74993720692). Always used as the caller number when calling the number specified in the contact parameter. Used as the caller number when calling the employee, if in the scenario in the “Forwarding” operation the “Show when calling” setting is set to “Service number”. Virtual numbers can be obtained using the DATA API method - Getting a list of virtual numbers.

virtual_phone_usage_rule string no

Rules for using a virtual number. Allows you to dynamically change the virtual number when calling. If a suitable number satisfying the selected rule is not found, the number specified in the virtual_phone_number parameter will be used. Valid parameter values:

  • fixed - Fixed
  • fixed_for_numa - Fixed for subscriber
  • random - Random
  • regional_random - Regional random
  • regional_fixed_for_numa - Regional fixed line for the subscriber

Note: the default rule is fixed. Other rules are available when the Automatic number management component is connected.

external_id string no A unique identifier that can be used to associate a call event with an external system.
dtmf_string string no 0-9, *, # Specifies the DTMF that will be sent to the subscriber specified in the contact parameter. Using the . symbol (= "1 second") you can set a timeout after which the DTMF symbol will be sent. Example: .12.1..4 - that is, after 1 second the number 12 will be sent, then after 1 second the number 1, and after 2 seconds the number 4.
direction string no in, out The default value is in.
Determines the direction of the call: in - Incoming call, out - Outgoing call.
contact string yes

The number of the subscriber to whom the call is made. The number format must match the international E.164 standard (for example, 79091234567). The employee's SIP number can also be specified as the number.

Note: if the contact_message parameter is not specified, then the system melody will be played to the subscriber - Forwarding Music (dialing_music).
Note: employee extension numbers are not supported.
first_call string yes contact, employee

Defines the number to call first:

  • employee - employee;
  • contact - the called party (usually the client);
switch_at_once boolean no true, false

Default value false.

If the first_call parameter is set to employee, a message to the employee is specified in the scenario, and the contact_message parameter is specified, then:

  • The first call is made to the employee from the scenario;
  • After picking up the phone, the employee listens to the message to the end and only then makes a call to the subscriber specified in the contact parameter;
  • When calling contact, the employee listens to the system melody - Forwarding Music (dialing_music);
  • After the subscriber from the contact parameter responds, a conversation with the employee will occur if switch_at_once has the value true;
  • If switch_at_once is set to false, the subscriber will listen to the message to the end and then a conversation with the employee will take place.

If first_call is contact, and contact_message and the message to the employee in the scenario are specified, then:

  • First, the call is made to the subscriber from the contact parameter;
  • After picking up the handset, the subscriber begins to listen to the message and at the same time a call is made to the employee from the scenario;
  • After the employee picks up the phone, playback of the message will be interrupted for the subscriber and a conversation will then take place if switch_at_once is true;
  • If switch_at_once is false, the message will be played to the end for both and then a conversation will take place;
  • If someone's message has finished playing earlier, that person listens to the system melody - Forwarding Music (dialing_music).
Note: if the contact_message.type parameter has the value tts, then switch_at_once=true does not work.
early_switching boolean no true, false

Default value false.

If the parameter has the value true, then the employee, when dialing the subscriber, will hear what is happening on the subscriber line.

For example, an operator is waiting for a call to reach a subscriber, but the subscriber is unavailable and their voicemail is activated; then, when early_switching = true, the operator will be able to hear the subscriber's voicemail message. If early_switching = false, the operator will hear the music specified in the media_file_id parameter.

Note: the parameter can have the value true unless the first_call parameter has the value employee and the switch_at_once parameter has the value true. Otherwise, the error -32602 invalid_parameters_combination - The combination of parameters is not permitted will occur (see the error codes section).
Message to be played to the subscriber specified in the parameter contact
contact_message object no

Defines the parameters of the message that needs to be played to the subscriber specified in the contact parameter.

Note: after the message has finished playing, the system melody will be played on a loop - Forwarding Music (dialing_music).
type string yes media, tts

Defines the message type: media - file, or tts - text for the Text-to-Speech speech synthesis service.
value string yes

If the type field has the value media, then the value is the identifier of the file to play. The file to be played can be system or user. The file identifier can be obtained using the DATA API - Getting a list of user files, Getting a list of system files.

If the type field has the value tts, then the value is the text to be synthesized into a voice message.

Note: the length of the TTS message is regulated by the tariff plan and the established limit.

Response parameters

Name Type Required Description
call_session_id number yes Unique call session identifier

Example request

{
  "jsonrpc": "2.0",
  "method": "start.vnumber_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "virtual_phone_number": "74993720692",
    "external_id": "34rty567",
    "dtmf_string": "..1.2.3",
    "direction": "in",
    "contact": "79260000000",
    "first_call": "employee",
    "switch_at_once": false,
    "show_virtual_phone_number": true,
    "contact_message": {
      "type": "media",
      "value": "237"
    }
  }
}

Example response

{
  "jsonrpc": "2.0",
  "id": "req1",
  "result": {
    "data": {
      "call_session_id": 123467589
    }
  }
}

List of returned errors

Error text Error code Mnemonics Description
The maximum length of a Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length} -32602 tts_text_exceeded Message length has exceeded the permissible limit set by the tariff plan
The media file with id {media_file_id} was not found -32602 media_file_not_found
Virtual phone number {virtual_phone_number} not found. It is not your virtual phone number. -32007 virtual_phone_number_not_found If you use a virtual number that does not belong to the client
Virtual phone number does not have a scenario -32007 scenario_not_found
The contact parameter cannot contain your own virtual phone number -32602 own_virtual_phone_number_not_allowed Calling your own virtual number is prohibited
The contact {contact} has been found in the blacklist -32602 contact_in_blacklist
The character encoding must be UTF-8 -32602 character_encoding_not_allowed

See also the section "List of errors common for all methods".