Ключ на один номер: как дать доступ к WhatsApp API подрядчику

Зачем отдельный ключ

Принцип наименьших привилегий: каждый получает ровно тот доступ, который нужен для его работы. Ключ номера пригодится, когда:

• подрядчик подключает CRM, сайт или бота к одному из ваших номеров;
• внешний сервис — например, сценарий в n8n или Make — отправляет уведомления с одного номера;
• ИИ-агент отвечает клиентам на номере поддержки и не должен видеть переписку продаж;
• у каждой интеграции свой ключ — чтобы отключить одну, не трогая остальные.

Отдельной платы за ключи нет — вы платите только за номер, условия на странице цен.

Ключ аккаунта и ключ номера

Ни один ключ не открывает личный кабинет. Пополнение баланса, настройка вебхуков, удаление номера и выпуск ключей доступны только после входа в кабинет. Подробнее об авторизации — в документации.

Как выпустить ключ номера

Шаг 1. Откройте карточку номера

В кабинете перейдите в раздел «Номера» и выберите нужный номер. Если номеров несколько, о том, как их разделить, — в гайде несколько номеров на одном аккаунте.

Шаг 2. Подпишите, для кого ключ

В блоке «Ключ только для этого номера» введите название — например, «CRM подрядчика» или «Бот поддержки». Через полгода оно подскажет, какой ключ можно отозвать.

Шаг 3. Выпустите и сразу скопируйте ключ

Нажмите «Выпустить ключ». Ключ показывается один раз: мы храним только его хеш и показать заново не сможем. Потеряли — отзовите и выпустите новый.

Шаг 4. Передайте ключ безопасно

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

Шаг 5. Проверьте, что видит ключ

Ключ номера возвращает в списке только свой номер:

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

{
  "numbers": [
    { "id": 2, "label": "Поддержка", "phone": "77020000000", "status": "active", "wa_status": "WORKING", "connected": true, "rating": 68, "cold_blocked_until": null }
  ],
  "limit": 10
}

А баланс ему закрыт:

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

HTTP/1.1 403 Forbidden

{
  "error": "Этот ключ выпущен для одного номера: баланс и данные аккаунта доступны только ключу аккаунта (wapi.kz/app/api).",
  "code": "forbidden_for_number_key"
}

Отправка с ключом номера — обычный POST /messages/send, только без from: сообщение уйдёт со «своего» номера. Как отправлять — в гайде отправка сообщений через API.

Отзыв ключа

В списке ключей на карточке номера видны начало ключа, название, дата выпуска и когда ключ последний раз использовался. Кнопка «Отозвать» отключает ключ сразу: интеграция с ним перестаёт работать, остальные ключи — нет.

• Подрядчик закончил работу — отзовите его ключ, даже если он «больше не нужен».
• У номера уже 5 ключей — чтобы выпустить новый, отзовите ненужный.
• Ключ выпущен давно, но так и не использовался — скорее всего, его можно отозвать.
• Номер удалили — все его ключи перестают работать автоматически.

Перевыпуск ключа аккаунта

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

Хорошая практика: ключ аккаунта держите только у себя, а всем внешним интеграциям выдавайте ключи номеров. Тогда перевыпускать главный ключ придётся редко.

Как хранить ключи

• В переменных окружения или секретах хостинга, а не в коде. Код читает ключ из окружения, например process.env.WAPI_NUMBER_KEY.
• Не в git. Файл .env — в .gitignore. Даже приватный репозиторий со временем видят новые люди и сервисы.
• Не в браузере. Ключ в коде страницы сайта или мобильного приложения может прочитать любой посетитель. Запросы к API делайте со своего сервера.
• Не на скриншотах и не в записях экрана для инструкций.
• Свой ключ на каждую интеграцию — тогда при проблеме вы отключаете одну, а не всё сразу.

Ключ — в файл .env рядом с кодом, сам файл — в исключения git:

echo "WAPI_NUMBER_KEY=<ключ номера>" >> .env
echo ".env" >> .gitignore

Если ключ утёк

Ключ попал в публичный репозиторий, в переписку или на скриншот — действуйте сразу:

1. Отзовите ключ номера на карточке номера или перевыпустите ключ аккаунта в «API и MCP».
2. Выпустите новый ключ и обновите его в интеграции.
3. Посмотрите историю: GET /messages?from=…&direction=out покажет исходящие, а поле source — кто их отправил (api, mcp, phone). Ищите сообщения, которых вы не отправляли.
4. Проверьте на карточке номера, когда ключ использовался последний раз.
5. Если ключ был в git, удаления коммита мало — ключ остаётся в истории и копиях репозитория. Отзыв обязателен.

Ключ номера ограничивает ущерб: с ним нельзя увидеть баланс, другие номера и данные аккаунта. Поля истории описаны в документации.

Зарегистрируйтесь, подключите номер и выпустите первый ключ — это займёт около 5 минут.