Чаты
Общее
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).
При создании чата сразу происходит его привязка к контакту. Она работает следующим образом:
При создании чата с использованием номера телефона, если в компании уже существует контакт с этим номером, чат будет привязан к нему
При создании чата в Telegram/Telegram Bot по возможности чат будет привязан к контакту, у которого уже есть чаты с этим пользователем. Пример: есть чат через бота с пользователем @example привязанный к контакту с
id=456. Создаём новый чат через личный номер telegram с тем же пользователем @example. Будет создан новый чат, но привязан он будет к контакту сid=456При создании чата можно явно указать
contact_id, тогда чат будет привязан к указанному контакту, если чат ещё не существует. Если существует, будет возвращёт существующий чат с существующим контактом.Если 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