Чаты

Общее

Swagger: https://api.radist.online/v2/docs#/Messaging

Необходимые права доступа (scopes) для работы с API: messaging

Источники чатов

Список доступных источников чатов можно получить здесь: https://api.radist.online/v2/docs#/Messaging/MessagingGetChatsSources

У каждого источника указано, как через него можно создавать новые чаты.

Создание чата

https://api.radist.online/v2/docs#/Messaging/MessagingCreateChat

В зависимости от мессенджера, чат можно создать либо с использованием номера телефона клиента (WhatsApp, Telegram), либо с использованием имени пользователя (Telegram).

При создании чата сразу происходит его привязка к контакту. Она работает следующим образом:

  1. При создании чата с использованием номера телефона, если в компании уже существует контакт с этим номером, чат будет привязан к нему

  2. При создании чата в Telegram/Telegram Bot по возможности чат будет привязан к контакту, у которого уже есть чаты с этим пользователем. Пример: есть чат через бота с пользователем @example привязанный к контакту с id=456. Создаём новый чат через личный номер telegram с тем же пользователем @example. Будет создан новый чат, но привязан он будет к контакту с id=456

  3. При создании чата можно явно указать contact_id, тогда чат будет привязан к указанному контакту, если чат ещё не существует. Если существует, будет возвращёт существующий чат с существующим контактом.

  4. Если 1-3 не сработали, будет создан новый контакт

Получение списка чатов

https://api.radist.online/v2/docs#/Messaging/MessagingGetChatsWithContacts

Чаты привязаны к контактам. Этот метод позволяет получить список чатов, сгруппированных по контактам. У одного контакта может быть несколько чатов.

Для итерации используйте параметр cursor, который возвращается в запросе.

Как отсортирована выдача:

  • Сначала идут те контакты, у которых есть чаты с неотвеченными сообщениями

  • Затем все остальные, отсортированные по времени последнего сообщения (более свежие выше)

Просмотр сообщений в чате

https://api.radist.online/v2/docs#/Messaging/MessagingGetMessages

Сообщения отсортированы от старых к новым. Для итерации используйте параметр until.

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

Отправка сообщения

https://api.radist.online/v2/docs#/Messaging/MessagingSendMessage

Для отправки сообщения необходимо знать id чата, в который сообщение отправляется, и id подключения, через которое сообщение будет отправлено.

Нужно указать тип сообщения и заполнить поле, имя которого совпадает с типом сообщения. Например, для сообщения с типом text нужно заполнить структуру text.

Отправка сообщения с файлом

https://api.radist.online/v2/docs#/Messaging/MessagingUploadFile

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

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

Максимальный размер файла для загрузки: 100 МБ. Но в разных мессенджерах могут быть дополнительные ограничения на размеры или форматы файлов. Уточняйте их в документации конкретных мессенджеров.

На примере WABA: максимальный размер изображения после пост-обработки* - 5 МБ. Это значит, что вы можете попытаться отправить изображение размером 100 МБ, но если после сжатия его размер всё ещё будет более 5 МБ, оно не будет отправлено.

Шаблонные сообщения WhatsApp Business API

Подробное описание возможностей:

Тип сообщения у нас: waba_template

Шаблоны - единственный тип сообщений, который можно отправить в чаты, у которых закрыто диалоговое окно. Про диалоговые окна ниже.

Шаблоны в общем случае состоят из 4 компонентов:

  • Заголовка/header (текст с переменными или файл)

  • Тела/body (текст с переменными)

  • Подписи/footer (текст)

  • Кнопок/buttons (текстовая, ссылка, номер телефона)

Обязательно только тело шаблона.

Для отправки шаблона необходимо знать его название, язык и передать список переменных, если требуется. Шаблоны создаются в хабе 360Dialog. Получить список доступных шаблонов можно тут:

https://api.radist.online/v2/docs#/Messaging/MessagingListWabaTemplates

Интерактивные сообщения WhatsApp Business API

Подробное описание:

Тип сообщения у нас: waba_interactive

Эти сообщения позволяют:

  • *Отправить товар

  • *Отправить группу товаров

  • Отправить сообщение с 3 кнопками

  • Отправить сообщение с меню, в котором можно выбрать один из вариантов (можно использовать как замену кнопок, если нужно отправить более 3 штук)

  • *Отправить сообщение, запрашивающее у пользователя локацию

* Эти типы у нас пока не поддерживаются. Если они вам нужны, запросите, это может ускорить их появление.

Доступность чата (WABA)

https://api.radist.online/v2/docs#/Messaging/MessagingGetChatAvailability

У WABA есть ограниченные по времени платные диалоговые сессии (описание). Если у чата нет открытой сессии, в чат нельзя будет отправить нешаблонное сообщение. Если же баланс диалогов достиг 0 или отрицательный, нельзя будет отправить никакое сообщение.

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

Этот метод так же учитывает, включена ли опция "Писать первым не с шаблонного сообщения" на номере. Если включена, то для отправки сообщения не обязательно дожидаться сообщения от клиента, можно сразу отправлять обычное текстовое сообщение.

Замечания

  • Не загружайте переписку методом опроса API, подпишитесь на вебхуки

  • Кешируйте и переиспользуйте ссылки на загруженные файлы. Особенно, если делаете рассылки с файлами.

  • Максимальный размер файла: 100МБ, но могут быть дополнительные ограничения на размер или формат файлов со стороны мессенджеров.

Last updated