Интеграции → API для разработчиков

API для разработчиков — WhatsApp, Telegram, MAX

HTTP API chatb24 работает. Отправляйте сообщения и получайте входящие напрямую в свою систему — сайт, интернет-магазин, 1С, мобильное приложение или самописную CRM. Один протокол для всех каналов: код пишется один раз, а WhatsApp, Telegram и MAX ходят через единый интерфейс.

Быстрый старт — три шага

В личном кабинете откройте «Подключить CRM или свой софт» → Свой софт (API) и создайте ключ. Ключ показывается один раз — сохраните его сразу.
Отправьте первое сообщение запросом POST /api/v1/messages.
Укажите адрес вебхука — и входящие начнут приходить к вам сами.

Аутентификация

Ключ имеет вид cb24_… и передаётся в заголовке. Работают оба способа:

Authorization: Bearer cb24_ваш_ключ
X-Api-Key: cb24_ваш_ключ

В базе хранится только хеш ключа — восстановить его мы не можем. Потеряли — отзовите старый и создайте новый. Ключ действует на весь аккаунт: доступны все ваши номера, чужие — нет.

Проверить ключ:

curl https://app.chatb24.ru/api/v1/ping \
  -H "Authorization: Bearer cb24_ваш_ключ"

{"ok":true}

Методы

Метод	Путь	Что делает
GET	`/api/v1/ping`	проверка ключа
GET	`/api/v1/profiles`	список ваших подключённых номеров
POST	`/api/v1/messages`	отправить текст
POST	`/api/v1/messages/media`	отправить файл, картинку, документ
GET	`/api/v1/webhook`	текущий адрес вебхука
PUT	`/api/v1/webhook`	задать адрес вебхука
DELETE	`/api/v1/webhook`	отключить вебхук

Базовый адрес — https://app.chatb24.ru. Ответы и тела запросов — JSON в кодировке UTF-8.

Список ваших номеров

curl https://app.chatb24.ru/api/v1/profiles \
  -H "Authorization: Bearer cb24_ваш_ключ"

[
  {
    "id": "9fa058c7-1bc5-4dfc-b18a-f1dbc879046a",
    "name": "Отдел продаж",
    "channel_type": "whatsapp",
    "status": "open",
    "phone": "79990001122"
  }
]

Поле id — это и есть profile_id, который нужен для отправки. channel_type бывает whatsapp, telegram, max_personal.

Отправить текст

curl -X POST https://app.chatb24.ru/api/v1/messages \
  -H "Authorization: Bearer cb24_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "9fa058c7-1bc5-4dfc-b18a-f1dbc879046a",
    "to": "79990001122",
    "text": "Заказ №123 собран и передан в доставку"
  }'

{"ok":true,"message_id":"3EB0C767D26B8F1B2A44"}

Поля пишутся через подчёркивание — profile_id, а не profileId. Это частая причина ошибки 400 на первом запросе.

В поле to для WhatsApp и MAX — номер телефона цифрами, для Telegram — номер или идентификатор чата.

Отправить файл

Два способа: дать ссылку на файл или прислать его содержимое в base64.

curl -X POST https://app.chatb24.ru/api/v1/messages/media \
  -H "Authorization: Bearer cb24_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "9fa058c7-1bc5-4dfc-b18a-f1dbc879046a",
    "to": "79990001122",
    "url": "https://example.com/schet-123.pdf",
    "filename": "Счёт №123.pdf",
    "caption": "Счёт во вложении"
  }'

Вместо url можно передать base64 — содержимое файла (с префиксом data: или без). Тогда файл сохраняется у нас и уходит клиенту ссылкой.

Входящие: вебхук

Мы сами отправляем вам POST-запрос на каждое входящее сообщение. Один адрес на аккаунт — приходят сообщения со всех ваших номеров, а номер указан в поле profile_id.

curl -X PUT https://app.chatb24.ru/api/v1/webhook \
  -H "Authorization: Bearer cb24_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ваш-сервер.ru/chatb24-hook"}'

{"ok":true,"webhook":{"url":"https://ваш-сервер.ru/chatb24-hook","active":true},
 "secret":"5870d805c2214fc8626e84c7cc3a3dfc…"}

Секрет показывается один раз — при первой установке адреса. Сохраните его: им проверяется подпись. Смена адреса секрет не меняет и второй раз его не показывает.

Что придёт на ваш адрес:

POST /chatb24-hook
X-Chatb24-Signature: 8be91a2620f2a64d6213cc011aaaabbab47af144e8c8e4d9dca128840b83d4ff
X-Chatb24-Delivery: cc430463-be4e-45e1-ac1d-7fb651a2ee3f
Content-Type: application/json

{
  "event": "message.inbound",
  "profile_id": "9fa058c7-1bc5-4dfc-b18a-f1dbc879046a",
  "channel": "tg",
  "chat_id": "343226676",
  "sender": "Иван Петров",
  "text": "Здравствуйте, а когда будет доставка?",
  "media_url": null,
  "external_id": "tgp-343226676-4821",
  "ts": "2026-09-16T13:06:57.383Z"
}

Текст приходит текстом, вложение — ссылкой в media_url, отправитель — именем, а не числовым идентификатором. Поле external_id уникально: используйте его для защиты от повторов.

Проверка подписи

Подпись — HMAC-SHA256 от сырого тела запроса на вашем секрете. Считайте её до разбора JSON: пересборка объекта меняет байты и ломает проверку.

# Python
import hmac, hashlib
def valid(raw_body: bytes, signature: str, secret: str) -> bool:
    mine = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mine, signature)

// PHP
function valid(string $raw, string $signature, string $secret): bool {
    return hash_equals(hash_hmac('sha256', $raw, $secret), $signature);
}

// Node.js
const crypto = require('crypto');
const valid = (raw, signature, secret) =>
  crypto.timingSafeEqual(
    Buffer.from(crypto.createHmac('sha256', secret).update(raw).digest('hex')),
    Buffer.from(signature));

Если ваш сервер ответил не 2xx или не ответил вовсе — мы повторим доставку: три попытки с паузами. После этого сообщение остаётся в кабинете и в CRM, но на ваш адрес не уйдёт.

Ошибки

Код	Значение	Что делать
400	неверные поля запроса	текст ошибки объясняет, чего не хватает
401	ключ не передан, неизвестен или отозван	проверьте заголовок и ключ в кабинете
402	нет активной подписки на этот канал	оплатите канал в разделе «Подписка»
404	номер не найден	`profile_id` чужой или удалён
429	превышен лимит частоты	подождите, сколько указано в `Retry-After`
502	мессенджер не принял сообщение	в тексте ошибки — причина от мессенджера

Тело ошибки всегда одинаковое:

{"error":"bad_request","message":"Нужен адрес получателя (to)"}

Лимиты

60 запросов в минуту на ключ. Сверх лимита — ответ 429 и заголовок Retry-After с числом секунд.
Ключей на аккаунт можно создать сколько нужно — например, отдельный на каждую свою систему. Отзыв одного не трогает остальные.
Вебхук — один на аккаунт.
Размер вложения — до 30 МБ.

Мессенджеры сами не любят частых массовых отправок с личных номеров. Лимит API — это защита сервиса, а не разрешение на рассылку: рассылайте разумно, иначе номер заблокирует сам мессенджер.

Кому пригодится

Интернет-магазинам — статусы заказа в WhatsApp прямо из своей админки.
Компаниям с самописной CRM — переписка в своей системе, без перехода на чужую.
Интеграторам — свой коннектор к 1С, отраслевой или учётной системе.
Продуктовым командам — мессенджеры внутри своего SaaS или мобильного приложения.

Сколько стоит

1 490 ₽ в месяц за аккаунт — сверх подписки на подключённые номера. Доплата одна независимо от того, сколько у вас номеров: и с одним, и с десятью цена за API та же.

Первые 14 дней — бесплатно. Создайте ключ и встраивайте: плата начнётся только после пробного периода.

Как начать

Отдельной регистрации не нужно. Подключите номер, откройте в кабинете «Свой софт (API)» и создайте ключ.

Создать ключ в кабинете Тарифы

Вопросы по API — support@chatb24.ru