SEBE APIофициальный WhatsApp Business API

API нужен, чтобы отправлять сообщения WhatsApp из вашей CRM, сайта или сервиса и получать входящие сообщения вебхуками. Всё работает через номер, подключённый в кабинете SEBE.

Доступ

Создайте ключ в кабинете: «API и вебхуки» → «Создать ключ». Передавайте его в каждом запросе:

Authorization: Bearer sk_live_…

Адрес API: https://sebe.kz/app/v1. Лимит - 100 запросов в минуту на ключ. Ответы - JSON. Ошибка: { "error": { "code": "…", "message": "…" } }.

Номера

GET/v1/numbers - подключённые номера компании: id, phone, status, quality. Если номеров несколько, указывайте number_id при отправке.

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

POST/v1/messages

Текст

Свободный текст можно отправить только в течение 24 часов после последнего сообщения клиента. Иначе - код window_closed, нужен шаблон.

{
  "to": "77011234567",
  "type": "text",
  "text": "Здравствуйте! Ваш заказ готов."
}

Шаблон

Одобренный Meta шаблон. Им можно написать клиенту первым и в любое время. params - значения подстановок {{1}}, {{2}}… по порядку.

{
  "to": "77011234567",
  "type": "template",
  "template": { "name": "order_ready", "language": "ru", "params": ["Айгерим", "№1456"] }
}

Для шаблонов с заголовком-картинкой или кнопками-ссылками передайте components в формате Meta вместо params.

Ответ 201: { "data": { "id": 812, "wamid": "wamid.HBgL…", "status": "sent", "conversation_id": 54 } }. Дальше статус меняется на delivered, read или failed - приходит вебхуком message.status.

GET/v1/messages/{id} - сообщение и его текущий статус.

Диалоги

GET/v1/conversations - последние диалоги. Параметры: number_id, wa_id (номер клиента), limit (до 100), before_id. В ответе window_open - можно ли писать текстом.

GET/v1/conversations/{id}/messages - переписка, новые в начале. Параметры: limit, before_id.

Шаблоны

GET/v1/templates - шаблоны номера и их статус (APPROVED, PENDING, REJECTED…).

POST/v1/templates - создать и отправить на проверку Meta:

{
  "name": "order_ready",
  "language": "ru",
  "category": "UTILITY",
  "header": "Заказ готов",
  "body": "Здравствуйте, {{1}}! Заказ {{2}} можно забрать.",
  "examples": ["Айгерим", "№1456"],
  "footer": "Магазин Береке",
  "buttons": [{ "type": "quick", "text": "Спасибо" }, { "type": "url", "text": "Где забрать", "url": "https://example.kz/map" }]
}

DELETE/v1/templates/{id} - удалить (и в Meta).

Вебхуки

В кабинете: «API и вебхуки» → «Добавить адрес». Мы присылаем POST с телом:

{ "event": "message.received", "created_at": "2026-10-06T12:00:00.000Z", "data": { … } }

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

Заголовки: X-Sebe-Timestamp и X-Sebe-Signature: sha256=… - HMAC-SHA256 от строки timestamp + "." + тело запроса секретом адреса (показывается один раз при создании). Отклоняйте запросы старше 5 минут.

const crypto = require('crypto');
function verify(req, rawBody, secret) {
  const ts = req.headers['x-sebe-timestamp'];
  const expect = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const got = Buffer.from(String(req.headers['x-sebe-signature'] || ''));
  const want = Buffer.from(expect);
  return got.length === want.length && crypto.timingSafeEqual(got, want) && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
}

Ответьте 2xx в течение 10 секунд. Иначе повторим через 1, 5 и 30 минут, 2 и 6 часов. Журнал доставки - в кабинете.

Частые ошибки

Правила WhatsApp

Пишите первым только тем, кто согласился получать сообщения от вашей компании. Рекламные шаблоны (категория MARKETING) Meta ограничивает по частоте. Много жалоб - Meta понижает качество номера и лимит рассылок.