Start employee call

Employee call

Method	`start.employee_call`
API version	v4.0
Description	The method implements a direct call to an employee and does not use any scenario.
Go back to methods list

Parameters of a request

Title		Type	Required	Valid value	Description
access_token		string	yes		Authentication session key
first_call		string	yes	contact, employee	Specifies a 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 `false`. If the parameter `first_call` has value `employee`, and parameters `employee_message` and `contact_message` are given: First call is assigned to an employee mentioned in the `employee` parameter; After an employee takes a call he or she listens to the message till the end. Only after that a call to an employee mentioned in a `contact` parameter is made; While dialing a `contact`, an `employee` listens to the message specified in the `media_file_id` parameter; After a subscriber specified in the `contact` parameter answers, a conversation with an `employee` begins, if the `switch_at_once` parameter has value `true`; After a `contact` answers, he or she listens to the message till the end, if the `switch_at_once` parameter has value `false`. Than a conversation with an `employee` begins. If the parameter `first_call` has value `contact`, and the parameters `contact_message` and `employee_message` are given: In the first place, a call to a subscriber specified in the `contact` parameter is made; The `contact` subscriber answers the call and starts listening to the message. At the same time a call to an `employee` is made); When the `employee` takes call, the message stops for the `contact`. Coversation begins if the `switch_at_once` parameter has value `true`; When the `employee` takes call, the message will be played till the end. Than a conversation starts 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, he or she starts listening to a message from the `media_file_id`. If the parameter `contact_message type` has value `tts`, the parameter `switch_at_once=true` doesn't work
early_switching		boolean	no	true, false	Default value is `false`. If a parameter has value `true`, an employee, dialing a subscriber, hears what's going on the subscriber's line. For example, an operator is trying to reach a subscriber, but the subscriber is unavailable, and the operator reaches his or hers voicemail. By activating the parameter `early_switching` = `true`, the operator gets to hear a message about the subscriber's voicemail. If the parameter `early_switching` = `false`, the operator gets to listen to the music from the "media_file_id" parameter A parameter can have value `true` only when the parameter `first_call` has value `employee` and the parameter `switch_at_once` has value `true`. Otherwise an error "-32602 invalid_parameters_combination The combination of parameters is not permitted" occurs (refer to Errors codes).
media_file_id		number	no		System melody "Dialing music" (`dialing_music`) is a default value. Provides ID for a dialing music media file. This can be both a system and a user media file. You can access a list of system and user files by using REST API - Receiving a list of user files, Receiving a list of system files. Is always played for a call leg that does not have one of the parameters: `contact_message` or `employee_message`
virtual_phone_number		string	yes		Virtual number, rented by client. Number's format should be the same as the international standart E.164 (for example, `74993720692`). Is always used as a caller's number when dialing a number from the `contact` parameter. Is used as a caller's number when dialing a number from the `employee` parameter, if the `show_virtual_phone_number` parameter has value `true`. Virtual numbers are accessible via REST API method - Receiving a list of virtual number.
virtual_phone_usage_rule		string	no		Virtual number rule. Dynamically changes virtual numbers in calls. If there is no number matching the conditions, the system will use a number from a parameter `virtual_phone_number`. Parameter values: `fixed` - Fixed `fixed_for_numa` - Fixed for subscriber `random` - Random `regional_random` - Local random `regional_fixed_for_numa` - Local fixed for subscriber `Fixed` number rule is used by default. Other rules are available if the `Automatic phone number management` component is enabled.
virtual_number_group		number	no		Group number of the virtual number pool which settings will be used in the call. For the group of virtual numbers to work correctly, you must also pass the parameter `virtual_phone_usage_rule` with any value other than fixed.
show_virtual_phone_number		boolean	no	true, false	Default value is `true`. Shows an `employee` a virtual number from the `virtual_phone_number` parameter as a calling subscriber's number.
contact		string	yes		A number of a subscriber that is being dialed. The number should follow the international standart E.164 (for example, `79091234567`). As a number an employee's SIP can be used. 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 call direction `in` - Incoming call, `out` - Outgoing call.
An employee to take a call from a `contact`
employee		object	yes		An employee that will take a call from `contact`.
	id	number	yes		A unique ID of an employee. You can get an ID from REST API - Receiving employee information If the parameter `phone_number` is not specified, all the employee's active phone numbers will be consecutively dialed.
	phone_number	string	no		Provides a number an employee that will take a call from a `contact`. A SIP-number, an extension number or a number in the E.164 format can be used. The number should be `Active` in a client area and should be appointed to an employee, specified in the `id` parameter.
A message that a `contact` listens to
contact_message		object	no		Defines parameters of a message to play to a subscriber from the `contact` parameter. After the message is played, a `media_file_id` will be played continually
	type	string	yes	media, tts	Defines a 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, a file ID is used as a value. The media file may be user or system. You can access a media file's ID via REST API - Receiving user files list, Receiving system files list. If the field `type` has `tts` in it, text for voice synthesis is used as value. Length of a TTS message is defined by your service plan or a limit.
A message `employee` listens to
employee_message		object	no		Defines parameters of a message an `employee` listens to. After the message is played, a `media_file_id` will be played continually
	type	string	yes	media, tts	Defines a type of a message. `media` file or `tts` - a text for text for voice synthesis service Text-to-Speech.
	value	string	yes		If the `type` is `media`, the file's ID is used as value. This can be a system or a user file. You can access the file's ID using REST API - Receiving user files list, Receiving system files list. If the field `type` has `tts` in it, text for voice synthesis is used as value.. Length of a TTS message is defined by your service plan or a limit.

Example 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.employee_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "first_call": "employee",
    "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",
    "employee": {
      "id": 25,
      "phone_number": "79260000001"
    },
    "contact_message": {
      "type": "tts",
      "value": "Hello"
    },
    "employee_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	Error code	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 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 is not attributed to client
Employee with id {`employee_id`} not found. It is not your employee.	-32602	`employee_not_found`
The phone number does not exist or inactive	-32602	`no_active_phone_number`	Employee does not have active phone numbers in the employee settings
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 of errors common for all methods