WhatsApp OTP API 集成:PHP、Node.js 与 Python 示例

通过 WhatsApp 发送验证码,只需用 WapFlow OTP API 完成两次调用:一次发送验证码,另一次验证用户输入的内容。在本指南中,我们将介绍该 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 开头的 11 位号码会被视为土耳其号码,并在前面加上 90。
您可以在 WapFlow 面板的 WapFlow OTP 页面中创建 API 密钥。密钥仅在创建时显示一次;请将其保存在服务器的环境变量中。
四个端点
| 端点 | 用途 |
|---|---|
| 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 会显示剩余尝试次数;将其告知用户,可以带来更好的体验。
频率限制与用户体验
- 同一号码每 60 秒最多接收 1 个验证码,每小时 5 个,每天 10 个。请在“重新发送”按钮上设置 60 秒倒计时。
- 每个 API 密钥每分钟可发送 60 条,每个 IP 地址每分钟可发送 120 个请求;验证时,每个号码每分钟允许 10 次尝试。
- 每日限制以及新号码的养号会影响发送;详情请参阅我们关于降低封号风险的文章。
安全检查清单
- 切勿在浏览器、移动应用或任何公开代码中使用 API 密钥;请从您的服务器发起调用。
- 始终通过
/verify在服务器端检查验证码;不要信任来自浏览器的“已验证”标记。 - 将密钥保存在环境变量中,不要放入代码仓库。
- 发送验证码前,请设置您自己的频率限制,并在需要时加入验证码(CAPTCHA);滥用可能会耗尽您的配额。
- 对于关键操作,请保留备用渠道(短信或电子邮件)。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,无法保证。
Windows 应用中也能使用此 API 吗?
不能。WapFlow OTP 是一款独立的云服务。


