Подключение Voximplant

Инструкция для администратора организации (право manage_integrations). После настройки входящие звонки на номер, арендованный в Voximplant, обслуживает голосовой агент.

Ориентировочное время настройки — до 30 минут.

Что понадобится

Аккаунт Voximplant с правом создавать приложения.
Номер телефона, арендованный в Voximplant (формат E.164, например +74951234567).
Созданный голосовой агент.
В платформе — доступ к разделу Интеграции (вкладки Номера телефонов и SIP).

Входящие звонки

1. Зарегистрируйте номер

Откройте Интеграции → Номера телефонов.
Добавьте номер, арендованный в Voximplant, в формате E.164.

Транк можно создать только с номерами, зарегистрированными в вашей организации. Один номер может принадлежать только одной организации и входить только в один входящий транк. Регистрация номера в платформе не арендует его и не настраивает маршрутизацию в Voximplant.

2. Создайте входящий транк

Откройте Интеграции → SIP → Входящие транки и нажмите создание транка.
Укажите название транка и выберите хотя бы один номер из шага 1.
Укажите логин (например, vox-myproject) и пароль (не короче 16 символов). Кнопка Сгенерировать заполнит пароль случайным значением прямо в браузере.
Для базового сценария оставьте шифрование медиа выключенным. Поле Разрешённые IP можно оставить пустым: логин и пароль всё равно обязательны. Если задаёте IP/CIDR, разрешите адреса, с которых Voximplant отправляет SIP-вызовы.
Сохраните.

Сохраните пароль

Скопируйте пароль до сохранения транка и сохраните в надёжном месте — он понадобится для сценария Voximplant. После закрытия формы платформа пароль не показывает и не возвращает; если он утерян — пересоздайте транк и обновите сценарий.

3. Создайте правило маршрутизации

Откройте Интеграции → SIP → Правила маршрутизации.
Укажите название и выберите тип Individual (новая комната на звонок), чтобы каждый звонок получил отдельную сессию.
В фильтре по транкам выберите входящий транк из шага 2.
Выберите активного голосового агента вашей организации, который будет отвечать на звонки (обязательно), и сохраните правило.
При необходимости включите Скрывать номер: номер звонящего не передаётся в переменную {{caller_number}} и поле номера звонящего в сессии агента. Это не настройка скрытия номера в истории самого Voximplant.

4. Настройте Voximplant

В панели Voximplant создайте приложение (Applications → Create).
В платформе нажмите кнопку Сценарий VoxEngine у транка и скопируйте текст.
В приложении Voximplant создайте сценарий, вставьте текст и замените <PASSWORD> на пароль, который вы задали в шаге 2.
Создайте правило (Routing → Rule): шаблон — ваш номер (например, \+74951234567 или .*), сценарий — из пункта 3.
Привяжите арендованный номер к приложению и убедитесь, что вызовы на него попадают под созданное правило.

Рабочий входящий сценарий

Кнопка Сценарий VoxEngine подставляет SIP-домен из конфигурации платформы и логин выбранного транка. Пароль API не возвращает: в тексте всегда остаётся <PASSWORD>. В рабочем примере домен — sip.lia.chat; для другого окружения используйте домен из сгенерированного сценария.

const SIP_DOMAIN = "sip.lia.chat";
const AUTH_USER = "<TRUNK_AUTH_USERNAME>";
const AUTH_PASSWORD = "<PASSWORD>";

let voxSessionId = "";

VoxEngine.addEventListener(AppEvents.Started, (e) => {
  voxSessionId = String(e.sessionId);
});

VoxEngine.addEventListener(AppEvents.CallAlerting, (e) => {
  const inbound = e.call;
  const sipCall = VoxEngine.callSIP(`sip:${e.destination}@${SIP_DOMAIN}`, {
    callerid: e.callerid,
    displayName: e.callerid,
    authUser: AUTH_USER,
    password: AUTH_PASSWORD,
    headers: { "X-Vox-Session-Id": voxSessionId },
  });
  sipCall.addEventListener(CallEvents.Failed, (ev) => {
    Logger.write(`agent-builder SIP failed: code=${ev.code} reason=${ev.reason}`);
  });
  VoxEngine.easyProcess(inbound, sipCall);
});

AUTH_USER и AUTH_PASSWORD — учётные данные входящего транка платформы, а не аккаунта Voximplant. e.destination должен совпадать с номером в транке в формате E.164; проверьте это значение в истории звонка, если вызов не маршрутизируется.

Сценарий передаёт номер звонящего через callerid и displayName. easyProcess отвечает на входящий вызов после подключения SIP-вызова, соединяет аудио и завершает сессию при окончании любого из вызовов. Параметры описаны в справочнике CallSIPParameters, обработка вызовов — в руководстве Voximplant.

Заголовок X-Vox-Session-Id передаёт e.sessionId для сопоставления звонков: при создании входящего транка платформа настраивает его преобразование в атрибут участника LiveKit vox.session_id.

5. Тестовый звонок

Позвоните на номер с любого телефона. Агент должен ответить приветствием. Звонок появится в журнале сессий агента с направлением «входящий».

В промпте агента доступны переменные {{caller_number}} (номер звонящего) и {{called_number}} (ваш номер).

Диагностика

Симптом	Причина и решение
При создании транка ошибка 403 «Phone number … is not registered to this organization»	Номер не зарегистрирован. Добавьте его на странице Номера телефонов и повторите. Если номер уже занят другой организацией — обратитесь в поддержку.
409 при создании входящего транка	Номер уже используется другим входящим транком. Используйте существующий транк или удалите прежний перед пересозданием.
422 при создании входящего транка	Логин и пароль обязательны, пароль не короче 16 символов. Используйте кнопку Сгенерировать.
422 при создании правила маршрутизации	Не выбран голосовой агент.
Звонок не доходит, в логе сценария Voximplant `code=401` или `407`	Проверьте логин транка и пароль в сценарии. Убедитесь, что `<PASSWORD>` заменён на пароль, заданный при создании транка. Если пароль утерян — пересоздайте транк и обновите сценарий. Лог: Voximplant → приложение → History → лог сессии.
Сценарий запускается, но входящий звонок не маршрутизируется	Проверьте `e.destination`, номер в транке и SIP-домен в сценарии. Номер назначения должен совпадать с зарегистрированным номером.
Звонок доходит, но агент не отвечает	Проверьте, что правило маршрутизации создано для нужного транка и в нём выбран существующий агент. Если агента удалили, его правила удаляются — создайте правило заново.

Что понадобится​

Входящие звонки​

1. Зарегистрируйте номер​

2. Создайте входящий транк​

3. Создайте правило маршрутизации​

4. Настройте Voximplant​

Рабочий входящий сценарий​

5. Тестовый звонок​

Диагностика​