Start simple call

Simple call

Method	`start.simple_call`
API version	v4.0
Description	Call to any number except own virtual numbers. This is not a call from an employee to any 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
first_call		string	yes	contact, operator	Defines a number that should be dialed in the first place: `operator` - an operator, who will be able to manage calls via conversation options; `contact` - called side (usually client);
switch_at_once		boolean	no	true, false	Default value is `false`. If the parameter `first_call` has value `operator` and the parameter `operator_message` is given, an operator takes call. He or she listens to the message till the end, and than calls a `contact`. If the parameter `switch_at_once` has value `true` and the parameter `contact_message` is given, the message will be interrupted for the leg `contact`. While reaching for a `contact`, an `operator` listens to the message from the parameter `media_file_id`. Consequently if the parameter `switch_at_once` has value `false`, and the parameter `contact_message` is given, the message will be played till the end for the leg `contact`. If the parameter `first_call` has value `contact`, and the parameter `contact_message` is given, a client takes call. Than he or she listens to the message, and at the same time a call to an `operator` is made. If the parameter `switch_at_once` has value `true` and the parameter `operator_message` is given, after an `operator` takes call, messages will be interrupted for both the `contact` and the `operator`. Consequently, if the parameter `switch_at_once` has value `false`, the message will be played till the end for the legs `contact` and `operator`. If one of the legs finishes lisneting to the message earlier than the other one, he or she listens to the promt, given in the parameter `media_file_id`.
early_switching		boolean	no	true, false	Default value is `false`. If the parameter has value `true`, an employee, dialing a subscriber, will hear what's happening on the line. For example, an oreator is trying to reach a subscriber, the subscriber is unavailable, and the operator reaches his or hers voicemail. Activating the parameter `early_switching` = `true`, the operator will be able to hear a message from the subscriber's voicemail. If the parameter `early_switching` = `false`, the operator will listen to the music given in the parameter "media_file_id" The parameter can have value `true` only if the parameter `first_call` have value `operator`, and the parameter `switch_at_once` has value `true`. Otherwise the error "-32602 invalid_parameters_combination The combination of parameters is not permitted" occurs (refer to section Errors codes).
media_file_id		number	no		Default value is a system melody "Dialing Music" (`dialing_music`). Defines ID of a media file with Dialing Music. The file can be system or user. You can access list of system and user files via REST API - Receiving a list of user files, Receiving a list of system files. Is always played for the leg that doesn't have one of the parameters: `contact_message` or `operator_message`
virtual_phone_number		string	yes		Virtual number, rented by client. Format of the number 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`. Can be used as a caller's number when dialing a number of an `operator` if the parameter `show_virtual_phone_number` has value `true`. You can access virtual numbers via REST API method - Receiving a list of virtual numbers.
show_virtual_phone_number		boolean	no	true, false	Default value is `true`. Defines whether a virtual number from the parameter `virtual_phone_number` will be shown to an `operator` as a caller's number or not.
contact		string	yes		Number of a subscriber you're reaching for. Format should comply with the international standart E.164 (for example, `79091234567`). You can also use SIP number of an employee. Extension numbers of employees are not supported.
external_id		string	no		Unique ID, that can be used to connect an event of a call with an outside system.
dtmf_string		string	no	0-9, *, #	Assigns 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.
An operator that's going to talk to a `contact`
operator		string	yes		Number of an operator that's going to talk to a `contact`. The operator can manage the call - conversation options. Format should comply with the international standart E.164 (for example, “79091234567”). Is not considered as employee. Is not featured as an employee in reports.
operator_confirmation		string	no	0-9, *, #, any	Receiving a confirmation from an operator that he or she is ready to take call. When using value "any", you can send the conversation by pushing any of the buttons.
contact_message		object	no		Defines parameters of the message that's to be played for a `contact`. After the message is played, a message from the parameter `media_file_id` is played continually.
	type	string	yes	media, tts	Defines type of a message: `media` is a media file or `tts` - is a text for voice synthesis service Text-to-Speech.
	value	string	yes		If the field `type` has `media` in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID 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.
Message to be played for an `operator`
operator_message		object	no		Defines parameters of a message that's to be played for an `operator`. After the message is played, a message from the parameter `media_file_id` is played continually.
	type	string	yes	media, tts	Defines type of a message: `media` is a media file or `tts` - is a text for voice synthesis service Text-to-Speech.
	value	string	yes		If the field `type` has `media` in it, ID of a media file to be played is used as value. The file can be both system and user. You can access media file ID 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.simple_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "first_call": "operator",
    "switch_at_once": true,
    "media_file_id": 2701,
    "show_virtual_phone_number": false,
    "virtual_phone_number": "74993720692",
    "external_id": "334otr01",
    "dtmf_string": ".1.2.3",
    "direction": "in",
    "contact": "79260000000",
    "operator":"79262444491",
    "contact_message": {
      "type": "tts",
      "value": "Hello"
    },
    "operator_message": {
      "type": "media",
      "value": "2561"
    }
  }
}

Example of a reply

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

List of returning errors

Text of error	Code of error	Mnemonics	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`	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 does not belong to a client
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	-32002	`contact_in_blacklist`
The character encoding must be UTF-8	-32602	`character_encoding_not_allowed`

Refer to List or errors common for all methods