События Asterisk: входящий звонок, текст и ответ

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

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

События Asterisk: входящий звонок, текст и ответ

Передавайте из Asterisk начало звонка, распознанный текст, ответ и завершение. TesLab использует эти события для карточки звонка и подстановки сведений в обращение. Сам HTTP-запрос не устанавливает голосовое соединение: для разговора требуется настроенная телефония.

Как проходит один звонок

  1. При поступлении вызова отправьте action=incoming с номером звонящего, линией и строковым uid.
  2. Если имеется распознанный текст, передайте action=incomingText с тем же uid, номером и линией.
  3. Когда сотрудник ответит, отправьте event=NOTIFY_ANSWER. Ответивший добавочный укажите в internal.
  4. После окончания разговора отправьте event=NOTIFY_END. Ответ и завершение являются разными событиями.

Используйте один способ передачи каждого события. Если уже работают события через AMI или отдельный HTTP hook, согласуйте их с этим входом: разные идентификаторы одного разговора не объединяются автоматически.

Телефон: событие и звук различаются. Согласуйте один идентификатор вызова и правильный добавочный.
Схема различает события и голосовое соединение. Для завершения передайте NOTIFY_END либо используйте согласованный канал AMI или HTTP hook.
Учебная карточка входящего звонка с указателями имени абонента, линии и кнопки Заявка
1. Имя и номер звонящего. 2. Линия, на которую поступил вызов. 3. Кнопка «Заявка», если действие настроено для линии.

Что настроить перед обменом

Создайте линию Asterisk и назначьте сотрудников или отделы, которым нужны уведомления. Значение trunk должно совпадать с маршрутом этой линии. Оно может быть номером или именем, например support-line. Не подставляйте произвольное имя, которого нет в настройках.

Для событий используется POST /api/system/ats/asterisk на сервере вашей организации. Передавайте ключ этого метода в заголовке Access-Code, JSON в теле и заголовок Out: json. Ключ другого АТС-входа не подходит. Не публикуйте рабочий ключ в переписке или снимках экрана.

В настройке линии доступна подсказка для дайлплана. Она показывает только начало звонка, поэтому остальные события требуется добавить отдельно. Сохраняйте ограничения ожидания CURLOPT(conntimeout) и CURLOPT(httptimeout). Значения имени, номера, линии и UID в form-запросе кодируйте через URIENCODE: символ & внутри имени не должен становиться новым параметром.

Пример подсказки вставляйте в согласованное место существующего дайлплана. Не заменяйте им целиком контекст from-trunk. Настройка AMI описана в статье «Уведомления о звонках: интеграция станции и AMI».

Поля запросов

ПолеЧто передавать
actionincoming или incomingText. Не передавайте одновременно с event.
eventNOTIFY_ANSWER или NOTIFY_END. Регистр значений важен.
uidОбязательный строковый идентификатор одного разговора, одинаковый для всех его событий. Допустимы латинские буквы, цифры и знаки _ . : @ + -, длина до 128 символов. Десятичный UNIQUEID также передавайте в кавычках.
trunkЛиния для начала и текста звонка.
destinationТа же линия для ответа и завершения.
phoneНомер звонящего для начала и текста. Не номер линии. Обычные записи российского номера с 8, 7 и +7 приводятся к одному виду.
tnameНеобязательное имя от станции. Показывается, если TesLab не нашёл собственную подпись абонента. Название линии выводится отдельно.
messТекст для incomingText, непустая строка до 20000 символов. Это не аудиофайл.
internalДобавочный ответившего сотрудника. Без него нельзя точно назвать ответившего и исключить его из уведомления об ответе коллеги.
serverИдентификатор станции, одинаковый во всех событиях разговора. При совместной работе с AMI или hook используйте одно согласованное значение для начала, текста, ответа и завершения.
dispositionНеобязательный итог при завершении: answered, busy, cancel, no answer, no_answer, noanswer или failed. Передавайте фактический исход станции.

Начало и текст звонка

Во всех примерах ниже используется один учебный разговор. Заголовки:

POST /api/system/ats/asterisk
Access-Code: YOUR_ASTERISK_KEY
Content-Type: application/json
Out: json

Начало:

{"action":"incoming","trunk":"support-line",
 "phone":"70000000000","uid":"1787070849.762581",
 "tname":"Учебный абонент","server":"pbx.training.invalid"}

Распознанный текст того же звонка:

{"action":"incomingText","trunk":"support-line",
 "phone":"70000000000","uid":"1787070849.762581",
 "mess":"Не работает освещение в кабине, подъезд 2",
 "server":"pbx.training.invalid"}

Текст дополняет контекст разговора. TesLab может попытаться определить адрес, подъезд, лифт и проблему, но распознавание не гарантирует правильного выбора объекта. Перед сохранением обращения проверьте подставленные сведения.

Учебная карточка с распознанной репликой и отдельным указателем кнопки Заявка
1. Переданный текст разговора. 2. Переход к оформлению заявки. Само получение текста ещё не создаёт диспетчерскую заявку.

Ответ и завершение

Сотрудник с добавочным 105 ответил:

{"event":"NOTIFY_ANSWER","destination":"support-line",
 "uid":"1787070849.762581","internal":"105",
 "server":"pbx.training.invalid"}

У остальных адресатов линии снимается уведомление о входящем с причиной ответа. Если соответствующая запись журнала уже создана адресным hook или AMI, она отмечается принятой. Сам разговор этим событием не завершается.

Разговор закончился:

{"event":"NOTIFY_END","destination":"support-line",
 "uid":"1787070849.762581","disposition":"answered",
 "internal":"105","server":"pbx.training.invalid"}

Не отправляйте answered только потому, что запрос успешно дошёл. Если станция не сообщает исход, не выдумывайте его. Для журнала с указанной станцией значение server должно совпадать с источником начала.

Как получить контекст звонка

Авторизованный клиент TesLab может прочитать свежие сведения по номеру звонящего. Для этого используется обычная авторизация сотрудника, а не передача ключа АТС пользователю:

POST /api/system/ats/asterisk
Content-Type: application/json
Out: json

{"ats-call":"70000000000","uid":"1787070849.762581"}

В ответе могут быть id, action, from, phone, name, mess и найденные сведения об объекте. Сверяйте id с текущим разговором. Доступ есть у адресата звонка или администратора.

Контекст сохраняется ненадолго: после 180 секунд без обновления он не возвращается. Поле uid при чтении необязательно, но без него при нескольких доступных разговорах с одного номера ответ будет пустым. Пустой ответ также возможен при отсутствии контекста или доступа. Это не подтверждение отсутствия самого звонка.

Проверка и устранение ошибок

  1. Проверьте адрес сервера, ключ метода, существование линии и её адресатов.
  2. Выполните учебный звонок и последовательно проверьте начало, текст, ответ и завершение с одним UID.
  3. Сопоставьте карточку, контекст и журнал. Начало через этот вход само по себе не создаёт строку журнала: для неё требуется настроенный адресный hook или AMI.
  4. Проверьте заблокированный номер. Начало и текст не должны рассылаться; ответ содержит is_block:true и accepted:false.
  5. Отдельно проверьте реальный разговор. Уведомление, HTTP-ответ и распознанный текст не подтверждают работу микрофона, звука или SIP-соединения.

Обычное подтверждение события содержит ok:true, accepted:true и тот же строковый id. Для начала оно может прийти до окончания доставки уведомлений. При неверном событии, типе или обязательном поле возвращается ошибка 400, при неизвестной линии 404, при отказе авторизации 403. Не считайте любой HTTP200 доказательством появления карточки у сотрудника.

При повторе после сетевого сбоя сохраняйте прежний UID. Не назначайте новый идентификатор каждому повторному запросу. Все события одного разговора должны использовать одинаковые линию и источник станции.