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`

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