Callgear

Call to an employee

Method	`start.employee_call`
API version	v4.0
Description	The method creates a direct call between a subscriber and an employee without using a script.
Return to list of methods

Request parameters

parameter will be connected

Name		Type	Required	Valid values	Description
access_token		string	yes		Authentication session key
first_call		string	yes	contact, employee	Defines the number to call first: `employee` - employee; `contact` - the called party (usually the client);
switch_at_once		boolean	no	true, false	Default value `false`. If `first_call` is `employee`, the parameters are `employee_message` and `contact_message`, then: The first call is made to the employee from the `employee` parameter; After picking up the phone, the employee listens to the message to the end and only then a call is made to the subscriber specified in the `contact` parameter; When dialing to `contact`, `employee` listens to the message specified in the `media_file_id` parameter; After the subscriber responds from the `contact` parameter, a conversation will occur with the employee from the `employee` parameter, if `switch_at_once` is set to `true`; After the subscriber responds from the `contact` parameter, he will listen to the message to the end if `switch_at_once` has the value `false` and then a conversation will take place with the employee from the `employee` parameter. If `first_call` is `contact`, `contact_message` is specified and parameter `employee_message`, then: First of all, the call is made to the subscriber from the parameter `contact`); The subscriber from the `contact` parameter, after picking up the handset, begins to listen to the message and at the same time a call is made to the employee from the `employee` parameter; After the employee picks up the phone from the `employee` parameter, playback of the message will be interrupted for the subscriber from the `contact` parameter and then a conversation will take place if the `switch_at_once` parameter is set to `true`; After the employee picks up the phone from the `employee` parameter, the message will be played to the end for both and then a conversation will take place if the `switch_at_once` parameter is set to `false`; If someone's message has finished playing earlier, then he listens to the message specified in the `media_file_id` parameter. If the `contact_message type` parameter has the value `tts`, then the `switch_at_once=true` parameter does not work
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 his voicemail is activated, then when the parameter `early_switching` = `true` is activated, the operator will be able to hear a message about the subscriber's voicemail. If the parameter `early_switching` = `false`, then the operator will listen to the music specified in the "media_file_id" parameter The parameter can have the value `true` unless the `first_call` parameter has the value `employee` and the `switch_at_once` parameter has the value `true`. Otherwise, there will be an error "-32602 invalid_parameters_combination The combination of parameters is not permitted" (see 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 forward music. The file can be either system or and custom. You can get a list of system or user files using DATA API - Getting a list of user files, Getting a list of system files. Always plays to the arm for which one of the parameters `contact_message` or `employee_message`
virtual_phone_number		string	yes		Virtual number rented by the client. The number format must comply with international E.164 standard (for example, `74993720692`). Always used as the caller number when calling to the number specified in the `contact` parameter. Used as the caller number when calling to the number specified in the `employee` 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 the number is suitable, that satisfies 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 The default rule is `Фиксированный`. Other rules are available when the component is connected `Автоматическое управление номерами`.
show_virtual_phone_number		boolean	no	true, false	Default value `true`. Whether to show the virtual number specified by the `virtual_phone_number` parameter as the caller number for the employee specified in the `employee` parameter.
contact		string	yes		The number of the subscriber to which the call is made. The number format must match international standard E.164 (for example, `79091234567`). The employee's SIP number can also be specified as a number. Employee extensions are not supported. If an employee is specified as a contact, then the status of the number is not taken into account. Searching for a contact name is only possible in the address book, because this method is considered as a call to an external number.
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. C Using the symbol `.` = '1 second' you can set a timeout after which the DTMF symbol will be sent. Example: `.12.1..4`, i.e. after 1 second the number 12 will be sent, then after 1 second the number 1 will be sent 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.
Employee to whom the subscriber from the `contact`
employee		object	yes		The employee to whom the subscriber specified in the `contact` parameter will be connected.
	id	number	yes		Unique employee identifier. This identifier can be obtained using the DATA API - Obtaining information about an employee If the `phone_number` parameter is not specified, then a sequential call will be made to all active employee numbers.
	phone_number	string	no		Specifies the number of the employee with whom the subscriber specified in the `contact` parameter will be connected. The number can be a SIP number, an internal number, or a number in E.164 format. The number must have the status `Активен` in your personal account and belong to the employee specified in the `id` parameter.
Message to be played to the subscriber specified in the parameter `contact`
contact_message		object	no		Defines the parameters of the message that needs to be played to the subscriber specified in the `contact` parameter. After the message has finished playing, the message from the parameter `media_file_id` will be played in a circle
	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 file identifier for playing. The file to be played can be system or user. ID The file to be played 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 text is taken as the value to synthesize it into voice message. 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 `employee`
employee_message		object	no		Defines the parameters of the message that needs to be played to the subscriber specified in the `employee` parameter. After the message has finished playing, the message from the parameter `media_file_id` will be played in a circle
	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 file identifier for playing. The file to be played can be system or user. ID The file to be played 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 text is taken as the value to synthesize it into voice message. The length of the TTS message is regulated by the tariff plan and the established limit.

Response parameters

Title	Type	Required	Description
call_session_id	number	yes	Unique call session identifier

Example request```json

{ "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": "Привет" }, "employee_message": { "type": "media", "value": "2561" } } }

#### Sample answer```json
{
  "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 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`} 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
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`	The employee does not have active numbers in the employee settings
Parameter `contact` can not contain 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 section "List of errors common to all methods"

Call to an employee

Request parameters

Response parameters

Example request```json

List of returned errors

CallGear online demo

Thank you, we've got your request!

Choose the number of employees who will use telephony

Choose the industry in which your company operates

Choose your CRM

Thanks!

Choose your region for a better connection

Account recovery