Архитектура каналов обмена сообщениями #
Каналы обмена сообщениями подключают мессенджер клиента к тому же рантайму диалогов, который обслуживает веб-чат и SDK. На этой странице описаны поток сообщений, гарантии доставки и поддержка типов сообщений по каналам. Страницы отдельных каналов: Telegram и WhatsApp. Чат на вашем сайте описан на странице Виджет чата на сайте.
Поток сообщений #
- Провайдер (Telegram или Meta) отправляет каждое сообщение клиента на HTTPS-вебхук HeySora.
- Адрес вебхука содержит секретный путь, а запрос проверяется по подписи или секретному заголовку провайдера. Запросы, не прошедшие проверку, отклоняются.
- Каждое входящее событие проходит надёжную дедупликацию: сообщение, которое провайдер доставил дважды, обрабатывается один раз.
- Рантайм диалогов привязывает сообщение к нужному диалогу нужного проекта.
- ИИ-агент отвечает на основе одобренных вами знаний или передаёт диалог оператору.
- Оператор видит диалог во входящих рабочего пространства и может ответить там.
- Исходящий отправитель доставляет каждый ответ (ИИ или оператора) провайдеру и записывает результат.
Надёжность #
- Идемпотентность. Входящие события дедуплицируются по идентификатору события провайдера, а исходящие ответы несут внутренний ключ доставки, поэтому повторы не создают дублей ответов.
- Повторы и backoff. Временные ошибки провайдера повторяются с экспоненциальной задержкой. Если провайдер просит замедлиться (подсказка
Retry-After), отправитель ждёт не меньше указанного. - Никаких тихих сбоев. Ответ, который нельзя доставить, получает видимое финальное состояние (ошибка или блокировка с причиной), а не молчание.
- Видимость состояния. Каждое подключение показывает статус и последнюю ошибку в рабочем пространстве, поэтому администратор видит проблему с ключом или вебхуком без чтения журналов.
Привязка к проекту #
Каждое подключение принадлежит ровно одному проекту одной организации. Привязка проверяется на сервере для входящих и исходящих сообщений: сообщение не может попасть в другой проект или другую организацию, что бы ни содержал запрос провайдера.
Поддерживаемые типы сообщений #
| Тип | Telegram | |
|---|---|---|
| Текст | Да | Да |
| Фото / изображение | Да | Да |
| Документ | Да | Да |
| Голос / аудио | Да | Да (аудио) |
| Геолокация | Вежливое уведомление «не поддерживается» | Да |
| Стикеры | Вежливое уведомление «не поддерживается» | Не входят в поддерживаемый набор |
| Видео | Вежливое уведомление «не поддерживается» | Не входят в поддерживаемый набор |
Типы вне поддерживаемого набора не обрабатываются как содержимое. Где канал это позволяет, клиент получает короткое уведомление, что тип не поддерживается, и просьбу описать вопрос текстом.
Состояния доставки #
| Состояние | Telegram | |
|---|---|---|
| Отправлено | Да | Да |
| Доставлено | Telegram не присылает квитанций | Да, по квитанциям провайдера |
| Прочитано | Telegram не присылает квитанций | Да, по квитанциям провайдера |
| Ошибка | Да | Да |
| Заблокировано с причиной | Не применимо | Да (например, вне 24-часового окна без одобренного шаблона) |
Настройка, тестирование и диагностика #
Шаги подключения, ключи, привязка к проекту, тестирование и диагностика зависят от вашей организации и доступны после входа: в Справке собраны пошаговые руководства по подключению и диагностике, а в портале разработчиков - технические детали и инструменты тестирования.