Webhook-каналы мессенджеров Chatter

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

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

Webhook-каналы мессенджеров Chatter

Webhook передаёт сообщения между мессенджером и диалогом Chatter. Входящее сообщение клиента поступает в настроенный источник, а публичный ответ оператора отправляется через тот же канал. Внутренняя заметка остаётся в Chatter.

Статья предназначена для администратора подключения. Оператору достаточно проверить источник диалога, написать ответ и убедиться, что он появился у получателя.

В этой статье

Как выбрать подключение

Откройте Настройки → Chatter → Источники и карточку нужного источника. Проверьте его название и тип подключения. Общий порядок описан в статье Источники Chatter: подключение и настройка каналов.

У Telegram есть два способа подключения: штатный Telegram-канал Chatter и API-канал с адаптером telegramBot на стороне TesLab. Эта статья описывает второй вариант. Для штатного Telegram-канала используйте его собственные настройки подключения.

ПодключениеОбмен через этот webhook
Telegram Bot, telegramBotВходящие сообщения, выбор кнопок и исходящие ответы.
Whapi, whapiВходящие сообщения WhatsApp, исходящие ответы и поддержанные события статусов.
Gupshup, gupshupВходящие сообщения, исходящие ответы и статусы в формате настроенного адаптера.
MAX, maxВходящие сообщения, выбор кнопок и исходящие ответы.
GREEN-API, green-apiСовместимое подключение WhatsApp: входящие сообщения, исходящие ответы и статусы.
Домиленд, domylandChatТекстовый ответ в связанный инцидент. Входящие сообщения Домиленда и вложения этим адаптером не обслуживаются.

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

Учебная карточка Telegram Bot: идентификатор входящего API-канала и сохранение настроек
1. Идентификатор входящего API-канала. 2. Кнопка сохранения. Ключ проверки личности пользователя ниже относится к другой проверке и не заменяет ключ webhook.

Два направления обмена

  1. Из мессенджера в Chatter. Провайдер отправляет своё событие. Адрес подключения указывает нужный источник, а адаптер извлекает автора, текст и поддержанные вложения.
  2. Из Chatter в мессенджер. Событие нового публичного ответа содержит объект inbox, сведения о диалоге и сообщение. TesLab выбирает адаптер из сохранённых настроек этого источника.

Webhook работает по адресу /api/system/chatters/webhook. Используйте адрес, сформированный при подключении источника, со своими параметрами доступа. Не собирайте рабочий URL из примера и не публикуйте его вместе с ключами.

У Chatter два разных входящих маршрута. Диалог и основная диспетчерская заявка имеют разные этапы.
Вход провайдера и ответ Chatter имеют отдельные ветви; private-заметка не отправляется наружу.

Входящее событие мессенджера

ПараметрЧто проверить
inboxЧисловой ID источника Chatter, переданный отдельным значением.
identifierИдентификатор именно этого источника. Несовпадение приводит к отказу.
Ключ входа webhookКлюч доступа TesLab из сформированного адреса подключения. Он отличается от inbox_identifier и токена бота.
Тело событияJSON выбранного провайдера: Telegram, WhatsApp и MAX передают разные структуры.

Адаптер берётся из сохранённых параметров источника. Значение mod в произвольном callback не переключает его на другой сервис. Для старого подключения GREEN-API заголовок User-Agent: GREEN-API помогает распознать совместимый канал только при наличии его сохранённых параметров. Он не заменяет проверку идентификатора и доступа.

Пример Telegram Bot

Ниже условное событие обычного текста. Все значения вымышлены. Пример объясняет формат, а для проверки используйте реальное сообщение своему тестовому боту.

POST /api/system/chatters/webhook?inbox=901201&identifier=YOUR_INBOX_IDENTIFIER
Access-Code: YOUR_CHATTER_WEBHOOK_KEY
Content-Type: application/json
Out: json

{
  "update_id": 901401,
  "message": {
    "message_id": 901402,
    "from": {"id": 901403, "first_name": "Учебный"},
    "chat": {"id": 901403, "type": "private"},
    "text": "Учебное сообщение"
  }
}

Для текста используется message.text, для подписи к файлу может приходить message.caption. Нажатие кнопки передаётся отдельным событием callback_query. В нём нужны идентификатор нажатия, выбранное значение, автор и исходное сообщение с данными чата. Его не нужно вручную превращать в обычное сообщение или повторно отправлять с новым ID.

Появление сообщения в Chatter ещё не означает создание диспетчерской заявки. Если источнику назначен робот, дальнейшее уточнение адреса и регистрацию обращения описывает статья Обращения из Chatter: события сообщений и диалога.

Ответ оператора и внутренняя заметка

Откройте диалог клиента и напишите публичный ответ. Для отправки наружу используется событие со следующими признаками:

ПолеЗначение или назначение
eventmessage_created.
message_typeoutgoing.
privateЛогическое false для ответа клиенту. При true заметка не отправляется в мессенджер.
account.id, inbox.idУчётная запись Chatter и настроенный источник.
conversation.id, idID диалога и сообщения Chatter.
conversation.meta.senderАдресат в формате канала: идентификатор чата или номер телефона.
content, attachmentsТекст и список вложений. Пустой список вложений не мешает отправке текста.
source_idID сообщения внешнего сервиса. Уже связанное с внешним сообщением событие повторно не отправляется.

Внутренняя заметка видна коллегам в истории с отдельной подписью. Наличие message_type=outgoing само по себе не означает, что запись предназначена клиенту. Признак приватности сохраняется и у сообщения с вложениями.

Учебный диалог: внутренняя заметка и обычный ответ клиенту
1. Внутренняя заметка для коллег. 2. Публичный ответ, который отправляется клиенту через источник диалога.

Для внешней отправки принимается до 10 вложений в одном событии. Если адаптер отправляет их отдельными сообщениями, общий успешный результат возвращается после подтверждения всех частей. Файлы, которые TesLab скачивает для передачи, ограничены 30 МиБ на файл. У мессенджера могут быть более строгие ограничения. Для остальных подключений, передающих провайдеру URL файла, действуют его правила загрузки.

Статусы и повторные события

Проверяйте результат по этапам:

  1. Webhook принят. HTTP 200 сообщает об обработке события. Ответ с accepted=false может означать, что событие не предназначено для внешней отправки, например это внутренняя заметка.
  2. Сообщение появилось в Chatter. Проверьте нужный источник, автора, текст и файлы в диалоге.
  3. API провайдера принял ответ. После подтверждения отправки сохраняется внешний ID и статус sent. Это ещё не подтверждение прочтения.
  4. Получатель получил или прочитал сообщение. Отдельные статусы delivered и read возможны, если подключение присылает поддержанные уведомления. Telegram Bot не подтверждает ими доставку и прочтение обычного ответа.

Успешно обработанное повторное событие использует сохранённый результат. Это защищает от повторной отправки того же ответа или повторного добавления того же входящего события.

Если соединение оборвалось после отправки запроса, результат у провайдера может остаться неизвестным. Такой повтор получает HTTP 409 и не отправляется вслепую ещё раз. То же правило действует, когда из нескольких вложений успела отправиться только часть. Администратору нужно сопоставить сообщение и файлы в Chatter с фактическими сообщениями провайдера, затем решить, нужен ли отдельный новый ответ. Не создавайте новые ID событий для обхода проверки повторов.

Как проверить подключение

  1. Выберите отдельный тестовый источник и учётную запись получателя.
  2. Проверьте тип канала, сохранённый адаптер и параметры подключения. Отправьте сообщение из мессенджера.
  3. Найдите его в правильном диалоге Chatter. Проверьте текст, автора и источник.
  4. Напишите публичный ответ оператором и убедитесь, что он появился у получателя.
  5. Если используются файлы, отдельно проверьте файл с подписью и несколько вложений.
  6. Проверьте внутреннюю заметку: она должна остаться в Chatter и отсутствовать у получателя.
  7. Если робот предлагает кнопки, нажмите одну из них. Проверьте выбранное значение и продолжение диалога.
  8. Для WhatsApp проверьте доступные статусы, учитывая возможности конкретного провайдера. Повторную доставку событий и сбои проверяйте в тестовом подключении.

Если обмен не работает

НаблюдениеЧто проверить
HTTP 400Структуру JSON, типы полей, ID источника и поддержку адаптера. Для Домиленда этот маршрут не принимает входящие сообщения и не отправляет файлы.
HTTP 403Ключ доступа, identifier, соответствие источника и учётной записи. Не заменяйте их значениями другого канала.
HTTP 409Предыдущая попытка ещё выполняется либо её внешний результат неизвестен. Проверьте фактическую отправку перед дальнейшими действиями.
HTTP 422 при повтореС тем же ID пришло другое содержимое. ID события нельзя использовать для другого сообщения.
HTTP 413Размер файла, скачиваемого TesLab для передачи.
HTTP 502 или ошибка провайдераДоступность Chatter и мессенджера, токен, адресата, права бота, типы файлов и ответ внешнего API.
HTTP 200, но клиент ничего не получилНаправление события, приватность записи, внешний ID и результат у провайдера. Приём webhook не равен доставке сообщения.
Текст проходит, кнопки или файлы не работаютВозможности конкретного канала и ограничения его API. Не переносите формат Telegram-кнопок в WhatsApp.

При обращении за помощью укажите источник, ID диалога и сообщения, время события, HTTP-код и безопасный фрагмент ошибки. Удалите из материалов ключи доступа, токены ботов и рабочие URL с секретными параметрами.