Перейти к содержимому
API
v2

Чаты

Общее

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

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

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

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

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

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

https://api.radist.online/v2/docs#/Messaging/MessagingCreateChat (POST /messaging/chats/)

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

Если чат уже существует, вернётся существующий чат.

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

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

Получение списка чатов с контактами (inbox)

https://api.radist.online/v2/docs#/Messaging/MessagingGetChatsWithContacts (GET /messagin/chats/with_contacts/)

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

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

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

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

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

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

https://api.radist.online/v2/docs#/Messaging/MessagingGetMessages (GET /messaging/messages/)

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

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

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

https://api.radist.online/v2/docs#/Messaging/MessagingSendMessage (POST /messaging/messages/)

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

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

Пример отправки текстового сообщения
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

POST /messaging/messages/
{
  "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": {
      "id": "0b4fadf0-76b1-4463-baae-e0c8a091263a",
      "name": "Dmitry V.",
      "external_id": "96",
      "user_id": 96,
      "phone": 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
  }
}

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

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

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

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

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

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

Пример отправки сообщения с файлом
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

POST /messaging/messages/
{
  "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": {
      "id": "0b4fadf0-76b1-4463-baae-e0c8a091263a",
      "name": "Dmitry V.",
      "external_id": "96",
      "user_id": 96,
      "phone": 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, в нашем личном кабинете, либо через API. Получить список доступных шаблонов можно тут:

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

Пример отправки шаблона с файлом и переменной в теле
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

// С файлом в заголовке
POST /messaging/messages/
{
  "chat_id": 452927,
  "message_type": "waba_template",
  "waba_template": {
    "template_locale": "bg",
    "template_name": "s_dokumentom1_29dbe7",
    "header_params": [
      {
        "url": "https://ams3.digitaloceanspaces.com/radist2/testing/973b2da1-8635-47f7-8bc1-a91abc2c85ac/0430503f-4371-4eb6-b619-7b1b1424e4d8.pdf"
      }
    ],
    "body_params": [
      "Demo value"
    ]
  }
}

Response
{
  "mode": "async",
  "chat": {
    "id": 452927,
    "name": "+79000000000",
    "is_group": false,
    "avatar_url": null,
    "profile_link": null
  },
  "message": {
    "message_id": "51f1da19-c89d-4adf-905d-2a918c09e922",
    "source_message_id": null,
    "chat_id": "79000000000",
    "direction": "outbound",
    "message_type": "waba_template",
    "author": {
      "id": "1809455d-6715-4cd6-91ce-eb37f628da7b",
      "name": "Vitaly S.",
      "external_id": "25",
      "user_id": 25,
      "phone": null
    },
    "created_at": "2025-06-03T12:07:26.380134Z",
    "delivered_at": null,
    "read_at": null,
    "error_at": null,
    "error_type": null,
    "error_text": null,
    "text": null,
    "file": null,
    "image": null,
    "audio": null,
    "video": null,
    "voice": null,
    "waba_template": {
      "text": "Не забудьте оплатить ваш заказ! Demo value",
      "template_locale": "bg",
      "template_name": "s_dokumentom1_29dbe7",
      "media_header": {
        "format": "document",
        "file_name": "document pdf.pdf",
        "file_size": 6489,
        "file_mime_type": "application/pdf",
        "file_url": "https://radist2.cdn.radist.online/testing/973b2da1-8635-47f7-8bc1-a91abc2c85ac/0430503f-4371-4eb6-b619-7b1b1424e4d8.pdf"
      },
      "buttons": [],
      "carousel": []
    },
    "waba_interactive": null,
    "radist_order": null,
    "waba_order": null
  }
}

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

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

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

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

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

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

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

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

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

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

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

Замечания

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