Skip to content

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