Start vnumber call

Call to a virtual number

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

Parameters of a request

Title		Type	Required	Valid value	Description
access_token		string	yes		Authentication session key
virtual_phone_number		string	yes		Virtual number, rented by client. Format should comply with the international standart E.164 (for example, 74993720692). Is always used as a caller's number when dialing a number of a contact. Is used as a caller's number when calling an employee if scenario implies setting "Show during call" with value "Number of service" in operation "Call Forwarding". You can access virtual numbers via REST API method - Receiving a list of virtual numbers
external_id		string	no		Unique ID that can be used to connect a call action with an outside system.
dtmf_string		string	no	0-9, *, #	Defines DTMF, that will be sent to a contact. You can specify timeout for when the DTMF symbol is going to be sent by using a symbol . = '1 second'. Example: .12.1..4, i.e. the number 12 will be sent in 1 second, a number 1 will be sent in another second, and than a number 4 will be sent in 2 seconds.
direction		string	no	in, out	Default value is in. Defines the direction of call: in - Incoming call, out - Outgoing call.
contact		string	yes		The number of a subscriber you're reaching for. The format should comply with the international standart E.164 (for example, 79091234567). You can also use SIP number of an employee. If the parameter contact_message is not given, a subscriber will listen to a system melody - Dialing Music (dialing_music) Extension numbers of the employees are not supported.
first_call		string	yes	contact, employee	Defines number that should be dialed in the first place: employee - employee; contact - called side (usually a client);
switch_at_once		boolean	no	true, false	Default value is false. If the parameter first_call has value employee, a message for an employee from the scenario and the contact_message parameter are given: First call reaches an employee from the scenario; After the employee takes call, he or she listens to the message till the end, and only after that a call to the contact is made; While dialing the contact, the employee listens to a system melody - Dialing Music (dialing_music); As the contact replies, a conversation with the employee happens, if the parameter switch_at_once has value true; After the contact replies, he or she listens to the message till the end if the parameter switch_at_once has value false. Than a conversation with the employee begins. If the parameter first_call has value contact, the parameter contact_message is given, and a message to the employee is given in the scenario: A call to a contact should be made in the first place; After the contact takes call he or she listens to the message. At the same time a call to an employee from the scenario is made; After the employee takes call the message will be interrupted for the contact. Than a conversation begins if the parameter switch_at_once has value true; After the employee takes call, both the employee and the subscriber will listen to the message till the end, after that a conversation begins if the parameter switch_at_once has value false; If one of the call's participants finishes listening to the message earlier than the other one, he or she listens to a system melody - Dialing Music (dialing_music). If the parameter contact_message type has value tts, the parameter switch_at_once=true doesn't work
A message that is to play to a contact
contact_message		object	no		Defines parameters of the message, that needs to be played to a contact. After the message is played, system melody starts playing continually - Dialing Music (dialing_music)
	type	string	yes	media, tts	Defines the type of a message. media is a media file, and tts is a text for voice synthesis service Text-to-Speech.
	value	string	yes		If the field type has media in it, ID of the file that's to be played is used as value. The file can be both system and user. You can access an ID of the file via REST API - Receiving a list of user files, Receiving a list of system files. If the field type has tts in it, text for voice synthesis is used as value. Length of a TTS message depends on your service plan or a limit.

Parameters of a reply

Title	Type	Required	Description
call_session_id	number	yes	Call session unique ID

Example of a 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 of a reply

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

List of returning errors

Text of error	Code of error	Mnemonics of error	Description
The maximum length of Text-to-Speech message is {tts_message_max_length}. The length of your message is {sent_tts_message_length}	-32602	tts_text_exceeded	The length of your message exceeded the limits of your service plan
The media file with id {media_file_id} 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	Virtual number doesn't belong to a client
Virtual phone number does not have a scenario	-32007	scenario_not_found
Parameter contact can not contain own virtual phone number	-32602	own_virtual_phone_number_not_allowed	Calls to own virtual numbers are not allowed
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

Refer to List of errors common for all methods