Start employee call

Вызов на сотрудника

Метод	`start.employee_call`
Версия API	v4.0
Описание	Метод создает прямой звонок абонента с сотрудником без использования сценария.
Вернуться к списку методов

Параметры запроса

Название		Тип	Обязательный	Допустимые значения	Описание
access_token		string	да		Ключ сессии аутентификации
first_call		string	да	contact, employee	Определяет номер, на который нужно дозвониться в первую очередь: `employee` - сотрудник; `contact` - вызываемая сторона (обычно клиент);
switch_at_once		boolean	нет	true, false	Значение по умолчанию `false`. Если параметр `first_call` имеет значение `employee`, заданы параметры `employee_message` и `contact_message`, то: Первый звонок совершается сотруднику из параметра `employee`; Сотрудник после поднятия трубки слушает сообщение до конца и только потом совершается звонок на абонента заданного в параметре `contact`; Во время дозвона до `contact`, `employee` слушает сообщение заданное в параметре `media_file_id`; После ответа абонента из параметра `contact`, произойдет разговор с сотрудником из параметра `employee`, если `switch_at_once` имеет значение `true`; После ответа абонента из параметра `contact`, он дослушает сообщение до конца, если `switch_at_once` имеет значение `false` и далее произойдет разговор с сотрудником из параметра `employee`. Если параметр `first_call` имеет значение `contact`, задан параметр `contact_message` и задан параметр `employee_message`, то: В первую очередь звонок совершается абоненту из параметр `contact`); Абонент из параметра `contact` после поднятия трубки начинает слушать сообщение и в это же время совершается звонок на сотрудника из параметра `employee`; После поднятия трубки сотрудником из параметра `employee` проигрывание сообщения будет прервано для абонента из параметра `contact` и далее состоится разговор, если параметр `switch_at_once` имеет значение `true`; После поднятия трубки сотрудником из параметра `employee` сообщение будет проиграно до конца обоим и далее состоится разговор, если параметр `switch_at_once` имеет значение `false`; Если у кого-то проигрывание сообщения закончилось раньше, то он слушает сообщение, заданное в параметре `media_file_id`. Если в параметре `contact_message type` имеет значение `tts`, то параметр `switch_at_once=true` не работает
early_switching		boolean	нет	true, false	Значение по умолчанию `false`. Если параметр имеет значение `true`, то сотрудник при дозвоне до абонента будет слышать то, что происходит в абонентской линии. К примеру, оператор ждет дозвона до абонента, а абонент недоступен и у него сработала голосовая почта, то при активации параметра `early_switching` = `true`, оператор сможет услышать сообщение о голосовой почте абонента. Если параметр `early_switching` = `false`, то оператор будет слушать музыку, которая задана в параметре "media_file_id" Параметр может иметь значение `true` если только параметр `first_call` имеет значение `employee` и параметр `switch_at_once` имеет значение значение `true`. В противном случае будет ошибка "-32602 invalid_parameters_combination The combination of parameters is not permitted" (см. раздел коды ошибок).
media_file_id		number	нет		Значение по умолчанию - системная мелодия "Музыка переадресации" (`dialing_music`). Задает идентификатор звукового файла для музыки переадресации. Файл может быть как системным, так и пользовательским. Получить список системных или пользовательских файлов можно с помощью DATA API - Получение списка пользовательских файлов, Получение списка системных файлов. Проигрывается всегда тому плечу, для которого не задан один из параметров `contact_message` или `employee_message`
virtual_phone_number		string	да		Виртуальный номер, арендуемый клиентом. Формат номера должен соответствовать международному стандарту E.164 (например, `74993720692`). Всегда используется в качестве номера звонящего при звонке на номер, указанный в параметре `contact`. Используется в качестве номера звонящего при звонке на номер, указанный в параметре `employee`, если параметр `show_virtual_phone_number` имеет значение `true`. Виртуальные номера можно получить с помощью DATA API метода - Получение списка виртуальных номеров
virtual_phone_usage_rule		string	нет		Правило использования виртуального номера. Позволяет динамически менять виртуальный номер при звонке. Если подходящий номер, удовлетворяющий выбранному правилу, не найден, то будет использован номер, указанный в параметре `virtual_phone_number`. Допустимые значения параметра: `fixed` - Фиксированный `fixed_for_numa` - Фиксированный для абонента `random` - Случайный `regional_random` - Региональный случайный `regional_fixed_for_numa` - Региональный фиксированный для абонента По умолчанию используется правило `Фиксированный`. Остальные правила доступны при подключенном компоненте `Автоматическое управление номерами`.
show_virtual_phone_number		boolean	нет	true, false	Значение по умолчанию `true`. Показывать ли виртуальный номер, заданный параметром `virtual_phone_number` в качестве номера звонящего абонента для сотрудника заданного в параметре `employee`.
contact		string	да		Номер абонента на который совершается вызов. Формат номера должен соответствовать международному стандарту E.164 (например, `79091234567`). В качестве номера может быть так же указан SIP номер сотрудника. Внутренние номера сотрудников не поддерживаются. Если в качестве контакта указан сотрудник — то статус номера не учитывается. Поиск имени контакта осуществляется только в адресной книге, т.к. этот метод считается как звонок на внешний номер.
external_id		string	нет		Уникальный идентификатор, который может быть использован для связи события звонка с внешней системой.
dtmf_string		string	нет	0-9, *, #	Задает DTMF, который будет отправлен абоненту, заданному в параметре `contact`. С помощью символа `.` = '1 секунда' можно задать таймаут по истечению которого символ DTMF будет отправлен. Пример: `.12.1..4`, т.е через 1 секунду будет отправлена цифра 12, далее через 1 секунду будет отправлена цифра 1 и через 2 секунды цифра 4.
direction		string	нет	in, out	Значение по умолчанию `in`. Определяет направление звонка `in` - Входящий звонок, `out` - Исходящий звонок.
Сотрудник с которым будет соединен абонент из параметра `contact`
employee		object	да		Сотрудник с которым будет соединен абонент, указанный в параметре `contact`.
	id	number	да		Уникальный идентификатор сотрудника. Данный идентификатор можно получить с помощью DATA API - Получение информации о сотруднике Если не указан параметр `phone_number`, то будет совершен последовательный обзвон всех активных номеров сотрудника.
	phone_number	string	нет		Задает номер сотрудника с которым будет соединен абонент указанный в параметре `contact`. В качестве номера может быть указан SIP-номер, внутренний номер, номер в формате E.164. Номер должен иметь статус `Активен` в личном кабинете и принадлежать сотруднику заданному в параметре `id`.
Сообщение для проигрывания абоненту, который задан в параметре `contact`
contact_message		object	нет		Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре `contact`. После окончания проигрывания сообщения, будет проигрываться покругу сообщение из параметра `media_file_id`
	type	string	да	media, tts	Определяет тип сообщения. `media` - файл или `tts` - текст для услуги синтеза речи Text-to-Speech.
	value	string	да		Если поле `type` имеет значение `media`, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью DATA API - Получение списка пользовательских файлов, Получение списка системных файлов Если поле `type` имеет значение `tts`, то в качестве значения принимается текст для синтезирования его в голосовое сообщение. Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
Сообщение для проигрывания абоненту, который задан в параметре `employee`
employee_message		object	нет		Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре `employee`. После окончания проигрывания сообщения, будет проигрываться покругу сообщение из параметра `media_file_id`
	type	string	да	media, tts	Определяет тип сообщения. `media` - файл или `tts` - текст для услуги синтеза речи Text-to-Speech.
	value	string	да		Если поле `type` имеет значение `media`, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью DATA API - Получение списка пользовательских файлов, Получение списка системных файлов Если поле `type` имеет значение `tts`, то в качестве значения принимается текст для синтезирования его в голосовое сообщение. Длина TTS сообщения регулируется тарифным планом и установленным лимитом.

Параметры ответа

Название	Тип	Обязательный	Описание
call_session_id	number	да	Уникальный идентификатор сессии звонка

Пример запроса

Копировать

{
 "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"
  }
 }
}

Пример ответа

Копировать

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

Список возвращаемых ошибок

Текст ошибки	Код ошибки	Мнемоника	Описание
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`	Длина сообщения превысила допустимое ограничение, установленное тарифным планом
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`	Если используется виртуальный номер не принадлежащий клиенту
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`	У сотрудника нет активных номеров в настройках сотрудника
Parameter `contact` can not contain own virtual phone number	-32602	`own_virtual_phone_number_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`

См. также раздел "Список ошибок общих для всех методов"

Оборудование

Start employee call

Вызов на сотрудника

Параметры запроса

Параметры ответа

Пример запроса

Пример ответа

Список возвращаемых ошибок