Start scenario call - Call API

Вызов по сценарию

Метод	`start.scenario_call`
Версия API	v4.0
Описание	Метод создает звонок согласно настроенному сценарию. Для использования метода достаточно одного виртуального номера и N сценариев.
Вернуться к списку методов

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

Название		Тип	Обязательный	Допустимые значения	Описание
access_token		string	да		Ключ сессии аутентификации
virtual_phone_number		string	да		Виртуальный номер, арендуемый клиентом. Формат номера должен соответствовать международному стандарту E.164 (например, `74993720692`). Всегда используется в качестве номера звонящего при звонке на номер, указанный в параметре `contact`. Используется в качестве номера звонящего при звонке на сотрудника, если в сценарии в операции "Переадресация" установлена настройка "Показывать при звонке" в значение "Номер услуги". Виртуальные номера можно получить с помощью DATA API метода - Получение списка виртуальных номеров
virtual_phone_usage_rule		string	нет		Правило использования виртуального номера. Позволяет динамически менять виртуальный номер при звонке. Если подходящий номер, удовлетворяющий выбранному правилу, не найден, то будет использован номер, указанный в параметре `virtual_phone_number`. Допустимые значения параметра: `fixed` - Фиксированный `fixed_for_numa` - Фиксированный для абонента `random` - Случайный `regional_random` - Региональный случайный `regional_fixed_for_numa` - Региональный фиксированный для абонента По умолчанию используется правило `Фиксированный`. Остальные правила доступны при подключённом компоненте `Автоматическое управление номерами`.
external_id		string	нет		Уникальный идентификатор, который может быть использован для связи события звонка с внешней системой.
dtmf_string		string	нет	0-9, *, #	Задаёт DTMF, который будет отправлен абоненту, заданному в параметре `contact`. С помощью символа `.` = '1 секунда' можно задать таймаут по истечению которого символ DTMF будет отправлен. Пример: `.12.1..4`, т.е через 1 секунду будет отправлена цифра 12, далее через 1 секунду будет отправлена цифра 1 и через 2 секунды цифра 4.
contact		string	да		Номер абонента на который совершается вызов. Формат номера должен соответствовать международному стандарту E.164 (например, `79091234567`). В качестве номера может быть так же указан SIP номер сотрудника. Если не задан параметр `contact_message`, то абоненту будет проигрываться системная мелодия - `Музыка переадресации (dialing_music)` Внутренние номера сотрудников не поддерживаются.
first_call		string	да	contact, employee	Определяет номер, на который нужно дозвониться в первую очередь: `employee` - сотрудник; `contact` - вызываемая сторона (обычно клиент);
switch_at_once		boolean	нет	true, false	Значение по умолчанию `false`. Если параметр `first_call` имеет значение `employee`, задано сообщение сотруднику в сценарии и задан параметр `contact_message`, то: Первый звонок совершается сотруднику из сценария; Сотрудник после поднятия трубки слушает сообщение до конца и только потом совершается звонок на абонента заданного в параметре `contact`; Во время дозвона до `contact`, сотрудник слушает системную мелодию - `Музыка переадресации (dialing_music)`; После ответа абонента из параметра `contact`, произойдет разговор с сотрудником, если `switch_at_once` имеет значение `true`; После ответа абонента из параметра `contact`, он дослушает сообщение до конца, если `switch_at_once` имеет значение `false` и далее произойдет разговор с сотрудником. Если параметр `first_call` имеет значение `contact`, задан параметр `contact_message` и задано сообщение сотруднику в сценарии, то: В первую очередь звонок совершается абоненту из параметр `contact`); Абонент из параметра `contact` после поднятия трубки начинает слушать сообщение и в это же время совершается звонок на сотрудника из сценария; После поднятия трубки сотрудником проигрывание сообщения будет прервано для абонента из параметра `contact` и далее состоится разговор, если параметр `switch_at_once` имеет значение `true`; После поднятия трубки сотрудником сообщение будет проиграно до конца обоим и далее состоится разговор, если параметр `switch_at_once` имеет значение `false`; Если у кого-то проигрывание сообщения закончилось раньше, то он слушает системную мелодию - `Музыка переадресации (dialing_music)`. Если в параметре `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" (см. раздел коды ошибок).
scenario_id		number	да		Уникальный идентификатор сценария, который может быть получен с помощью DATA API - Получение списка сценариев.
direction		string	нет	in, out	Значение по умолчанию `in`. Определяет направление звонка `in` - Входящий звонок, `out` - Исходящий звонок.
Сообщение для проигрывания абоненту, который задан в параметре `contact`
contact_message		object	нет		Определяет параметры сообщения, которое необходимо проиграть абоненту заданному в параметре `contact`. После окончания проигрывания сообщения, будет проигрываться покругу системная мелодия - `Музыка переадресации (dialing_music)`
	type	string	да	media, tts	Определяет тип сообщения. `media` - файл или `tts` - текст для услуги синтеза речи Text-to-Speech.
	value	string	да		Если поле `type` имеет значение `media`, то в качестве значения принимается идентификатор файла для проигрывания. Файл для проигрывания может быть системным или пользовательским. Идентификатор файла для проигрывания можно получить с помощью DATA API - Получение списка пользовательских файлов, Получение списка системных файлов Если поле `type` имеет значение `tts`, то в качестве значения принимается текст для синтезирования его в голосовое сообщение. Длина TTS сообщения регулируется тарифным планом и установленным лимитом.
Сообщение для проигрывания сотруднику
employee_message		object	нет		Определяет параметры сообщения, которое необходимо проиграть сотруднику. Сообщение сотруднику, которое задано в сценарии приоритетнее, сообщения из параметра `employee_message`. Но проигрываться будут оба сообщения по очереди. После окончания проигрывания сообщения, будет проигрываться покругу сообщение из параметра `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.scenario_call",
  "id": "req1",
  "params": {
    "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
    "virtual_phone_number": "74993720692",
    "external_id": "34rty567",
    "dtmf_string": "..1.2.3",
    "contact": "79260000000",
    "first_call": "employee",
    "switch_at_once": false,
    "scenario_id": 23456,
    "direction": "in",
    "contact_message": {
      "type": "media",
      "value": "237"
    },
    "employee_message": {
      "type": "media",
      "value": "237"
    }
  }
}

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

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

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

Текст ошибки	Код ошибки	Мнемоника ошибки	Описание
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`	Если используется виртуальный номер не принадлежащий клиенту
Scenario with id {`scenario_id`} not found	-32602	`scenario_not_found`
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	-32602	`contact_in_blacklist`
The character encoding must be UTF-8	-32602	`character_encoding_not_allowed`

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