Чаты

PreviousИнтеграции NextШаблоны

Last updated 6 days ago

Was this helpful?

Чаты

Общее

Swagger:

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

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

Список доступных источников чатов можно получить здесь:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример отправки текстового сообщения

POST /messaging/messages/
{
  "connection_id": 29228,
  "chat_id": 7810280,
  "message_type": "text",
  "text": {
    "text": "demo"
  }
}

Response
{
  "mode": "async",
  "chat": {
    "id": 7810280,
    "name": "Demo",
    "is_group": false,
    "avatar_url": "https://radist2.cdn.radist.online/avatars/example",
    "profile_link": "https://t.me/durov"
  },
  "message": {
    "message_id": "0023ebfa-c820-4642-a8cc-37e28ef754a8",
    "source_message_id": null,
    "chat_id": "192736912",
    "direction": "outbound",
    "message_type": "text",
    "author": null,
    "created_at": "2025-04-29T13:40:52.471511Z",
    "delivered_at": null,
    "read_at": null,
    "error_at": null,
    "error_type": null,
    "error_text": null,
    "text": {
      "text": "demo"
    },
    "file": null,
    "image": null,
    "audio": null,
    "video": null,
    "voice": null,
    "waba_template": null,
    "waba_interactive": null,
    "radist_order": null,
    "waba_order": null
  }
}

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

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

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

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

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

POST /messaging/messages/
{
  "connection_id": 29228,
  "chat_id": 7810280,
  "message_type": "image",
  "image": {
    "caption": "caption demo",
    "url": "https://ams3.digitaloceanspaces.com/radist2/user_uploads/91a43013-9925-4b82-98dc-7414950abfdb/8fdc0a35-a4d0-4175-b1b6-a2fd45ad62f3.jpg"
  }
}

Response
{
  "mode": "async",
  "chat": {
    "id": 7810280,
    "name": "Demo",
    "is_group": false,
    "avatar_url": "https://radist2.cdn.radist.online/avatars/example",
    "profile_link": "https://t.me/durov"
  },
  "message": {
    "message_id": "50c97862-0c6b-4f3c-8144-19b4b96a8571",
    "source_message_id": null,
    "chat_id": "192736912",
    "direction": "outbound",
    "message_type": "image",
    "author": null,
    "created_at": "2025-04-29T13:44:13.330623Z",
    "delivered_at": null,
    "read_at": null,
    "error_at": null,
    "error_type": null,
    "error_text": null,
    "text": null,
    "file": null,
    "image": {
      "caption": "caption demo",
      "name": "245348975_827083521495161_4529912460032517702_n.jpg",
      "size": 720406,
      "mime_type": "image/jpeg",
      "url": "https://radist2.cdn.radist.online/user_uploads/91a43013-9925-4b82-98dc-7414950abfdb/8fdc0a35-a4d0-4175-b1b6-a2fd45ad62f3.jpg"
    },
    "audio": null,
    "video": null,
    "voice": null,
    "waba_template": null,
    "waba_interactive": null,
    "radist_order": null,
    "waba_order": null
  }
}

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

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

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

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

Заголовка/header (текст с переменными или файл)
Тела/body (текст с переменными)
Подписи/footer (текст)
Кнопок/buttons (текстовая, ссылка, номер телефона)

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

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

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

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

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

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

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

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

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

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

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

Замечания

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

PreviousИнтеграции NextШаблоны

Last updated 6 days ago

Was this helpful?