zh
免费预览

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

作者: WapFlow 团队 · 2026年11月16日 · 3 分钟阅读
代码编辑器中显示 WhatsApp OTP API 调用,手机上显示验证码消息

通过 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 是一款独立的云服务。

相关文章