Интеграция API WhatsApp OTP: примеры на PHP, Node.js и Python

Отправка кода подтверждения через WhatsApp сводится к двум вызовам API WapFlow OTP: один отправляет код, другой проверяет то, что ввёл пользователь. В этом руководстве мы собрали принцип работы API, примеры на cURL, PHP, Node.js и Python, обработку ошибок и моменты безопасности, на которые стоит обратить внимание. Примеры следуют формату из официальной документации API, с небольшими дополнениями для удобства чтения. Если вы ещё не знаете, что представляет собой продукт, прежде чем начать писать код, сначала прочитайте статью «Что такое WhatsApp OTP».
Основы
- Базовый URL:
https://wapflow.net/api/otp/v1 - Аутентификация: заголовок
Authorization: Bearer <key>в каждом запросе. Боевые ключи начинаются сwfo_live_, тестовые — сwfo_test_. - Формат ответа:
{ "success": true, ... }при успехе,{ "success": false, "error": { "code": "...", "message": "..." } }при ошибке. - Номер телефона: с кодом страны, например
905321234567. API оставляет только цифры (знаки +, пробелы и дефисы удаляются) и ожидает от 10 до 15 цифр. Одиннадцатизначные номера, начинающиеся с 0, считаются турецкими, и к ним спереди добавляется 90.
Ключ API создаётся на странице WapFlow OTP в панели WapFlow. Ключ показывается только один раз, при создании; храните его в переменной окружения на вашем сервере.
Четыре конечные точки
| Конечная точка | Назначение |
|---|---|
| POST /send | Генерирует код и отправляет его через WhatsApp. Параметр phone обязателен; необязательные — code_length (4–8), ttl (60–900 с), lang, app_name. |
| POST /verify | Проверяет код, введённый пользователем. Параметры phone и code обязательны; если передан request_id, проверяется именно этот запрос. |
| GET /status/:request_id | Возвращает статус запроса: queued, sent, delivered, read, failed, verified, expired. |
| GET /me | Показывает, действителен ли ключ, тариф, количество подключённых аккаунтов и использование квоты за этот месяц. |
После 5 неверных попыток запрос блокируется, а подтверждённый код нельзя использовать повторно. Если не передать request_id, проверяется последний действующий код, отправленный на этот номер с этим ключом. Так как может существовать несколько сессий, рекомендуем сохранять request_id и передавать его при проверке.
Первая попытка с cURL
# 1) send the code
curl -X POST https://wapflow.net/api/otp/v1/send \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"phone":"905321234567","app_name":"Acme"}'
# 2) verify the code
curl -X POST https://wapflow.net/api/otp/v1/verify \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'
Первую попытку сделайте с ключом wfo_test_: сообщение WhatsApp не отправляется, квота не расходуется, а код возвращается в поле test_code ответа.
Пример на PHP
<?php
function wapflow_otp(string $path, array $body): array {
$ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$res = json_decode(curl_exec($ch), true) ?: [];
curl_close($ch);
return $res;
}
$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }
Пример на Node.js
В примере используется встроенный fetch (Node.js 18 или новее), и он должен выполняться как ES-модуль.
const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
const res = await fetch(BASE + path, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }
Пример на Python
import os
import requests
BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}
def otp(path, body):
return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()
sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
pass # signed in
Обработка ошибок
Отправку и проверку обрабатывайте отдельно. Если отправка возвращает success: false, действуйте в зависимости от кода ошибки:
| HTTP / код | Что делать |
|---|---|
| 401 invalid_key | Проверьте ключ; возможно, он отозван или набран с ошибкой. |
| 402 no_subscription, subscription_expired | Оформите или продлите подписку. |
| 422 invalid_phone | Попросите пользователя ввести номер заново с кодом страны. |
| 429 rate_limited | Повторите запрос через количество секунд из поля retry_after в ответе. |
| 429 quota_exceeded | Месячная квота исчерпана; повысьте тариф или дождитесь следующего периода. |
| 429 daily_limit_reached | Подключённые аккаунты достигли дневного лимита; повторите запрос через retry_after (со следующего дня в 00:00 по турецкому времени). Квота не расходуется. |
| 503 no_account_connected, send_failed | Убедитесь, что есть подключённый и включённый аккаунт WhatsApp; повторите попытку немного позже. |
При проверке ответ HTTP 200 всё равно может содержать valid со значением false. Причину показывает поле reason: invalid_code, expired, too_many_attempts, already_verified или not_found. При неверном коде поле attempts_left показывает, сколько попыток осталось; передача этого значения пользователю улучшает его опыт.
Лимиты запросов и пользовательский опыт
- На один номер можно получить 1 код за 60 секунд, 5 в час и 10 в день. Добавьте 60-секундный обратный отсчёт на кнопку «Отправить повторно».
- Лимиты: 60 отправок в минуту на один ключ API, 120 запросов в минуту на один IP-адрес и, для проверки, 10 попыток в минуту на один номер.
- На отправку влияют дневной лимит и прогрев новых номеров; подробности — в нашей статье о снижении риска блокировки.
Чек-лист безопасности
- Никогда не используйте ключ API в браузере, мобильном приложении или любом открытом коде; выполняйте вызовы с вашего сервера.
- Всегда проверяйте код на сервере через
/verify; не доверяйте флагу «подтверждено», пришедшему из браузера. - Храните ключ в переменной окружения, а не в репозитории.
- Ставьте собственное ограничение частоты и, при необходимости, CAPTCHA перед отправкой кода: злоупотребления могут съесть вашу квоту.
- Для критичных действий держите резервный канал (SMS или e-mail). WapFlow OTP — не официальный WhatsApp Business API, и доставка не гарантируется.
Если вы используете WordPress или WooCommerce, можно обойтись без программирования и воспользоваться плагином. Тарифы смотрите на странице цен, обзор продукта — на странице WapFlow OTP.
Часто задаваемые вопросы
Что меняется при переходе в боевой режим?
Только ключ. Тестовый ключ начинается с wfo_test_, а правила отправки и лимитов у него такие же, как у боевого ключа; действующая подписка всё равно нужна.
Обязательно ли передавать request_id?
Нет, но рекомендуется. Если его не передать, проверяется последний действующий код, отправленный на этот номер.
Можно ли изменить текст сообщения?
Да. В панели можно задать название приложения, шаблон сообщения, длину кода, срок действия и язык. В шаблоне используются переменные {code}, {app} и {minutes}. Для каждого запроса их можно переопределить параметрами app_name, code_length, ttl и lang.
Как узнать, что сообщение доставлено?
Запросите статус через /status/:request_id; вы можете увидеть sent, delivered и read. Информация о доставке зависит от WhatsApp и не гарантируется.
Доступен ли этот API в приложении для Windows?
Нет. WapFlow OTP — отдельный облачный сервис.


