Голосовой робот: обмен сообщениями с АТС
Голосовой робот принимает уже распознанный текст разговора, находит адрес, подъезд, лифт и описание проблемы. Он помогает уточнить обращение и передать сведения диспетчеру. Сам метод не слушает аудио и не регистрирует основную диспетчерскую заявку.
В этой статье
Что подготовить
Для обмена используется метод /api/maintenance/requests/robot на вашем сервере TesLab. Адрес сервера и общие правила запросов описаны в статье API TesLab: адрес сервера и первый запрос. Ключ доступа к методу передавайте согласованным для подключения способом, например в заголовке Access-Code. Не включайте настоящий ключ в примеры и снимки экрана.
- Настройте линию Asterisk и сотрудников, которым должны поступать уведомления.
- Подготовьте распознавание речи на стороне телефонного сценария. В TesLab передаётся текст каждой новой реплики.
- Для анализа нужна действующая лицензия диспетчерской службы и доступ сервера к сервису распознавания.
- Убедитесь, что обслуживаемые адреса, подъезды и лифты заведены корректно. Если найдено несколько подходящих объектов, робот не должен угадывать один из них.
Настройка телефонного сценария и синтеза речи: Робот-диспетчер: АТС и синтез речи. Передача событий самой станции: События Asterisk: входящий звонок, текст и ответ.
Как провести один разговор
- Передайте
CallNotification, чтобы сообщить о входящем звонке. Проверьте, не вернулся лиis_block:true. - Отправьте первую распознанную реплику с
action:"start". - Прочитайте
action,questionиinfo. Если нужны уточнения, задайте соответствующий вопрос абоненту. - Передайте следующую реплику с
action:"request". Вmore.infoскопируйте весьinfoиз последнего успешного ответа. - При
Stuckили необходимости участия оператора передайте обращение диспетчеру. ПриtoQueueпроверьте сведения и выполните отдельный шаг регистрации заявки.

Пример уведомления о входящем звонке:
{
"action": "CallNotification",
"trunk": "support-line",
"phone": "70000000000",
"uid": "1787070849.762581",
"server": "pbx.training.invalid"
}
Первая реплика того же разговора:
{
"action": "start",
"trunk": "support-line",
"phone": "70000000000",
"uid": "1787070849.762581",
"server": "pbx.training.invalid",
"text": "Учебная улица Примерная, дом 10. Не работает освещение в лифте.",
"showMore": true
}
Продолжение удобно собирать программно. Здесь previousReply является последним успешным ответом сервера, а call содержит неизменные поля телефонного разговора:
const nextRequest = {
...call,
action: "request",
text: "Первый подъезд, левый лифт",
more: { info: previousReply.info },
showMore: true
};
toQueue не подтверждает создание заявки и не содержит её номера. Для регистрации из внешней системы используйте отдельный проверенный сценарий из статьи Диспетчерские заявки из внешней системы. Проверка договора обслуживания и подтверждение регистрации выполняются на этом отдельном шаге.
Что передавать в запросе
| Поле | Что означает |
|---|---|
action | CallNotification, start или request. Неизвестное действие отклоняется. |
trunk | Номер или именованный идентификатор существующей линии Asterisk. Например, support-line. Имя линии не превращается в телефонный номер. |
phone | Номер звонящего. Для одного разговора используйте один и тот же номер. Телефон приводится к единому виду. |
uid | Точный идентификатор разговора строкой, включая все цифры после точки. Не передавайте его JSON-числом и не округляйте. |
server | Адрес источника Asterisk. Во всех шагах одного разговора передавайте одинаковое значение. Если это поле используется и в других событиях станции, значения тоже должны совпадать. |
text | Только очередная распознанная реплика, обязательна для start и request. Не отправляйте заново всю историю. Максимум 20 000 символов. |
more.info | Полный info из предыдущего ответа, обязателен для request. Не добавляйте и не меняйте поля. |
showMore | true запрашивает читаемые названия найденного адреса и лифта в отдельном блоке ответа more. Работает для первой реплики и уточнений. |
NotSendInfo | true включает отдельный ручной анализ текста без телефонных уведомлений. В таком режиме phone, trunk и uid не требуются. Для обычного голосового разговора этот флаг не включайте. |
В голосовом режиме обязательны phone, trunk и uid. Проверка чёрного списка действует до анализа и отправки контекста на всех голосовых шагах. При is_block:true прекратите этот сценарий. Ручной анализ без телефона не проверяет телефонный чёрный список.
Как читать результат
| Поле ответа | Как использовать |
|---|---|
ok, robotV | Успешный результат анализа содержит ok:true и robotV:1. Одного успешного HTTP-запроса недостаточно для обещания зарегистрированной заявки. |
question | Массив недостающих сведений: address, front, elevator, problem. В обычном диалоге вопросы строятся по итоговому найденному объекту, а не по наличию слова в тексте. |
info.address | ID обслуживаемого адреса. Это не ID дома в общем адресном справочнике. 0 означает, что адрес не определён однозначно. |
info.front | Найденный подъезд выбранного адреса. -1 означает, что подъезд не определён. |
info.elevator | ID конкретного лифта, а не его номер или буква. 0 означает, что лифт не выбран. |
info.problem, info.problemType | Описание и категория проблемы. Уточнение может изменить ранее распознанное описание. |
info.last_mess, info.lastMess | Совместимые имена одной накопленной истории, без повторного добавления прежних реплик. Сохраняйте оба поля как получены. |
info.stateToken | Служебная подпись состояния. Передавайте её только вместе с неизменённым info следующего шага. Не разбирайте и не редактируйте значение. |
more | Читаемые пояснения по объекту при showMore:true. Этот блок не заменяет info и не является состоянием для следующей реплики. |
| Исход | Следующее действие |
|---|---|
Нет action, есть вопросы | Уточните перечисленные сведения и продолжите через request. |
toQueue | Найдены адрес, подъезд, лифт и описание проблемы. Передайте их дальше и отдельно зарегистрируйте заявку. |
Stuck | Распознано застревание. Сразу подключите диспетчера и проверьте место происшествия. Этот исход возможен и после уточнения, даже если раньше распозналась другая проблема. Определение застревания не означает, что адрес и лифт уже найдены. |
operator | Нужен разбор диспетчером. В том числе так обрабатывается обращение сразу о нескольких лифтах, чтобы не выбрать один произвольно. |
nonsense, request_null, intercom | Специальные исходы анализа. Не считайте их готовой заявкой. Обработайте согласованной ветвью телефонного сценария или передайте диспетчеру. |
Если на одной улице несколько домов с одинаковым номером в разных населённых пунктах, уточните город. Сохраняйте букву дома и корпус в произнесённом адресе. Непонятное обозначение лифта или совпадение нескольких объектов требует уточнения.
Состояние, история и повтор запроса
Состояние связано с номером звонящего, линией, точным uid и источником станции. Не переносите info между разговорами и не формируйте его вручную. Подмена ID, служебных полей или подписи отклоняется. Подпись действует до 24 часов; при её истечении или утрате состояния передайте разговор диспетчеру.
Шаги отправляйте последовательно. При потере ответа повторите последний запрос без изменений, с тем же текстом и тем же предыдущим info. Последний одинаковый запрос возвращает сохранённый результат без нового анализа и повторного добавления реплики. Когда получен следующий результат, прежнее состояние уже нельзя использовать для другой реплики. Не запускайте новый start с изменённым текстом поверх начатого разговора с тем же идентификатором.
Не отправляйте параллельно два разных уточнения одного разговора. Если сервер сообщает о конфликте состояния, не исправляйте подпись и не пытайтесь угадать недостающие поля. Проверьте, не пришёл ли ответ на предыдущий запрос, либо подключите диспетчера.
Контекст звонка отправляется сотрудникам выбранной линии. Его кратковременная подстановка в интерфейсе ограничена по времени и не заменяет сохранённое внешней программой состояние диалога. Ограничения телефонного контекста описаны в статье о событиях Asterisk.
Как разобрать сообщение вручную
В форме добавления заявки можно разобрать готовый текст сообщения без телефонного разговора.
- Нажмите кнопку с роботом внизу формы добавления заявки.
- В окне «Распознать сообщение» вставьте адрес и описание ситуации. Нажмите «Распознать».
- Проверьте сообщение о результате. Полный и частичный результат отличаются. При необходимости разбора диспетчером данные не подставляются как готовая заявка.
- Проверьте адрес, подъезд, конкретный лифт и содержание. Заполните оставшиеся поля и сохраните заявку обычной кнопкой формы.



При ошибке анализа окно с исходным текстом остаётся открытым. Его можно исправить и отправить ещё раз. Отмена закрывает окно; запоздалый ответ не должен менять форму. Распознанное застревание сопровождается предупреждением и выбором типа заявки «Застревание», но место происшествия всё равно нужно проверить.
Ошибки и проверка подключения
| Ситуация | Что проверить |
|---|---|
| Неверные параметры, код 400 | Действие, строковые типы uid и text, обязательные поля, структуру more.info. Не передавайте массив вместо текста. |
| Нет доступа или лицензии, код 403 | Ключ метода и подключение диспетчерской службы. Поля return_request, whoadd и num не относятся к внешнему обмену робота и запрещены. |
| Не найдена линия, код 404 | Совпадение trunk с существующей линией Asterisk. |
| Конфликт состояния, код 409 | Полный неизменённый info, последовательность шагов, источник и идентификатор разговора. Если изменился каталог объектов, ранее выбранный объект тоже может потребовать повторной проверки. |
| Реплика не распознана, код 502 | Доступность анализа и текст сообщения. Повторите последний запрос либо передайте разговор диспетчеру. Такой отказ не означает готовность заявки. |
| Нет карточки или контекста у диспетчера | Настройки линии, её работающих сотрудников и доставку событий. Успех анализа сам по себе не подтверждает, что сотрудник увидел сообщение. |
Перед включением подготовьте учебный разговор: первая неполная реплика, уточнение подъезда и лифта, повтор последнего запроса, застревание после обычной проблемы, неоднозначный адрес и недоступность анализа. Для каждого случая проверьте результат API, отображение у диспетчера и отдельное подтверждение регистрации заявки.