Start simple call

Simple call

Method	`start.simple_call`
API version	v4.0
Description	Call any number except your own virtual ones. This is not a call from an employee to any number.
Return to list of methods

Request parameters

Name		Type	Required	Valid values	Description
access_token		string	yes		Authentication session key
first_call		string	yes	contact, operator	Defines the number to call first: `operator` - operator who will be able to control the call through talk options; `contact` - the called party (usually the client);
switch_at_once		boolean	no	true, false	Default value `false`. If the `first_call` parameter has the value `operator` and the `operator_message` parameter is specified, then the call is made to the operator; after picking up the handset, the operator listens to the message to the end, then a call is made to `contact`; and if `switch_at_once` has the value `true` and the `contact_message` parameter is specified, then playback of the message will be interrupted for the `contact` leg. When dialing `contact`, operator listens to the message specified in the `media_file_id` parameter. Accordingly, if `switch_at_once` has the value `false` and the `contact_message` parameter is specified, then the message will be played to the end for the `contact` leg. If the `first_call` parameter has the value `contact` and the `contact_message` parameter is specified, then a call is made to the client; after picking up the handset, the client begins to listen to the message, and at the same time a call is made to `operator`; and if `switch_at_once` has the value `true` and the `operator_message` parameter is specified, then after operator picks up the handset, playback of the message will be interrupted for `contact` and `operator`. Accordingly, if `switch_at_once` has the value `false`, then the message will be played to the end for the `contact` and `operator` legs. If one party's message has finished playing earlier, that party listens to the message specified in the `media_file_id` parameter.
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 `operator` 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).
media_file_id		number	no		The default value is the system melody "Forwarding Music" (`dialing_music`). Sets the audio file ID for the forwarding music. The file can be either system or custom. You can get a list of system or user files using the DATA API - Getting a list of user files, Getting a list of system files. Note: always plays to the leg for which one of the `contact_message` or `operator_message` parameters is set.
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 number specified in the `operator` parameter, if the `show_virtual_phone_number` parameter is set to `true`. 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.
show_virtual_phone_number		boolean	no	true, false	Default value `true`. Whether to show the virtual number specified in the `virtual_phone_number` parameter as the caller number for the operator specified in the `operator` parameter.
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: employee extension numbers are not supported.
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.
Operator with which the subscriber will be connected from the parameter `contact`
operator		string	yes		The operator number to which the subscriber from the `contact` parameter will be connected. The operator has access to call control through talk options. The number format must comply with the international E.164 standard (for example, `79091234567`). Note: not an employee, and will not appear in reports as an employee.
operator_confirmation		string	no	0-9, *, #, any	Receive confirmation from the operator that they are ready to accept the call. If you specify the value "any", then confirmation of readiness to accept the call will be made by pressing any key.
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 message from the `media_file_id` parameter will be played on a loop.
	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.
Message to be played to the subscriber specified in the parameter `operator`
operator_message		object	no		Defines the parameters of the message that needs to be played to the subscriber specified in the `operator` parameter. Note: after the message has finished playing, the message from the `media_file_id` parameter will be played on a loop.
	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.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 response

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

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
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	-32002	`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".