Глоссарий WhatsApp API: термины простыми словами

API

API (application programming interface) — способ, которым одна программа управляет другой без участия человека: отправляет команды и получает ответы. WhatsApp API — это когда ваша CRM, сайт или бот сами отправляют и читают сообщения WhatsApp, а не менеджер вручную. В wapi.kz API работает с вашим обычным номером WhatsApp или WhatsApp Business: номер подключается как связанное устройство, а программа общается с ним через HTTP-запросы. Подробнее — в гайде что такое WhatsApp API.

REST API

REST API — самый распространённый стиль API: у каждой операции свой адрес (эндпоинт) и HTTP-метод, например GET — получить данные, POST — отправить. У wapi.kz базовый адрес https://wapi.kz/api/v1: POST /messages/send отправляет сообщение, GET /messages отдаёт журнал, GET /numbers — список номеров, GET /balance — баланс. Отдельных библиотек и SDK нет и не нужно — хватает любого HTTP-клиента: curl, fetch в Node.js, requests в Python, cURL в PHP или HTTPСоединение в 1С. Готовые запросы на curl, Node.js и Python — в разделе примеры кода.

JSON

JSON — текстовый формат данных из пар «ключ: значение», в котором программы обмениваются информацией. Все запросы и ответы wapi.kz — JSON в кодировке UTF-8, поэтому кириллица в сообщениях передаётся без перекодировки. Тело отправки выглядит так: {"to":"77011234567","text":"Заказ готов","from":1}. Если тело запроса — не JSON-объект, API вернёт ошибку invalid_json с кодом HTTP 400. Все поля отправки — в разделе отправка сообщения.

Код ответа HTTP

Код ответа HTTP — трёхзначное число, по которому программа сразу понимает результат запроса: 200 — всё хорошо, 4xx — ошибка в запросе, 5xx — сбой на стороне сервиса или WhatsApp. В wapi.kz тело ошибки всегда одинаковое: { "error": "текст по-русски", "code": "машинный_код" }, и в программе проверять стоит именно code. Основные коды: 400 — неверный запрос (invalid_to, text_too_long), 401 — нет ключа или он неверный, 402 — номер на паузе, 403 — действие запрещено для ключа номера, 404 — не найдено, 409 — номер не добавлен или не подключён, 429 — превышен лимит, 502 — WhatsApp не принял сообщение, 503 — номер перезапускается. На 503 повторите запрос через пару минут, а на 429 сначала посмотрите code: часть лимитов обновляется только в полночь. Полная таблица — в разделе «Ошибки».

API-ключ

API-ключ — секретная строка, по которой сервис понимает, что запрос пришёл именно от вас. В wapi.kz ключ аккаунта берут в кабинете, в разделе «API и MCP», и передают в каждом запросе заголовком Authorization: Bearer <API_KEY> (или X-Api-Key: <API_KEY>). Ключ аккаунта работает со всеми вашими номерами, поэтому храните его в переменной окружения на сервере, а не в коде страницы сайта. Без ключа API ответит unauthorized, с неверным ключом — invalid_key (оба HTTP 401), а если ключ утёк, перевыпустите его в кабинете: старый сразу перестанет работать. Подробнее — в разделе авторизация.

Ключ номера

Ключ номера — отдельный API-ключ, который выпускается в карточке номера и работает только с этим номером. Его удобно отдавать подрядчику или интеграции: поле from не нужно, к другим номерам доступа нет (number_not_found), а баланс и данные аккаунта — /balance, /me и MCP-инструмент get_balance — отвечают forbidden_for_number_key (HTTP 403). На один номер можно выпустить до 5 ключей и отзывать каждый отдельно, а при удалении номера все его ключи перестают работать. Когда это нужно и как раздать доступы — в гайде ключ API на каждый номер.

Номер отправителя (from)

from — параметр, которым вы выбираете, с какого из своих номеров работать: id номера из GET /numbers (например, 1) или его телефон (77010000000). В POST-запросах это поле тела, в GET — параметр строки запроса. Если from не указан и подключённый номер один, берётся он; если подключённых несколько, отправка вернёт from_required, а GET /messages, /chats и /export отдадут данные всех номеров. Номер, которого нет в аккаунте, даёт ошибку number_not_found, а значение, которое не похоже ни на id, ни на телефон, — invalid_from. Все случаи собраны в разделе номер отправителя.

Международный формат номера (E.164)

E.164 — международный стандарт записи телефонных номеров: код страны, затем сам номер, всего не больше 15 цифр. В API wapi.kz номер получателя to — 10–15 цифр с кодом страны: плюс, пробелы, скобки и дефисы сервер отбросит сам, а меньше 10 или больше 15 цифр — ошибка invalid_to (HTTP 400). Для Казахстана номер начинается с 7: не 8 701 123-45-67, а 77011234567. Восьмёрку в начале сервер на семёрку не меняет — 87011234567 формально проходит проверку, но уйдёт не туда, поэтому приводите такие номера к виду с 7 у себя перед отправкой. Первую отправку пошагово разбираем в гайде как отправить сообщение через API.

Вебхук (webhook)

Вебхук — адрес вашего сервера, на который сервис сам присылает событие, как только оно произошло: не вы спрашиваете «есть новое?», а вам сообщают. В wapi.kz вебхук задаётся в кабинете — на карточке номера (для одного номера) или в «API и MCP» (для всех); принимаются только публичные адреса https://. Приходят события message (входящее от собеседника), message.out (человек написал с вашего номера с телефона), message.ack (статус доставки), session.status (изменилось подключение), export.ready (готов архив переписки) и storage.warning (предупреждение по хранилищу файлов). Отвечайте 200 за 10 секунд; повторной отправки и подписи нет, поэтому пропущенное забирайте через GET /messages?since=…, а в адрес добавьте секрет вроде ?token=… и проверяйте его. Пошагово — в гайде вебхуки WhatsApp.

Опрос по таймеру (polling)

Polling — способ узнавать о новых данных, регулярно спрашивая сервер по таймеру: «что нового с такого-то времени?». Это проще вебхука, потому что не нужен публичный адрес, но новые сообщения вы видите с задержкой, равной интервалу опроса. В wapi.kz опрос делается запросом GET /messages?since=…&direction=in, например раз в минуту, и он же помогает добрать события, пропущенные вебхуком. Так же приходится работать с Kaspi: вебхуков для продавцов у него нет, и заказы опрашивают по таймеру. Параметры запроса — в разделе история сообщений.

MCP (Model Context Protocol)

MCP — открытый протокол, через который ИИ-агенты подключают внешние инструменты: агент видит список доступных действий и сам решает, когда их вызвать. У wapi.kz есть MCP-сервер https://wapi.kz/api/mcp (HTTP, JSON-RPC 2.0, тот же API-ключ) с 10 инструментами: send_message, list_numbers, get_messages, get_media, create_export, get_export, get_balance, get_limits, check_number и get_status. В Claude Code он добавляется одной командой claude mcp add --transport http wapi https://wapi.kz/api/mcp --header "Authorization: Bearer <API_KEY>", а в Codex, Cursor и других клиентах — как HTTP MCP-сервер по инструкции клиента, с тем же адресом и заголовком. Сообщения, которые отправил агент, попадают в журнал с source: "mcp". Пошагово — в гайде WhatsApp для ИИ-агента через MCP.

ИИ-агент

ИИ-агент — программа на основе языковой модели (например, Claude или ChatGPT), которая не просто отвечает текстом, а сама выполняет действия: читает переписку, проверяет данные, отправляет сообщения. К WhatsApp агент подключается через MCP или, если вы пишете его сами, через REST API и вебхуки. Полезное правило: перед ответом агент смотрит последние сообщения чата, и если там есть source: "phone", разговор уже ведёт человек — вмешиваться не стоит. Агент работает в тех же лимитах и с тем же индексом доверия, что и любая программа на этом номере. Сценарии и архитектура — в гайде ИИ-бот для WhatsApp.

QR-код

QR-код — основной способ привязать номер к wapi.kz, точно так же, как вы входите в WhatsApp Web. После добавления номера в кабинете на экране появится QR-код; на телефоне откройте WhatsApp → Настройки → Связанные устройства → Привязка устройства и наведите камеру на экран. Пока номер ждёт сканирования, его wa_status — SCAN_QR_CODE. Способ удобен, когда кабинет открыт на компьютере, а если он открыт на том же телефоне, где стоит WhatsApp, проще код привязки.

Код привязки (pairing code)

Код привязки — замена QR-коду, когда сканировать нечем: например, кабинет открыт на том же телефоне, где установлен WhatsApp. В кабинете вы получаете 8-значный код, а в WhatsApp открываете Связанные устройства → Привязка устройства → «Привязать по номеру телефона» и вводите его. Результат тот же, что и с QR: номер становится связанным устройством, и после подключения его статус сменится на WORKING. Весь путь от регистрации до первого сообщения занимает около 5 минут — он описан в гайде подключение WhatsApp API.

Связанное устройство (linked device)

Связанное устройство — функция самого WhatsApp: к одному номеру можно подключить компьютер, браузер или другой клиент, а основным остаётся телефон. wapi.kz подключается именно так, как WhatsApp Web: номер и приложение остаются у вас, вы продолжаете переписываться с телефона, а сообщения, набранные на нём, тоже попадают в журнал. По правилам WhatsApp связанные устройства отключаются, если телефон не выходит в интернет около 14 дней, поэтому хотя бы иногда держите его в сети. Если подключение слетело — например, устройство удалили в списке на телефоне, — придёт вебхук session.status, мы тоже пришлём уведомление, а переподключиться можно по QR или коду. Как следить за подключением, описано в термине сессия.

Сессия (session)

Сессия — активное подключение вашего номера к WhatsApp через wapi.kz; у каждого номера она своя. Её состояние показывает поле wa_status в ответе GET /numbers: WORKING — подключён и можно отправлять, SCAN_QR_CODE — ждёт сканирования, STARTING — запускается, FAILED или STOPPED — отключился и требует переподключения в кабинете, none — ещё не запускался. Каждое изменение статуса приходит вебхуком session.status, так что мониторинг можно построить и без постоянных запросов. Отправка с неподключённого номера вернёт not_connected (HTTP 409), а пока номер перезапускается — capacity (HTTP 503). Все поля номера — в разделе номера.

chat_id

chat_id — идентификатор чата в WhatsApp, который приходит в истории, списке чатов и проверке номера. Личный чат выглядит как 77011234567@c.us (телефон собеседника плюс @c.us), личный чат со скрытым номером — как …@lid, группа — как …@g.us; в вебхуке тот же формат лежит в поле payload.from, и, отрезав @c.us, вы получите номер клиента. Параметр chat в GET /messages принимает и телефон, и chat_id. Отправлять через API можно только в личные чаты, а во входящих из групп автора сообщения показывает поле payload.participant. Список чатов со счётчиками сообщений — в разделе чаты.

LID

LID — скрытый идентификатор собеседника вида …@lid, который WhatsApp иногда показывает вместо телефона. Это функция приватности самого WhatsApp: в таком чате номер собеседника не раскрывается. В журнале и списке чатов wapi.kz у таких собеседников поле peer — телефон, если WhatsApp его сообщил, иначе null, а сам идентификатор лежит в peer_lid. Цифры LID — не телефон, и за телефон мы их не выдаём. Если ваша CRM ищет клиента по телефону, заранее предусмотрите случай peer: null. Про форматы чатов — в термине chat_id.

wa_message_id

wa_message_id — идентификатор сообщения внутри самого WhatsApp, в отличие от id — номера сообщения в журнале wapi.kz. Оба приходят в ответе на POST /messages/send, например "id": 1842, "wa_message_id": "3EB0A1F2C4D5E6F7", а у исходящего, которое WhatsApp ещё не принял, wa_message_id равен null. В вебхуке отдельного поля нет: идентификатор спрятан в payload.id вида true_77011234567@c.us_3EB0A1F2C4D5E6F7 — это третья часть между символами «_». По нему вы связываете событие message.ack со своим отправленным сообщением. Разбор полей события — в разделе вебхуки.

Статус доставки

Статус доставки показывает, что стало с исходящим сообщением, — те самые галочки в WhatsApp. В журнале wapi.kz поле status принимает значения queued (принято, ждёт отправки), sent (одна галочка), delivered (две галочки), read (прочитано) и failed (не доставлено, причина — в поле error), а входящие сохраняются со статусом delivered. Изменения приходят вебхуком message.ack с полем payload.ack: 1 — отправлено, 2 — доставлено, 3 — прочитано, 4 — голосовое прослушано, -1 — ошибка. Статус одного сообщения в любой момент отдаёт GET /messages/{id}. Как использовать статусы в уведомлениях клиентам — в гайде уведомления через WhatsApp API.

Источник сообщения (source)

source — поле журнала, которое говорит, кто написал сообщение: номер остаётся на телефоне, и в одном чате могут писать и программа, и человек. Значения: api — ваша программа, mcp — ИИ-агент через MCP, test — тест из кабинета, phone — человек с телефона или из WhatsApp Web/Desktop, contact — собеседник, system — служебное сообщение. На этом поле строится передача разговора между ботом и менеджером: увидели phone в последних сообщениях — бот молчит. В вебхуках то же видно по событию: message — пишет собеседник, message.out — человек с вашего номера. Таблица значений — в разделе кто написал.

История сообщений

История, или журнал сообщений, — все входящие и исходящие сообщения ваших номеров с момента подключения, включая набранные на телефоне, вместе с фото, видео, голосовыми и документами. wapi.kz хранит их в Казахстане: текст — без срока и ограничений объёма, файлы — 5 ГБ на аккаунт бесплатно, сверх — 1 000 ₸ в месяц за каждые 5 ГБ (хранилище). Её отдаёт GET /messages с фильтрами from, chat, since, until и direction: новые сверху, по умолчанию 50 записей, максимум 500, следующая страница — через before со значением next_before из прошлого ответа. Хранение переписки можно выключить в настройках: тогда text будет null и новые файлы не сохранятся, а время, направление и статус останутся, причём уже сохранённые тексты при выключении стираются. Как строить на истории отчёты и контекст для бота — в гайде история сообщений через API.

Выгрузка (export)

Выгрузка — история сообщений одним файлом за период: для отчётов, архива или переноса в свою базу. Запрос GET /export?from=&since=&until=&format=csv|json отдаёт до 100 000 сообщений за раз, старые сверху, а без from — по всем номерам. CSV в UTF-8 открывается в Excel (текст, который начинается с =, +, - или @, получает апостроф, чтобы Excel не принял его за формулу), JSON повторяет формат GET /messages. Выгружаются только сообщения; переписку вместе с файлами собирает POST /exports — ZIP-архив с файлами, messages.json и messages.csv, ссылка на него живёт 7 дней (см. выгрузки архивом). Пример запроса — в разделе выгрузка.

Лимиты

Лимиты — сколько сообщений номер может отправить за сутки; в wapi.kz они считаются для каждого номера отдельно и зависят от его индекса доверия. Базовый уровень «Хороший» (индекс 60–79) — 1 000 сообщений и 150 первых сообщений новым людям в сутки; «Отличный» (80–100) — в 1,5 раза больше, то есть 1 500 и 225; «Средний» (40–59) — ×0,6; «Низкий» (20–39) — ×0,3 сообщений и ×0,2 новых; «Критический» (0–19) — ×0,3 сообщений, а первые сообщения новым людям закрыты. Отдельно — до 200 проверок номера в сутки; сутки считаются по Алматы, и счётчики обновляются в полночь. Текущие лимиты и сколько уже использовано, показывают GET /limits?from= и карточка номера в кабинете. У самого WhatsApp публичных лимитов нет — это наши правила, чтобы снизить риск блокировки, и гарантий «без блокировок» не даёт никто.

Ограничение частоты (rate limit)

Rate limit — ограничение не на объём за сутки, а на скорость: сколько запросов можно сделать за короткий промежуток времени. В wapi.kz с одного номера — не чаще 1 сообщения в секунду, первые сообщения новым людям — не чаще раза в 5 секунд, проверки номера — не чаще 1 в секунду. Превышение даёт ошибку rate_limited (HTTP 429); правильная реакция — поставить сообщения в очередь и отправлять их с паузой, а не повторять запрос в цикле. Суточные лимиты отвечают другими кодами: daily_limit, new_contacts_limit, checks_limit. Разбор этих и других ошибок — в гайде решение проблем с WhatsApp API.

Новый контакт

Новый контакт — человек, которому ваш номер пишет первым, без предыдущей переписки. Именно такие сообщения самые рискованные: массовые первые сообщения незнакомым людям — главная причина блокировок в WhatsApp. Поэтому в wapi.kz на них отдельный лимит — 150 в сутки на уровне «Хороший» (при превышении — new_contacts_limit) и пауза не меньше 5 секунд между ними; сообщения в чат с самим собой в этот лимит не входят. Перед первой отправкой номер стоит проверить через POST /contacts/check — меньше ошибок доставки и выше индекс доверия. Формат запроса — в разделе проверка номера.

Прогрев номера (warmup)

Прогрев — первые 2 недели после подключения номера к wapi.kz, когда лимиты растут ступенями, чтобы новый для сервиса номер не начинал сразу с полной нагрузки. Дни 1–3 — 200 сообщений и 20 новых контактов в сутки, дни 4–7 — 400 и 40, дни 8–14 — 700 и 80, дальше — полные лимиты по индексу доверия. Пока прогрев идёт, GET /limits показывает warmup: true. Прогрев — защитная ступенька, а не способ «раскачать» номер под рассылки: холодные массовые сообщения опасны и после него. Какие лимиты действуют после прогрева — в термине лимиты.

Индекс доверия

Индекс доверия — оценка номера от 0 до 100, которую wapi.kz считает по последним 14 дням и от которой зависят лимиты. В расчёт входят доля диалогов, начатых клиентами, отвечают ли люди на ваши первые сообщения, баланс входящих и исходящих, объём холодных первых сообщений, ошибки доставки и то, сколько номер уже работает у нас. Уровни: 80–100 «Отличный», 60–79 «Хороший», 40–59 «Средний», 20–39 «Низкий», 0–19 «Критический», а пока сообщений меньше ~20, действуют стандартные лимиты. Индекс виден в карточке номера, в поле rating ответа GET /numbers и в GET /limits; лучше всего на него работают сообщения, которых люди ждут и на которые отвечают. Таблица уровней — в разделе лимиты и индекс доверия.

Защита от рассылок

Защита от рассылок — автоматический тормоз wapi.kz, который срабатывает, когда отправка похожа на массовую холодную рассылку. Условия: один и тот же текст ушёл 25 и более новым людям за час или за час появилось 40 и более новых контактов. Тогда первые сообщения новым людям приостанавливаются на 24 часа: API отвечает cold_blocked или spam_detected (HTTP 429), а время окончания паузы видно в поле cold_blocked_until у номера. Отвечать тем, кто пишет вам сам, при этом можно — это защита номера от блокировки со стороны WhatsApp, а не наказание. Как работать с номером без лишнего риска — в гайде как избежать блокировки WhatsApp.

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

Официальный WhatsApp Business API (WhatsApp Business Platform, Cloud API) — продукт Meta для компаний, который подключают напрямую у Meta или через её партнёров (BSP). Нужны аккаунт Meta Business, обычно подтверждение компании и одобрение отображаемого имени; первое сообщение клиенту вне 24-часового окна — только по заранее одобренному шаблону, а с июля 2025 года Meta берёт плату за доставленные шаблонные сообщения. Плюсы — официальный статус, ниже риск блокировки при соблюдении правил, кнопки, шаблоны и масштаб; минусы — дольше подключение, модерация шаблонов и плата за сообщения. wapi.kz — другой путь: неофициальное подключение обычного номера как связанного устройства, без шаблонов, модерации и платы за сообщения, но с более высоким риском блокировки, если нарушать правила WhatsApp. Подробное сравнение — в гайде официальный или неофициальный WhatsApp API.

BSP — бизнес-партнёр Meta

BSP (Business Solution Provider) — компания-партнёр Meta, через которую бизнес подключает официальный WhatsApp Business API, если не хочет работать с Meta напрямую. Партнёр помогает пройти проверку, настроить шаблоны и даёт свой интерфейс или API, а за это часто берёт абонентскую плату или наценку сверх тарифов Meta за сообщения. Номер при этом, как правило, переводится в API; совместное использование с приложением WhatsApp Business Meta вводит постепенно и с ограничениями, так что это стоит уточнять у партнёра. wapi.kz не является BSP и не связан с Meta: мы подключаем ваш номер как связанное устройство. Чем способы отличаются по деньгам и срокам — на странице сравнения.

Шаблоны сообщений (templates)

Шаблон — заранее одобренный Meta текст сообщения с переменными (имя, номер заказа, дата), без которого в официальном WhatsApp Business API нельзя написать клиенту первым или вне 24-часового окна. Шаблоны делятся на категории — маркетинг, сервисные (utility) и аутентификация, и с июля 2025 года Meta берёт плату за каждый доставленный шаблон, а тариф зависит от страны получателя и категории. В wapi.kz шаблонов и модерации нет: текст вы собираете в своей программе и отправляете полем text (до 4096 символов). Обратная сторона — ответственность за то, чтобы писать только тем, кто ждёт сообщения, полностью на вас. Когда шаблон обязателен, объясняет термин 24-часовое окно.

24-часовое окно

24-часовое окно — правило официального WhatsApp Business API: после последнего сообщения клиента у компании есть 24 часа, чтобы отвечать ему обычным текстом. Ответы внутри окна бесплатны, а когда окно закрылось, написать можно только по одобренному шаблону, и такое сообщение платное. В wapi.kz окна нет: номер работает как обычный WhatsApp, и написать клиенту можно в любое время — в пределах лимитов и правил WhatsApp. Здравый смысл при этом тот же: сообщение, которого человек не ждёт, повышает риск жалоб и блокировки. Как окно и шаблоны влияют на итоговую стоимость — в гайде сколько стоит WhatsApp API.

Приложение WhatsApp Business

WhatsApp Business — бесплатное приложение Meta для малого бизнеса: тот же WhatsApp, но с профилем компании, каталогом, быстрыми ответами и метками. Его часто путают с WhatsApp Business API, но это разные вещи: приложение — для ручной переписки с телефона, API — для программ. К wapi.kz можно подключить и обычный WhatsApp, и WhatsApp Business: приложение продолжит работать как раньше, а ваша CRM или бот получат API и вебхуки к тому же номеру. Переносить номер или отказываться от приложения не нужно. Чем это отличается от официального пути — в термине официальный WhatsApp Business API.

Одноразовый код (OTP)

OTP (one-time password) — одноразовый код для входа, подтверждения телефона или операции, который обычно отправляют по SMS. Через wapi.kz такой код можно отправить в WhatsApp обычным сообщением через POST /messages/send — без платы за сообщение, оплачивается только номер. Учтите: код чаще всего получает человек, который ещё ни разу вам не писал, поэтому такое сообщение считается первым новому контакту и упирается в лимит — 150 в сутки на уровне «Хороший» и меньше в дни прогрева. Если регистраций больше, нужен запасной канал, например SMS. Схема и пример кода — в гайде OTP через WhatsApp.

Баланс

Баланс — лицевой счёт в wapi.kz, с которого оплачиваются номера: 9 900 ₸ в месяц за номер, списание по дням — 330 ₸ в сутки за каждый активный номер, в 00:05 по Алматы. Пополнить можно любой суммой от 1 000 ₸ до 1 000 000 ₸ через Kaspi или счётом на ТОО/ИП; оплаты картой пока нет, а за сообщения, запросы к API и вебхуки плата не берётся. GET /balance возвращает balance, daily_charge, days_left, active_numbers и paused_numbers, а когда денег остаётся на 3 дня или меньше, мы предупреждаем заранее. Удалили номер — со следующего дня списаний за него нет. Все условия оплаты — на странице цены.

Пауза номера

Пауза — состояние номера, когда на балансе закончились деньги: через сервис он не отправляет и не принимает сообщения, в GET /numbers у него status: "paused", а отправка возвращает number_paused (HTTP 402). Привязка WhatsApp при этом сохраняется, а на телефоне всё работает как обычно. После пополнения номер включается сам — заново сканировать QR-код не нужно. Чтобы не доводить до паузы, следите за days_left в ответе баланса или поручите это мониторингу.