События Asterisk: входящий звонок, текст и ответ
Передавайте из Asterisk начало звонка, распознанный текст, ответ и завершение. TesLab использует эти события для карточки звонка и подстановки сведений в обращение. Сам HTTP-запрос не устанавливает голосовое соединение: для разговора требуется настроенная телефония.
Как проходит один звонок
- При поступлении вызова отправьте
action=incomingс номером звонящего, линией и строковымuid. - Если имеется распознанный текст, передайте
action=incomingTextс тем жеuid, номером и линией. - Когда сотрудник ответит, отправьте
event=NOTIFY_ANSWER. Ответивший добавочный укажите вinternal. - После окончания разговора отправьте
event=NOTIFY_END. Ответ и завершение являются разными событиями.
Используйте один способ передачи каждого события. Если уже работают события через AMI или отдельный HTTP hook, согласуйте их с этим входом: разные идентификаторы одного разговора не объединяются автоматически.


Что настроить перед обменом
Создайте линию 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».
Поля запросов
| Поле | Что передавать |
|---|---|
action | incoming или incomingText. Не передавайте одновременно с event. |
event | NOTIFY_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 может попытаться определить адрес, подъезд, лифт и проблему, но распознавание не гарантирует правильного выбора объекта. Перед сохранением обращения проверьте подставленные сведения.

Ответ и завершение
Сотрудник с добавочным 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 при чтении необязательно, но без него при нескольких доступных разговорах с одного номера ответ будет пустым. Пустой ответ также возможен при отсутствии контекста или доступа. Это не подтверждение отсутствия самого звонка.
Проверка и устранение ошибок
- Проверьте адрес сервера, ключ метода, существование линии и её адресатов.
- Выполните учебный звонок и последовательно проверьте начало, текст, ответ и завершение с одним UID.
- Сопоставьте карточку, контекст и журнал. Начало через этот вход само по себе не создаёт строку журнала: для неё требуется настроенный адресный hook или AMI.
- Проверьте заблокированный номер. Начало и текст не должны рассылаться; ответ содержит
is_block:trueиaccepted:false. - Отдельно проверьте реальный разговор. Уведомление, HTTP-ответ и распознанный текст не подтверждают работу микрофона, звука или SIP-соединения.
Обычное подтверждение события содержит ok:true, accepted:true и тот же строковый id. Для начала оно может прийти до окончания доставки уведомлений. При неверном событии, типе или обязательном поле возвращается ошибка 400, при неизвестной линии 404, при отказе авторизации 403. Не считайте любой HTTP200 доказательством появления карточки у сотрудника.
При повторе после сетевого сбоя сохраняйте прежний UID. Не назначайте новый идентификатор каждому повторному запросу. Все события одного разговора должны использовать одинаковые линию и источник станции.