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 провайдера. Типы файлов, размеры, кнопки и доступность канала зависят от конкретного подключения. Произвольный новый сервис нельзя подключить, подставив его название в событие.

Два направления обмена
- Из мессенджера в Chatter. Провайдер отправляет своё событие. Адрес подключения указывает нужный источник, а адаптер извлекает автора, текст и поддержанные вложения.
- Из Chatter в мессенджер. Событие нового публичного ответа содержит объект
inbox, сведения о диалоге и сообщение. TesLab выбирает адаптер из сохранённых настроек этого источника.
Webhook работает по адресу /api/system/chatters/webhook. Используйте адрес, сформированный при подключении источника, со своими параметрами доступа. Не собирайте рабочий URL из примера и не публикуйте его вместе с ключами.

Входящее событие мессенджера
| Параметр | Что проверить |
|---|---|
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: события сообщений и диалога.
Ответ оператора и внутренняя заметка
Откройте диалог клиента и напишите публичный ответ. Для отправки наружу используется событие со следующими признаками:
| Поле | Значение или назначение |
|---|---|
event | message_created. |
message_type | outgoing. |
private | Логическое false для ответа клиенту. При true заметка не отправляется в мессенджер. |
account.id, inbox.id | Учётная запись Chatter и настроенный источник. |
conversation.id, id | ID диалога и сообщения Chatter. |
conversation.meta.sender | Адресат в формате канала: идентификатор чата или номер телефона. |
content, attachments | Текст и список вложений. Пустой список вложений не мешает отправке текста. |
source_id | ID сообщения внешнего сервиса. Уже связанное с внешним сообщением событие повторно не отправляется. |
Внутренняя заметка видна коллегам в истории с отдельной подписью. Наличие message_type=outgoing само по себе не означает, что запись предназначена клиенту. Признак приватности сохраняется и у сообщения с вложениями.

Для внешней отправки принимается до 10 вложений в одном событии. Если адаптер отправляет их отдельными сообщениями, общий успешный результат возвращается после подтверждения всех частей. Файлы, которые TesLab скачивает для передачи, ограничены 30 МиБ на файл. У мессенджера могут быть более строгие ограничения. Для остальных подключений, передающих провайдеру URL файла, действуют его правила загрузки.
Статусы и повторные события
Проверяйте результат по этапам:
- Webhook принят. HTTP 200 сообщает об обработке события. Ответ с
accepted=falseможет означать, что событие не предназначено для внешней отправки, например это внутренняя заметка. - Сообщение появилось в Chatter. Проверьте нужный источник, автора, текст и файлы в диалоге.
- API провайдера принял ответ. После подтверждения отправки сохраняется внешний ID и статус
sent. Это ещё не подтверждение прочтения. - Получатель получил или прочитал сообщение. Отдельные статусы
deliveredиreadвозможны, если подключение присылает поддержанные уведомления. Telegram Bot не подтверждает ими доставку и прочтение обычного ответа.
Успешно обработанное повторное событие использует сохранённый результат. Это защищает от повторной отправки того же ответа или повторного добавления того же входящего события.
Если соединение оборвалось после отправки запроса, результат у провайдера может остаться неизвестным. Такой повтор получает HTTP 409 и не отправляется вслепую ещё раз. То же правило действует, когда из нескольких вложений успела отправиться только часть. Администратору нужно сопоставить сообщение и файлы в Chatter с фактическими сообщениями провайдера, затем решить, нужен ли отдельный новый ответ. Не создавайте новые ID событий для обхода проверки повторов.
Как проверить подключение
- Выберите отдельный тестовый источник и учётную запись получателя.
- Проверьте тип канала, сохранённый адаптер и параметры подключения. Отправьте сообщение из мессенджера.
- Найдите его в правильном диалоге Chatter. Проверьте текст, автора и источник.
- Напишите публичный ответ оператором и убедитесь, что он появился у получателя.
- Если используются файлы, отдельно проверьте файл с подписью и несколько вложений.
- Проверьте внутреннюю заметку: она должна остаться в Chatter и отсутствовать у получателя.
- Если робот предлагает кнопки, нажмите одну из них. Проверьте выбранное значение и продолжение диалога.
- Для 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 с секретными параметрами.
Связанные статьи
- Talk-Me и Chatter: каналы приёма обращений.
- Источники Chatter: подключение и настройка каналов.
- Обращения из Chatter: события сообщений и диалога.
- API TesLab: адрес сервера и первый запрос.
- Протокол обмена с 1С:Бухгалтерия.