Чаты (API v2)

Чаты в API Radist.Online: источники чатов, создание диалога по номеру, username или id чата в WhatsApp, Telegram, MAX и VK, привязка чатов к контактам и inbox.

Общее

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

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

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

Список доступных источников чатов можно получить здесь (GET /companies/{company_id}/messaging/chats/sources/): MessagingGetChatsSources

У каждого источника указан connection_id, который нужно будет использовать далее, и объект create_chat — три флага, показывающие, каким идентификатором в этом источнике можно создать чат: with_phone (номер телефона), with_username (имя пользователя) и with_chat_id (идентификатор чата на стороне мессенджера).

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

MessagingCreateChat (POST /companies/{company_id}/messaging/chats/)

Чат создаётся по одному из трёх идентификаторов — в запросе нужно передать хотя бы один из них:

phone — номер телефона клиента в формате E.164 (WhatsApp, WABA, Telegram, MAX, VK Мессенджер);
user_name — имя пользователя (Telegram, VK Мессенджер);
chat_id — идентификатор чата на стороне мессенджера (Telegram, MAX).

Какие идентификаторы принимает конкретное подключение, видно в объекте create_chat в списке источников. У Telegram Bot, MAX Bot, VK Сообществ и Авито все три флага false: создать чат через них нельзя, диалог начинает клиент.

Если чат уже существует, вернётся существующий чат. В ответе приходят chat_id, contact_id и два флага — created_chat и created_contact: они показывают, были ли чат и контакт созданы этим запросом или уже существовали.

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

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

Саму карточку контакта — имя, телефоны, теги, заметки — можно вести отдельно, см. Контакты.

Пример создания чата по номеру телефона

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
POST /companies/{company_id}/messaging/chats/
{
  "connection_id": 6466,
  "phone": "+79000000000"
}

Response
{
  "created_chat": true,
  "created_contact": false,
  "chat_id": 7810280,
  "contact_id": 1183
}

Получение чата

Если id чата уже известен, чат можно получить методом MessagingGetChatById (GET /companies/{company_id}/messaging/chats/{chat_id}).

Если у вас есть идентификатор чата на стороне мессенджера (тот, что приходит в вебхуках в поле message.chat_id), используйте MessagingGetChatBySource (GET /companies/{company_id}/messaging/chats/by_source/) — метод принимает connection_id и source_chat_id и возвращает наш чат.

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

MessagingGetChatsWithContacts (GET /companies/{company_id}/messaging/chats/with_contacts/)

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

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

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

Порядок выдачи задаётся параметром sort_order:

new_first — контакты отсортированы по времени последнего сообщения, более свежие выше. Только с этим значением работают фильтры connection_ids (показывать контакты только по этим подключениям) и unanswered_only (только контакты с неотвеченными сообщениями).
unanswered_first — сначала контакты, у которых есть чаты с неотвеченными сообщениями, затем все остальные по времени последнего сообщения. Значение по умолчанию.

sort_order=unanswered_first устарел и будет удалён 2026-10-01, вместе с ним пропадёт и текущее значение по умолчанию. Переходите на sort_order=new_first: передавайте его явно, а если вам нужны были неотвеченные сверху — получайте их отдельным запросом с unanswered_only=true.

Отметка чата отвеченным

MessagingMarkChatAnsweredById (POST /companies/{company_id}/messaging/chats/{chat_id}/actions/mark_answered)

Обнуляет счётчик неотвеченных сообщений чата (unanswered_count) — тот самый, по которому чаты попадают наверх при sort_order=unanswered_first и в фильтр unanswered_only. Пригодится, если вы отвечаете клиентам не через нас и хотите, чтобы это было видно в личном кабинете. В ответ приходит 204 No Content.

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

MessagingGetMessages (GET /companies/{company_id}/messaging/messages/)

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

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

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

MessagingSendMessage (POST /companies/{company_id}/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 /companies/{company_id}/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
  }
}

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

MessagingUploadFile

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

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

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

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

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

 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 /companies/{company_id}/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. Получить список доступных шаблонов можно тут:

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 /companies/{company_id}/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

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

https://developers.facebook.com/docs/whatsapp/guides/interactive-messages

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

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

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

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

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

MessagingGetChatAvailabilityById (GET /companies/{company_id}/messaging/chats/{chat_id}/availability)

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

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

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

Замечания

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

Помогла ли статья?

Последнее обновление 10 сентября 2026 г.

Интеграции (API v2)Контакты