Документация API

Шлюз даёт HTTP API к пользовательским аккаунтам MAX, WhatsApp и Telegram в формате GREEN-API. Клиенты и SDK GREEN-API работают со шлюзом, если указать другой apiUrl. Всё, чего нет в этом документе, шлюз не поддерживает.

Машиночитаемое описание: openapi.json (OpenAPI 3.1).

Быстрый старт

1. Получите у администратора шлюза инстанс: idInstance и apiTokenInstance. Инстанс — один подключённый аккаунт мессенджера. Администратор создаёт его в панели /admin. Внешняя система создаёт инстансы сама по токену партнёра — см. Подключение SaaS к шлюзу.
2. Подключите аккаунт: откройте страницу входа qrPage и отсканируйте QR в приложении мессенджера. Для Telegram и WhatsApp есть вход по номеру.
3. Дождитесь состояния authorized (getStateInstance).
4. Отправьте сообщение:

curl -X POST "https://message.bclife.ru/waInstance1101234567/sendMessage/<apiTokenInstance>" \
  -H "Content-Type: application/json" \
  -d '{"chatId": "79991234567@c.us", "message": "Здравствуйте!"}'

{"idMessage": "3EB0C767D097B7C7C030"}

5. Получайте входящие и статусы: укажите webhookUrl в setSettings или опрашивайте receiveNotification.

Адреса и авторизация

{apiUrl}/waInstance{idInstance}/{method}/{apiTokenInstance}
{apiUrl}/v3/waInstance{idInstance}/{method}/{apiTokenInstance}     — то же самое, как в GREEN-API v3 для MAX
{apiUrl}/waInstance{idInstance}/deleteNotification/{apiTokenInstance}/{receiptId}
{apiUrl}/partner/{method}/{partnerToken}                            — или /partner/{method} + Authorization: Bearer
GET {apiUrl}/healthz                                               — {"ok": true}

• apiUrl — https://message.bclife.ru.
• idInstance — 10 цифр. Первые две цифры — мессенджер: 31 MAX, 11 WhatsApp, 41 Telegram.
• apiTokenInstance — 50 hex-символов. Даёт полный доступ к аккаунту: храните как пароль, не показывайте в браузере клиентов и не пишите в логи.
• Имена методов не зависят от регистра (sendMessage = sendmessage).
• Тело запроса — JSON до 100 КБ, заголовок Content-Type: application/json.
• Неверный токен — 401, неизвестный инстанс — 403.

Ответы и ошибки

Ошибка — JSON {"message": "…"} с HTTP-кодом:

Методы входа (sendAuthorizationPassword, startAuthorization, sendAuthorizationCode) отвечают 200 даже при неудаче — как в GREEN-API:

{"status": false, "data": {"status": "fail", "reason": "invalid_code"}}

Мессенджеры и поддержка методов

✔ — работает; Ж — ответ из журнала шлюза (у WhatsApp нет истории на сервере); — — не поддерживается.

typeInstance: v3 — MAX, whatsapp — WhatsApp, telegram — Telegram.

Идентификаторы

chatId

Допустимые форматы: число (можно со знаком минус), цифры@c.us, цифры@lid, цифры-цифры@g.us.

LID WhatsApp. WhatsApp заменяет номера на скрытые идентификаторы …@lid. По умолчанию (enableLidMode = "no") шлюз переводит LID в номер, если знает его. С enableLidMode = "yes" LID приходит как есть.

idMessage

idMessage выдаётся сразу при постановке в очередь и не меняется. Методы, которые принимают idMessage (quotedMessageId, getMessage, readChat), понимают и этот ID, и ID мессенджера.

Статусы сообщений

sent → delivered → read; ошибки — failed, noAccount (у номера нет аккаунта), notInGroup.

• WhatsApp — настоящие квитанции: сначала sent, потом delivered и read.
• MAX и Telegram не сообщают о доставке: после ответа сервера сразу delivered, потом read.
• Сообщение, которое не удалось отправить за 24 часа (например, аккаунт не подключён), получает failed.

Состояния инстанса

Каждое изменение пишется в историю (getStateInstanceHistory) и приходит уведомлением stateInstanceChanged, если stateWebhook = "yes".

Partner API

Partner API нужен внешним системам (SaaS, CRM), которые сами создают инстансы для своих клиентов.

Партнёр — такая система. Администратор шлюза создаёт партнёра в панели /admin → «Партнёры» и выдаёт ему токен партнёра (64 hex-символа). Токен показывается один раз; потерян — администратор выпускает новый.

• Партнёр видит и удаляет только свои инстансы. Чужой idInstance отвечает так же, как несуществующий.
• Администратор задаёт партнёру лимит инстансов и разрешённые мессенджеры.
• Работа с самим инстансом — обычными методами по apiTokenInstance, как в GREEN-API.

Токен передаётся одним из двух способов:

{apiUrl}/partner/{method}/{partnerToken}                                 — как в GREEN-API
{apiUrl}/partner/{method}   +  заголовок Authorization: Bearer {partnerToken}   — рекомендуем

Заголовок лучше: токен не попадает в журналы прокси и историю браузера.

Отключение партнёра закрывает только Partner API: его инстансы продолжают работать по своим apiTokenInstance.

У администратора шлюза есть ещё общий токен GATEWAY_PARTNER_TOKEN: он видит все инстансы и не ограничен лимитами. Это служебный доступ — внешним системам его не выдают.

createInstance

POST /partner/createInstance — создать инстанс. Он сразу принадлежит партнёру.

curl -X POST "https://message.bclife.ru/partner/createInstance" \
  -H "Authorization: Bearer <partnerToken>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Салон на Ленина", "messenger": "whatsapp", "webhookUrl": "https://crm.example.ru/hooks/messenger", "webhookUrlToken": "secret-for-webhook"}'

{"idInstance": 1101234567, "apiTokenInstance": "d75b3a66374942c5b3c019c698abc2067e151558acbd412345", "typeInstance": "whatsapp"}

Сохраните apiTokenInstance у себя: им подписываются все запросы к инстансу.

Telegram-инстанс создаётся, только если на шлюзе задано приложение Telegram (GATEWAY_TELEGRAM_API_ID, GATEWAY_TELEGRAM_API_HASH).

deleteInstanceAccount

POST /partner/deleteInstanceAccount — выйти из аккаунта и удалить инстанс со всеми данными (журнал, очереди, сессия). Отменить нельзя.

{"idInstance": 1101234567}

{"deleteInstanceAccount": true}

Если инстанса нет или он чужой: {"deleteInstanceAccount": false, "reason": "Instance not found"}.

getInstances

GET /partner/getInstances — инстансы партнёра. Ответ содержит их токены — не показывайте его пользователям.

[{"idInstance": 1101234567, "name": "Салон на Ленина", "typeInstance": "whatsapp",
  "apiTokenInstance": "d75b…", "stateInstance": "authorized", "timeCreated": "2026-10-25T12:00:00Z"}]

У MAX есть поле maxTransport.

getPartnerInfo

GET /partner/getPartnerInfo — сведения о партнёре: лимит, сколько инстансов создано, какие мессенджеры разрешены. Расширение шлюза; работает только с токеном партнёра.

{"partnerId": 2, "name": "Салон CRM", "status": "active", "maxInstances": 10, "instances": 3,
 "messengers": ["whatsapp", "telegram"]}

maxInstances: 0 — без лимита. Если администратор не ограничил мессенджеры, в messengers — все три.

Подключение SaaS к шлюзу

Пошагово: как внешней системе подключать аккаунты своих клиентов.

1. Получите токен партнёра у администратора шлюза. Храните его только на своём сервере: в переменной окружения или в хранилище секретов. Не кладите его в браузер, мобильное приложение или репозиторий. Проверьте токен:

curl -H "Authorization: Bearer $PARTNER_TOKEN" https://message.bclife.ru/partner/getPartnerInfo

2. Создайте инстанс для клиента (createInstance). Сразу укажите webhookUrl — адрес вашего сервера для уведомлений — и webhookUrlToken, чтобы отличать настоящие уведомления от поддельных. Сохраните у себя idInstance и apiTokenInstance.

3. Покажите клиенту QR. Ваш сервер запрашивает qr раз в 2–5 секунд и передаёт картинку в интерфейс клиента. Клиент сканирует QR в приложении мессенджера. Для WhatsApp и Telegram можно войти по номеру: getAuthorizationCode, startAuthorization.

Ссылку qrPage клиенту не отправляйте: в ней apiTokenInstance, а он даёт полный доступ к аккаунту.

4. Дождитесь подключения. Придёт уведомление stateInstanceChanged со stateInstance: "authorized". Если webhook не настроен — опрашивайте getStateInstance.

5. Отправляйте и получайте сообщения: sendMessage, входящие — incomingMessageReceived, статусы — outgoingMessageStatus. Проверяйте заголовок Authorization: Bearer <webhookUrlToken> в каждом уведомлении.

6. Клиент ушёл — удалите инстанс (deleteInstanceAccount): шлюз выйдет из аккаунта и сотрёт его данные.

Советы:

• Соблюдайте лимит: getPartnerInfo показывает, сколько инстансов осталось.
• На 429 подождите столько секунд, сколько указано в Retry-After, и повторите запрос.
• Смена токена без простоя: администратор выпускает второй токен, вы переключаетесь на него, затем администратор отзывает старый.
• Для переписки клиентов ваша система — оператор персональных данных, шлюз — обработчик. Оформите поручение обработки в договоре со шлюзом (152-ФЗ).

Аккаунт

getStateInstance

GET /waInstance{id}/getStateInstance/{token} → {"stateInstance": "authorized"}. Значения — в разделе Состояния.

getStateInstanceHistory

GET — история состояний, новые первыми (до 100 записей). timestamp — секунды.

[{"stateInstance": "authorized", "timestamp": 1761400000}, {"stateInstance": "starting", "timestamp": 1761399990}]

getSettings

GET — настройки инстанса. Описание полей — в разделе Настройки.

setSettings

POST — изменить настройки. Передавайте только те поля, которые меняете.

{"webhookUrl": "https://crm.example.ru/hooks/messenger", "webhookUrlToken": "secret", "incomingWebhook": "yes"}

{"saveSettings": true}

webhookUrl должен быть публичным адресом http(s): адреса локальной сети и localhost запрещены. wid, typeInstance, maxTransport, proxyUrl здесь не меняются.

reboot

GET — переподключиться к мессенджеру без выхода из аккаунта → {"isReboot": true}.

logout

GET — выйти из аккаунта мессенджера (на телефоне устройство исчезнет) → {"isLogout": true}. Инстанс остаётся, войти можно заново.

getWaSettings

GET — сведения о подключённом аккаунте.

{"avatar": "https://…", "phone": "79991234567", "stateInstance": "authorized", "deviceId": "…"}

Вход в аккаунт

После входа шлюз сам переподключается и после перезапуска входит без QR.

qr

GET — текущий QR-код. Код меняется каждые 20–30 секунд; QR-сессия живёт, пока метод вызывают (не реже раза в минуту).

qrPage

GET — расширение шлюза: готовая HTML-страница входа. Сама обновляет QR каждые 3 секунды и показывает состояние. Ссылка содержит токен — отправляйте её только владельцу аккаунта.

https://message.bclife.ru/waInstance1101234567/qrPage/<apiTokenInstance>

getAuthorizationCode

POST — только WhatsApp: код для «Связать по номеру телефона».

{"phoneNumber": 79991234567}

{"status": true, "code": "ABCD1234"}

При ошибке и у других мессенджеров — {"status": false}.

startAuthorization

POST — только Telegram: начать вход по номеру. Код обычно приходит в приложение Telegram, не по SMS. Состояние станет pendingCode.

{"phoneNumber": 79991234567}

{"status": true, "data": {"status": "success", "reason": ""}}

sendAuthorizationCode

POST — только Telegram: код из Telegram. Если включён облачный пароль, передайте его в password сразу или потом через sendAuthorizationPassword.

{"code": "12345", "password": ""}

sendAuthorizationPassword

POST — пароль 2FA (MAX) или облачный пароль (Telegram) в состоянии pendingPassword.

{"password": "…"}

{"status": true, "data": {"status": "success", "reason": ""}}

Отправка

sendMessage

POST — отправить текст. Сообщение встаёт в очередь, ответ приходит сразу.

{"chatId": "79991234567@c.us", "message": "Напоминаем о записи завтра в 12:00", "typingTime": 2000}

{"idMessage": "3EB0C767D097B7C7C030"}

Если аккаунт не подключён — 400 instance is starting or not authorized. Сообщения уходят строго по очереди, между ними пауза delaySendMessagesMilliseconds (по умолчанию 1000 мс). Результат отправки приходит уведомлениями outgoingAPIMessageReceived и outgoingMessageStatus.

sendTyping

POST — показать собеседнику «печатает».

{"chatId": "79991234567@c.us"}

{"result": true}

Получение уведомлений

Уведомления (входящие сообщения, статусы, смена состояния) копятся в очереди инстанса и хранятся 24 часа. Два способа их получать — выберите один:

• webhook — шлюз сам отправляет POST на webhookUrl;
• опрос — receiveNotification + deleteNotification. Работает, только пока webhookUrl пуст.

Webhook

• POST {webhookUrl}, тело — уведомление в формате раздела Уведомления, Content-Type: application/json.
• Если задан webhookUrlToken — заголовок Authorization: Bearer <webhookUrlToken>. Проверяйте его.
• Успех — любой ответ 2xx за 15 секунд. Иначе повтор через 5 с, 15 с, 30 с, далее раз в минуту, пока уведомление не устареет (24 часа).
• Уведомления идут строго по порядку: следующее ждёт, пока не доставлено предыдущее.
• webhookUrl — только публичный адрес, адреса локальной сети запрещены.

receiveNotification

GET …/receiveNotification/{token}?receiveTimeout=20 — взять первое уведомление из очереди. Если очередь пуста, запрос ждёт до receiveTimeout секунд (5–60, по умолчанию 5) и возвращает null.

{"receiptId": 15, "body": {"typeWebhook": "incomingMessageReceived", "…": "…"}}

Уведомление остаётся в очереди, пока его не удалят.

deleteNotification

DELETE …/deleteNotification/{token}/{receiptId} — удалить обработанное уведомление → {"result": true} (false — такого уже нет).

Журналы и чаты

getChatHistory

POST — последние сообщения чата, новые первыми. count — 1–1000, по умолчанию 100.

{"chatId": "79991234567@c.us", "count": 20}

[{"type": "incoming", "idMessage": "3A6B…", "timestamp": 1761400000, "typeMessage": "textMessage",
  "chatId": "79991234567@c.us", "chatType": "user", "senderId": "79991234567@c.us", "senderName": "Анна",
  "senderType": "user", "senderContactName": "", "textMessage": "Да, приду",
  "isForwarded": false, "forwardingScore": 0, "isEdited": false, "isDeleted": false},
 {"type": "outgoing", "idMessage": "3EB0…", "timestamp": 1761399000, "typeMessage": "textMessage",
  "chatId": "79991234567@c.us", "chatType": "user", "textMessage": "Напоминаем о записи",
  "statusMessage": "read", "sendByApi": true,
  "isForwarded": false, "forwardingScore": 0, "isEdited": false, "isDeleted": false}]

У WhatsApp история берётся из журнала шлюза: при подключении он заполняется перепиской за 90 дней, дальше — всеми новыми сообщениями.

getMessage

POST — одно сообщение: {"chatId": "…", "idMessage": "…"}. Ответ — элемент как в getChatHistory; нет такого — 404 message not found (у WhatsApp).

getChats

GET или POST — список чатов, count — до 1000 (по умолчанию 100): ?count=50 или {"count": 50}.

[{"chatId": "79991234567@c.us", "name": "Анна", "type": "user", "phoneNumber": "79991234567", "unreadCount": 0}]

readChat

POST — отметить прочитанным чат или сообщения до idMessage включительно.

{"chatId": "79991234567@c.us", "idMessage": "3A6B…"}

{"setRead": true}

Контакты и проверка номеров

checkAccount

POST — есть ли у номера аккаунт в мессенджере. Номер — 11–12 цифр. Результат кэшируется на 7 дней; force: true — проверить заново.

{"phoneNumber": 79991234567, "force": false}

{"exist": true, "chatId": "79991234567@c.us", "fromCache": false}

У MAX есть лимит проверок: при его превышении — 469.

checkWhatsapp

POST — то же в формате GREEN-API для WhatsApp: {"phoneNumber": 79991234567} → {"existsWhatsapp": true}. Работает у всех мессенджеров.

getContactInfo

POST — сведения о собеседнике (не о группе): {"chatId": "79991234567@c.us"}.

{"avatar": "", "name": "Анна", "contactName": "Анна Иванова", "chatId": "79991234567@c.us", "chatType": "user",
 "lastSeen": null, "phoneNumber": "79991234567", "phoneNumberTimestamp": 0, "description": ""}

getContacts

GET — адресная книга аккаунта (WhatsApp, Telegram; у MAX — 501).

[{"id": "79991234567@c.us", "name": "Анна", "contactName": "Анна Иванова", "type": "user"}]

addContact

POST — только MAX: добавить номер в контакты аккаунта. Номер — в chatId (79991234567@c.us) или phoneNumber; firstName обязателен, имена — до 100 символов.

{"chatId": "79991234567@c.us", "firstName": "Анна", "lastName": "Иванова"}

{"addContact": true}

Ошибки: 400 Contact …@c.us already exists, 404 …@c.us is not on MAX.

editContact

POST — только MAX: переименовать контакт. Поля как у addContact → {"editContact": true}.

deleteContact

POST — только MAX: {"chatId": "79991234567@c.us"} → {"deleteContact": true}.

importContacts

POST — расширение шлюза, только MAX: загрузить до 10 000 контактов. Импорт идёт в фоне порциями по 50 номеров с паузой 15 секунд и продолжается после перезапуска шлюза. Повторы номеров отбрасываются.

{"contacts": [{"phoneNumber": 79991234567, "firstName": "Анна"}, {"chatId": "79997654321@c.us", "firstName": "Олег", "lastName": "Петров"}]}

{"importId": 1, "status": "running", "total": 2}

Если MAX отвечает ошибкой лимита, импорт ставится на паузу на 2 часа (status: "paused", время продолжения — resumeAt). По окончании приходит уведомление contactsImportFinished.

Импорт контактов не защищает от блокировок: антиспам смотрит, сохранён ли ваш номер у получателя. Телефонная книга — персональные данные, на её загрузку нужно согласие.

getImportContactsStatus

POST — ход импорта: {"importId": 1, "withResults": true}.

{"importId": 1, "status": "done", "total": 2, "processed": 2, "found": 1, "notFound": 1,
 "createdAt": 1761400000, "updatedAt": 1761400030,
 "results": [{"phoneNumber": "79991234567", "exist": true, "chatId": "123456789"},
             {"phoneNumber": "79997654321", "exist": false, "chatId": ""}]}

status: running, paused, done, failed, cancelled. Нет такого импорта — 404.

cancelImportContacts

POST — отменить импорт: {"importId": 1}. Ответ — как у getImportContactsStatus без results.

Очереди

showMessagesQueue

GET — сообщения, которые ещё ждут отправки.

[{"messageID": "3EB0…", "messagesIDs": ["3EB0…"], "type": "sendMessage", "body": {"chatId": "79991234567@c.us", "message": "…"}}]

clearMessagesQueue

GET — удалить все неотправленные сообщения → {"isCleared": true}.

getMessagesCount

GET — сколько сообщений ждёт отправки → {"count": 0}.

getWebhooksCount

GET — сколько уведомлений ждёт доставки → {"count": 3}.

clearWebhooksQueue

GET — удалить все недоставленные уведомления → {"isCleared": true}.

Уведомления

Общие поля: typeWebhook, instanceData (idInstance, wid, typeInstance), timestamp (секунды).

incomingMessageReceived

{
  "typeWebhook": "incomingMessageReceived",
  "instanceData": {"idInstance": 1101234567, "wid": "79990000000@c.us", "typeInstance": "whatsapp"},
  "timestamp": 1761400000,
  "idMessage": "3A6B2C0D…",
  "senderData": {"chatId": "79991234567@c.us", "chatName": "Анна", "chatType": "user",
                 "sender": "79991234567@c.us", "senderName": "Анна", "senderType": "user",
                 "senderContactName": "Анна Иванова", "senderPhoneNumber": 79991234567},
  "messageData": {"typeMessage": "textMessage", "textMessageData": {"textMessage": "Да, приду"}}
}

outgoingMessageReceived и outgoingAPIMessageReceived устроены так же; в senderData.sender — сам аккаунт.

Типы messageData

Файлы: скачивание пока не поддерживается — downloadUrl обычно пустой (заполняется только для фото MAX). Тип, подпись и имя файла приходят.

outgoingMessageStatus

{"typeWebhook": "outgoingMessageStatus", "chatId": "79991234567@c.us",
 "instanceData": {"idInstance": 1101234567, "wid": "79990000000@c.us", "typeInstance": "whatsapp"},
 "timestamp": 1761400005, "idMessage": "3EB0C767D097B7C7C030", "status": "delivered", "sendByApi": true}

status: sent, delivered, read, failed, noAccount, notInGroup; при ошибке есть description.

stateInstanceChanged

{"typeWebhook": "stateInstanceChanged",
 "instanceData": {"idInstance": 1101234567, "wid": "79990000000@c.us", "typeInstance": "whatsapp"},
 "timestamp": 1761400000, "stateInstance": "authorized"}

contactsImportFinished

{"typeWebhook": "contactsImportFinished", "instanceData": {"idInstance": 3101234567, "wid": "", "typeInstance": "v3"},
 "timestamp": 1761400030, "importId": 1, "status": "done", "total": 2, "processed": 2, "found": 1, "error": ""}

Настройки

Флаги — строки "yes" / "no".

Не поддерживается

Эти методы GREEN-API шлюз пока не реализует (ответ 404):

• отправка файлов, геолокации, контактов, опросов: sendFileByUrl, sendFileByUpload, uploadFile, sendLocation, sendContact, sendPoll;
• скачивание файлов downloadFile;
• forwardMessages, editMessage, deleteMessage, sendReaction;
• группы: createGroup, getGroupData, участники и администраторы;
• lastIncomingMessages, lastOutgoingMessages, setProfilePicture, getAvatar и прочие методы, которых нет в этом документе.

Отличия от GREEN-API

• Расширения шлюза: qrPage, importContacts, getImportContactsStatus, cancelImportContacts, уведомление contactsImportFinished, состояние pendingCode, поля maxTransport и proxyUrl.
• Partner API: метод getPartnerInfo, токен в заголовке Authorization: Bearer, у каждого партнёра свой токен, только свои инстансы, лимиты и ограничение частоты.
• Webhook подписывается заголовком Authorization: Bearer <webhookUrlToken>.
• Telegram и WhatsApp работают через тот же адрес waInstance…; мессенджер определяется инстансом.
• Шлюз работает от имени пользовательских аккаунтов по неофициальным протоколам: мессенджер может ограничить или заблокировать аккаунт за массовые рассылки. Пишите тем, кто ждёт ваших сообщений, соблюдайте паузы и не рассылайте рекламу без согласия.