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

Авторизация

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

Authorization: Bearer <API_KEY>

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

Поле to — номер получателя в международном формате, только цифры (для Казахстана начинается с 7).

{
  "to": "77011234567",
  "text": "Ваш заказ №1042 готов к выдаче"
}

Изображение с подписью:

{
  "to": "77011234567",
  "image": { "url": "https://example.kz/check.jpg", "caption": "Ваш чек" }
}

Ответ:

{ "ok": true, "id": "3EB0A1F2C4D5E6F7", "status": "sent" }

Статус подключения

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

{ "status": "WORKING", "phone": "77011234567", "paid_until": "2026-11-15T14:33:16.206Z" }

Возможные статусы: WORKING (подключён, можно отправлять), SCAN_QR_CODE (ждёт сканирования), STARTING, FAILED / STOPPED (переподключите в кабинете), none (ещё не подключали).

Аккаунт

Данные аккаунта и срок оплаты.

{ "email": "you@company.kz", "company": "ТОО «Ромашка»", "paid_until": "2026-11-15T14:33:16.206Z",
  "wa_status": "WORKING", "wa_phone": "77011234567" }

Проверка номера

Есть ли номер в WhatsApp — проверяйте перед первой отправкой: меньше ошибок доставки и выше индекс доверия. До 200 проверок в сутки, не чаще 1 в секунду.

curl -X POST https://wapi.kz/api/v1/contacts/check \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"phone":"77011234567"}'

{ "phone": "77011234567", "exists": true, "chat_id": "77011234567@c.us" }

Лимиты и индекс доверия

Сколько ещё можно отправить сегодня и индекс доверия номера (0–100).

{
  "rating": 74, "tier": "good", "tier_title": "Хороший", "enough_data": true,
  "limits": { "messages_per_day": 1000, "new_contacts_per_day": 150, "checks_per_day": 200, "messages_per_second": 1 },
  "used": { "messages": 312, "new_contacts": 18, "checks": 40 },
  "cold_blocked_until": null, "warmup": false
}

Индекс считается по последним 14 дням: доля диалогов, которые начали клиенты; отвечают ли люди на ваши первые сообщения; баланс входящих и исходящих; объём холодных первых сообщений; ошибки доставки; сколько номер уже работает у нас. Пока сообщений меньше ~20 — действуют стандартные лимиты.

Первые 3 дня после подключения — прогрев: 200 сообщений и 30 новых контактов в сутки (с тем же множителем).

Защита от рассылок. Если один и тот же текст ушёл 25+ новым людям за час или за час появилось 40+ новых контактов, первые сообщения новым людям приостанавливаются на 24 часа. Отвечать тем, кто вам пишет, можно. Это защищает ваш номер от блокировки WhatsApp.

Вебхуки

Укажите URL в кабинете — мы будем отправлять на него POST-запросы с событиями. Отвечайте кодом 200 в течение 10 секунд.

Входящее сообщение — message

{
  "event": "message",
  "timestamp": 1792154662,
  "data": {
    "id": "3EB0B7C1D2E3F4A5",
    "from": "77011234567",
    "name": "Айгерим",
    "text": "Здравствуйте, заказ ещё в силе?",
    "hasMedia": false
  }
}

Статус доставки — message.ack

{
  "event": "message.ack",
  "timestamp": 1792154700,
  "data": { "id": "3EB0A1F2C4D5E6F7", "to": "77011234567", "ack": "read" }
}

Значения ack: sent, delivered, read, failed.

Смена статуса подключения — session.status

{
  "event": "session.status",
  "timestamp": 1792154800,
  "data": { "status": "disconnected" }
}

Ошибки и лимиты

Ошибка возвращается в виде { "error": "описание" }.

Лимит — до 1 сообщения в секунду на номер: так меньше риск блокировки со стороны WhatsApp. Не делайте массовых рассылок незнакомым людям — это главная причина блокировок.

Примеры кода

curl

curl -X POST https://wapi.kz/api/v1/messages/send \
  -H "Authorization: Bearer $W_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"77011234567","text":"Здравствуйте!"}'

Node.js

const res = await fetch("https://wapi.kz/api/v1/messages/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.W_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "77011234567", text: "Здравствуйте!" }),
});
console.log(await res.json());

Python

import os, requests

r = requests.post(
    "https://wapi.kz/api/v1/messages/send",
    headers={"Authorization": f"Bearer {os.environ['W_API_KEY']}"},
    json={"to": "77011234567", "text": "Здравствуйте!"},
    timeout=15,
)
print(r.json())

MCP: подключите WhatsApp к Claude Code или Codex

MCP-сервер даёт ИИ-агенту инструменты send_message, get_status, get_limits и check_number. Агент сможет сам отправлять сообщения и встроить WhatsApp в ваш проект.

Claude Code — одной командой

claude mcp add --transport http wapi https://wapi.kz/api/mcp \
  --header "Authorization: Bearer <API_KEY>"

Конфиг для любого MCP-клиента

{
  "mcpServers": {
    "wapi": {
      "type": "http",
      "url": "https://wapi.kz/api/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}