Голосовой робот: обмен сообщениями с АТС

В документации мы постарались ответить на частые вопросы по работе TesLab, с которыми сталкиваются пользователи.
Если Вы не нашли ответ на свой вопрос, напишите нам.

Личный кабинет

Голосовой робот: обмен сообщениями с АТС

Голосовой робот принимает уже распознанный текст разговора, находит адрес, подъезд, лифт и описание проблемы. Он помогает уточнить обращение и передать сведения диспетчеру. Сам метод не слушает аудио и не регистрирует основную диспетчерскую заявку.

В этой статье

Что подготовить

Для обмена используется метод /api/maintenance/requests/robot на вашем сервере TesLab. Адрес сервера и общие правила запросов описаны в статье API TesLab: адрес сервера и первый запрос. Ключ доступа к методу передавайте согласованным для подключения способом, например в заголовке Access-Code. Не включайте настоящий ключ в примеры и снимки экрана.

  • Настройте линию Asterisk и сотрудников, которым должны поступать уведомления.
  • Подготовьте распознавание речи на стороне телефонного сценария. В TesLab передаётся текст каждой новой реплики.
  • Для анализа нужна действующая лицензия диспетчерской службы и доступ сервера к сервису распознавания.
  • Убедитесь, что обслуживаемые адреса, подъезды и лифты заведены корректно. Если найдено несколько подходящих объектов, робот не должен угадывать один из них.

Настройка телефонного сценария и синтеза речи: Робот-диспетчер: АТС и синтез речи. Передача событий самой станции: События Asterisk: входящий звонок, текст и ответ.

Как провести один разговор

  1. Передайте CallNotification, чтобы сообщить о входящем звонке. Проверьте, не вернулся ли is_block:true.
  2. Отправьте первую распознанную реплику с action:"start".
  3. Прочитайте action, question и info. Если нужны уточнения, задайте соответствующий вопрос абоненту.
  4. Передайте следующую реплику с action:"request". В more.info скопируйте весь info из последнего успешного ответа.
  5. При 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 не подтверждает создание заявки и не содержит её номера. Для регистрации из внешней системы используйте отдельный проверенный сценарий из статьи Диспетчерские заявки из внешней системы. Проверка договора обслуживания и подтверждение регистрации выполняются на этом отдельном шаге.

Что передавать в запросе

ПолеЧто означает
actionCallNotification, start или request. Неизвестное действие отклоняется.
trunkНомер или именованный идентификатор существующей линии Asterisk. Например, support-line. Имя линии не превращается в телефонный номер.
phoneНомер звонящего. Для одного разговора используйте один и тот же номер. Телефон приводится к единому виду.
uidТочный идентификатор разговора строкой, включая все цифры после точки. Не передавайте его JSON-числом и не округляйте.
serverАдрес источника Asterisk. Во всех шагах одного разговора передавайте одинаковое значение. Если это поле используется и в других событиях станции, значения тоже должны совпадать.
textТолько очередная распознанная реплика, обязательна для start и request. Не отправляйте заново всю историю. Максимум 20 000 символов.
more.infoПолный info из предыдущего ответа, обязателен для request. Не добавляйте и не меняйте поля.
showMoretrue запрашивает читаемые названия найденного адреса и лифта в отдельном блоке ответа more. Работает для первой реплики и уточнений.
NotSendInfotrue включает отдельный ручной анализ текста без телефонных уведомлений. В таком режиме phone, trunk и uid не требуются. Для обычного голосового разговора этот флаг не включайте.

В голосовом режиме обязательны phone, trunk и uid. Проверка чёрного списка действует до анализа и отправки контекста на всех голосовых шагах. При is_block:true прекратите этот сценарий. Ручной анализ без телефона не проверяет телефонный чёрный список.

Как читать результат

Поле ответаКак использовать
ok, robotVУспешный результат анализа содержит ok:true и robotV:1. Одного успешного HTTP-запроса недостаточно для обещания зарегистрированной заявки.
questionМассив недостающих сведений: address, front, elevator, problem. В обычном диалоге вопросы строятся по итоговому найденному объекту, а не по наличию слова в тексте.
info.addressID обслуживаемого адреса. Это не ID дома в общем адресном справочнике. 0 означает, что адрес не определён однозначно.
info.frontНайденный подъезд выбранного адреса. -1 означает, что подъезд не определён.
info.elevatorID конкретного лифта, а не его номер или буква. 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.

Как разобрать сообщение вручную

В форме добавления заявки можно разобрать готовый текст сообщения без телефонного разговора.

  1. Нажмите кнопку с роботом внизу формы добавления заявки.
  2. В окне «Распознать сообщение» вставьте адрес и описание ситуации. Нажмите «Распознать».
  3. Проверьте сообщение о результате. Полный и частичный результат отличаются. При необходимости разбора диспетчером данные не подставляются как готовая заявка.
  4. Проверьте адрес, подъезд, конкретный лифт и содержание. Заполните оставшиеся поля и сохраните заявку обычной кнопкой формы.
Кнопка ручного распознавания в форме добавления заявки
1. Кнопка с роботом открывает окно ручного анализа сообщения.
Текст сообщения и кнопка Распознать
1. Вставьте исходный текст. 2. Нажмите «Распознать». Во время анализа повторное нажатие заблокировано.
Частично заполненная заявка с невыбранным лифтом
1. В этом примере лифт ещё не выбран. Адрес, подъезд и описание уже подставлены, но перед сохранением нужен конкретный объект.

При ошибке анализа окно с исходным текстом остаётся открытым. Его можно исправить и отправить ещё раз. Отмена закрывает окно; запоздалый ответ не должен менять форму. Распознанное застревание сопровождается предупреждением и выбором типа заявки «Застревание», но место происшествия всё равно нужно проверить.

Ошибки и проверка подключения

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

Перед включением подготовьте учебный разговор: первая неполная реплика, уточнение подъезда и лифта, повтор последнего запроса, застревание после обычной проблемы, неоднозначный адрес и недоступность анализа. Для каждого случая проверьте результат API, отображение у диспетчера и отдельное подтверждение регистрации заявки.

Связанные статьи