Start scenario call

Scenario call

Method	`start.scenario_call`
API version	v4.0
Description	Method allows you to make calls according to a customized acenario. To use the method you only need a virtual phone number and N scenario.
Go back to list of methods

Parameters of 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 of the number should comply with the international standart E.164 (for example, `74993720692`). Is always used as a caller's number when dialing the 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 using REST API method - Receiving a list of virtual numbers.
external_id		string	no		Unique ID, that can be used to connect call action with an outside system.
dtmf_string		string	no	0-9, *, #	Sets DTMF, that will be sent to a subscriber from the `contact` parameter. You can set a timeout for when to dispatch DTMF using symbol `.` = '1 second'. For example: `.12.1..4`, i.e. in 1 second the figure 12 will be sent, in another second the figure 1 will be sent, and than in 2 seconds the figure 4 will be sent.
contact		string	yes		A number that is used to reach a subscriber. Its format should comply with international standart E.164 (for example, `79091234567`). You can also use SIP number as an emploee's number. If the parameter `contact_message` is not given, a subscriber will listen to a system melody - `Dialing music (dialing_music)` Employees' extension numbers are not supported.
first_call		string	yes	contact, employee	Defines number, that should be reached in the first place: `employee` - employee; `contact` - called side (usually client);
switch_at_once		boolean	no	true, false	Default value is `false`. If the `first_call` parameter has value `employee`, a message is specified for an employee in the scenario, and the parameter `contact_message` is given: The first call reaches an employee from the scenario; After the employee takes call he listents to the message till the end, and after that dials a `contact`; While dialing the `contact`, the employee listens to a system melody - `Dialing music (dialing_music)`; After the `contact` answers the call, a conversation with the employee starts if the parameter `switch_at_once` has value `true`; After a `contact` answers the call, he or she will listen the message till the end if the parameter `switch_at_once` has value `false`. After that a conversation begins. If the parameter `first_call` has value `contact`, the parameter `contact_message` and a message for an employee are given in the scenario: A call to a `contact` should be made in the first place); After the `contact` takes call, he or she starts listening to the message. At the same time a call to an employee from the scenario is being 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 lestening 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
scenario_id		number	yes		Unique scenario ID that can be accessed by using REST API - Receiving a list of scenarios.
direction		string	no	in, out	Default value is `in`. Defines direction of a call: `in` - Incoming call, `out` - Outgoing call.
Message that a `contact` listens to.
contact_message		object	no		Defines parameters of the message that a `contact` listens to. As the message is played, a system melody is played continually - `Dialing music (dialing_music)`
	type	string	yes	media, tts	Defines a type of a message. `media` - meida file or `tts` - text for voice synthesis service Text-to-Speech.
	value	string	yes		If the field `type` has `media` in it, an ID of the file to be played is used as value. The file may be both a system or a user file. You can access the file's 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 that is played for an employee
employee_message		object	no		Defines parameters of a message that's going to be played for an employee. A message for an employee specified in the scenario has a higher priority than a message from the `employee_message` parameter. However both of the messages will be played in sequence. After a message is played, the code>media_file_id message will be played continually.
	type	string	yes	media, tts	Defines the type of a message. `media` - media file or `tts` - text for voice synthesis service Text-to-Speech.
	value	string	yes		If the field `type` has `media` in it, an ID of the file to be played is used as value. This file can be both a system or a user file. You can access the file's 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	Unique call session ID

Example of a request

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

Example of a reply

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

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`	Length of your message exceeded the limit 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 the client
Scenario with id {`scenario_id`} not found	-32602	`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 permitted
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 section List of errors common for all methods