Продукты Решения Тарифы Партнерам
Клиентам
Получить консультацию
Связаться
Skip to content

Start vnumber call

Вызов на виртуальный номер

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

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

Название Тип Обязательный Допустимые значения Описание
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.
direction string нет in, out Значение по умолчанию in.
Определяет направление звонка in - Входящий звонок, out - Исходящий звонок.
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" (см. раздел коды ошибок).
Сообщение для проигрывания абоненту, который задан в параметре 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 сообщения регулируется тарифным планом и установленным лимитом.

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

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

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

Копировать
{
 "jsonrpc": "2.0",
 "method": "start.vnumber_call",
 "id": "req1",
 "params": {
  "access_token": "2fRN4g217ca0b4224a67988aff3e584f91964a692045415f36fa66146f5a3c1ae1f6093d",
  "virtual_phone_number": "74993720692",
  "external_id": "34rty567",
  "dtmf_string": "..1.2.3",
  "direction": "in",
  "contact": "79260000000",
  "first_call": "employee",
  "switch_at_once": false,
  "show_virtual_phone_number": true,
  "contact_message": {
   "type": "media",
   "value": "237"
  }
 }
}

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

Копировать
{
 "jsonrpc": "2.0",
 "id": "req1",
 "result": {
  "data": {
   "call_session_id": 123467589
  }
 }
}

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

Текст ошибки Код ошибки Мнемоника ошибки Описание
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 Если используется виртуальный номер не принадлежащий клиенту
Virtual phone number does not have a scenario -32007 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

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

Полезные кейсы, статьи и исследования от экспертов UIS
Подписаться
Нажимая кнопку вы подтверждаете, что согласны получать рассылку
Вы успешно подписаны на новости!
Спасибо за обращение
Понятно