Базовый адрес: https://bizgateway.pro/api/v1. Ключ — в кабинете, раздел «API и вебхуки». Все запросы и ответы в JSON.
Заголовок X-Api-Key: <ключ> или Authorization: Bearer <ключ>. Без ключа — 401 unauthorized. Лимит: 300 запросов в минуту на ключ (429 rate_limited).
Ошибки всегда одного вида: { "error": "<код>", "message": "...", ...детали } с соответствующим HTTP-статусом.
| Метод | Путь | Описание |
|---|---|---|
| GET | /me | Аккаунт, баланс, число каналов |
| GET | /channels | Список каналов с состоянием (state: idle, connecting, qr, open, closed, logged_out) и статусом оплаты |
| GET | /channels/:id | Состояние одного канала, привязанный номер, лимиты и использование за месяц |
| Метод | Путь | Тело / ответ |
|---|---|---|
| POST | /channels/:id/messages | WhatsApp: { "phone": "+7 999 123-45-67", "text": "..." } → { id, phone, messageId, jid }Telegram: { "to": "@username | +7… | tg:<id>", "text": "..." } → { id, to, name, messageId } |
| POST | /channels/:id/messages | Ответ в известный чат (WhatsApp и Telegram): { "jid": "79991234567@s.whatsapp.net | tg:<id>", "text": "..." } → { id, messageId, jid, phone, name, kind, ts } |
| GET | /channels/:id/messages?limit=50&direction=in | Журнал: входящие и исходящие |
| GET | /channels/:id/chats?limit=50&groups=1 | Чаты из переписок (до 200, новые сверху; группы — только с groups=1): { chats: [{ jid, name, phone, username, isGroup, unread, lastMessageAt, lastText }] } |
| GET | /channels/:id/chats/:jid/messages?limit=50&before=<ts> | Сообщения чата по возрастанию времени: { jid, messages: [{ id, direction, text, type, ts, createdAt, status, senderName, deleted }] }; медиа без подписи — [фото], [голосовое], [файл: имя] |
| GET | /channels/:id/numbers/check?phone=... | { phone, exists, jid } — есть ли номер в WhatsApp (только каналы WhatsApp) |
curl -X POST https://bizgateway.pro/api/v1/channels/CHANNEL_ID/messages \
-H "X-Api-Key: ВАШ_API_KEY" -H "Content-Type: application/json" \
-d '{"phone":"+7 999 123-45-67","text":"Здравствуйте! Ваш заказ готов."}'Коды ошибок: invalid_phone 400, phone_not_on_whatsapp 422, whatsapp_not_connected 503, channel_suspended 402, plan_limit_reached 402, daily_limit_reached 429, send_failed 502.
| Метод | Путь | Тело / ответ |
|---|---|---|
| POST | /channels/:id/otp/send | { "phone": "...", "purpose": "login", "clientIp": "1.2.3.4" } → { phone, purpose, expiresInSec, resendAfterSec, messageId } |
| POST | /channels/:id/otp/verify | { "phone": "...", "code": "123456", "purpose": "login" } → { verified: true, phone, purpose } |
Код действует 5 минут, 5 попыток, повтор не чаще раза в 60 секунд, не больше 5 кодов в час на номер и 30 на clientIp. Ошибки: invalid_code (с attemptsLeft), code_expired, code_not_found, too_many_attempts, resend_too_soon, too_many_requests.
Укажите URL и получите секрет в кабинете. Мы отправляем POST с JSON { event, data, sentAt }, заголовками X-Event и X-Signature: sha256=<HMAC-SHA256(secret, тело)>. Три повтора с паузами 1, 3 и 9 секунд; отвечайте 2xx быстро.
| Событие | data |
|---|---|
message.received | { channelId, channelKind, jid, phone, name, username, text, messageId, ts, fromMe: false, direction: "in", isGroup, id, from, pushName, timestamp } |
message.sent | { channelId, channelKind, jid, phone, name, username, text, messageId, ts, fromMe: true, direction: "out", source } |
channel.state | { channelId, state, connected, phone, lastDisconnect } |
channel.suspended | { channelId, reason, plan, price } |
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhook(rawBody: string, signature: string | undefined, secret: string) {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
return !!signature && signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}Партнёрские сервисы подключаются кнопкой «Подключить BizGateWay»: пользователь входит и разрешает доступ, сервис получает токен.
| Шаг | Запрос |
|---|---|
| 1 | GET /oauth/authorize?client_id=…&redirect_uri=…&state=… → после согласия редирект на redirect_uri?code=…&state=… (отказ — error=access_denied) |
| 2 | POST /oauth/token { grant_type: "authorization_code", code, client_id, client_secret, redirect_uri } → { access_token, token_type: "Bearer", account }. Код одноразовый, живёт 5 минут |
| 3 | Все запросы /api/v1 — с Authorization: Bearer <access_token> |
PUT /api/v1/app/webhook { url } → { url, secret } — свой адрес и секрет вебхука у подключения; DELETE /api/v1/app/connection — отключиться |