Как подключить WhatsApp API за 5 минут: свой номер по QR или коду

Что подготовить

• Телефон с номером, который будете подключать: приложение WhatsApp или WhatsApp Business — подходят оба.
• Компьютер с кабинетом, если будете сканировать QR-код. Если кабинет открыт на том же телефоне, удобнее привязка кодом по номеру.
• От 1 000 ₸ для пополнения баланса — Kaspi или счёт на ТОО/ИП. Бесплатного теста нет; при добавлении номера сразу списывается первый день, 330 ₸.
• Доступ к интернету на телефоне — во время привязки и потом периодически.

Пошагово

Шаг 1. Зарегистрируйтесь

Откройте регистрацию и создайте аккаунт: email и пароль или вход через Google.

Шаг 2. Пополните баланс

В разделе «Баланс» выберите способ: Kaspi — счёт придёт в приложение Kaspi, или счёт на ТОО/ИП — укажите название и БИН, счёт сформируется сразу. Минимум — 1 000 ₸, этого хватит одному номеру на три дня. Номер стоит 9 900 ₸ в месяц, списание по дням; подробности — на странице цен. Оплаты картой пока нет.

Шаг 3. Добавьте номер в кабинете

Дайте номеру понятное название: «Отдел продаж», «Филиал на Абая». Название потом видно в API, и по нему удобно различать номера. В момент добавления спишется первый день — 330 ₸.

Шаг 4. Привяжите WhatsApp по QR-коду или коду

Кабинет предложит два способа — выберите удобный.

QR-код — если кабинет открыт на компьютере:

1. Откройте WhatsApp на телефоне: на iPhone — «Настройки», на Android — меню ⋮.
2. Нажмите «Связанные устройства» → «Привязка устройства».
3. Наведите камеру на QR-код в кабинете.

Код по номеру — если кабинет открыт на том же телефоне и сканировать нечего:

1. В кабинете выберите привязку по номеру телефона — появится 8-значный код.
2. В WhatsApp откройте «Связанные устройства» → «Привязка устройства».
3. Нажмите «Привязать по номеру телефона» и введите код.

Через несколько секунд кабинет покажет, что номер подключён, а в WhatsApp в списке связанных устройств появится новое. Подробнее о том, что это значит, — в глоссарии: QR-код, код по номеру, связанное устройство.

Шаг 5. Возьмите API-ключ

Ключ аккаунта лежит в разделе «API и MCP». Он работает со всеми вашими номерами, а нужный номер выбирается полем from. Если интеграцию делает подрядчик, выпустите ему отдельный ключ номера в карточке номера: он работает только с этим номером и не видит баланс.

Шаг 6. Отправьте тестовое сообщение

Сначала — кнопкой теста в кабинете: так вы проверите, что номер работает, без единой строчки кода. Затем — тем же запросом, которым будет пользоваться ваша программа. Для теста удобно писать на свой второй номер или самому себе: сообщения в чат с самим собой не идут в лимит новых контактов.

export W_API_KEY="ваш_ключ"

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":"Тест: WhatsApp API подключён"}'

Номер в to — 10–15 цифр с кодом страны; для Казахстана он начинается с 7. Отправка — только в личные чаты. Если на аккаунте подключён один номер, from можно не указывать. Когда номеров несколько, добавьте "from":1 — id номера из GET /numbers. Успешный ответ:

{"ok":true,"id":1842,"wa_message_id":"3EB0A1F2C4D5E6F7","from":{"id":1,"phone":"77010000000"}}

Примеры на Node.js, Python и PHP — в гайде «Как отправить сообщение через API» и в документации.

Шаг 7. Задайте вебхук

Чтобы получать входящие сообщения, укажите адрес вашего сервера в кабинете: на карточке номера — для одного номера, или в разделе «API и MCP» — для всех сразу. Адрес должен быть публичным и начинаться с https://. Подписи у вебхуков нет, поэтому добавьте в адрес секрет и проверяйте его.

Минимальный обработчик на Node.js:

const express = require("express");
const app = express();

app.post("/whatsapp/webhook", express.json(), (req, res) => {
  if (req.query.token !== process.env.WAPI_HOOK_TOKEN) return res.sendStatus(403);
  res.sendStatus(200); // ответить сразу, обработать — после
  const e = req.body;
  if (e.event === "message" && e.payload.from.endsWith("@c.us")) {
    const client = e.payload.from.split("@")[0];
    console.log(e.wapi.number_id, client, e.payload.body);
  }
});

app.listen(3000);

Отвечайте кодом 200 быстрее 10 секунд, а тяжёлую работу делайте после ответа. Повторной отправки нет: если сервер был недоступен, пропущенное заберите из истории через GET /messages?since=…. Все события и поля — в разделе документации о вебхуках и в гайде про вебхуки.

Какой номер подключать

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

Не стоит подключать новую SIM-карту, купленную вчера, и сразу запускать с неё много сообщений. Новые номера с резкой активностью WhatsApp ограничивает чаще. Поэтому у каждого номера в wapi.kz первые две недели действует прогрев — мягкий старт с меньшими лимитами:

Полные лимиты зависят от индекса доверия номера, они описаны в разделе лимитов. Прогрев — это защита номера в первые дни, а не способ подготовить его к рассылкам: писать стоит тем, кто ждёт сообщение. Подробнее — в гайде «Как не получить блокировку».

WhatsApp или WhatsApp Business — разницы для подключения нет. Если номер уже привязан к другому сервису автоматизации, отвяжите его там, чтобы две программы не отвечали клиентам одновременно.

Телефон должен выходить в интернет

Сервис работает как связанное устройство, а по правилам WhatsApp связанные устройства отключаются, если телефон не выходит в сеть около 14 дней. Держать телефон включённым круглосуточно не нужно — достаточно, чтобы он периодически бывал онлайн.

Если номер всё-таки отключился, вы узнаете об этом: придёт вебхук session.status, и мы тоже пришлём уведомление. Переподключите номер в кабинете тем же QR-кодом или кодом.

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

• QR-код истёк. Код живёт недолго и обновляется. Если камера не успела, обновите его в кабинете и отсканируйте сразу.
• WhatsApp пишет «попробуйте позже». Это ограничение самого WhatsApp на слишком частые привязки устройств. Подождите и попробуйте другой способ: вместо QR — код по номеру или наоборот.
• Код по номеру не принимается. Проверьте, что вводите его в WhatsApp именно того номера, который добавили в кабинете, и что код свежий. Не помогло — запросите новый код.
• Номер привязан, но отправка возвращает 409 not_connected. Посмотрите статус запросом ниже: WORKING — всё в порядке, SCAN_QR_CODE или STARTING — подключение ещё идёт, FAILED или STOPPED — переподключите номер в кабинете.
• Ответ 402 number_paused. На балансе не хватает денег на сутки. Пополните — номер включится сам, привязка сохранится.

curl https://wapi.kz/api/v1/numbers \
  -H "Authorization: Bearer $W_API_KEY"

Остальные коды ошибок — в разделе ошибок и в гайде по решению проблем. Не получилось — напишите в поддержку, Telegram-бот @wapi_kz_support_bot. Если подключить номер не получится по нашей вине, вернём деньги.

Что дальше

Номер подключён — дальше всё зависит от задачи. Связать с CRM или сайтом — раздел интеграций. Отвечать клиентам с помощью ИИ — гайд про ИИ-агента через MCP. Подключить ещё номера для отделов или филиалов — гайд про несколько номеров.