消息API对接指南：REST、SMPP与Webhook

本指南面向需要把应用接入WhatsApp、短信或邮件消息服务商的后端开发者、解决方案架构师和CTO。文中说明应选用哪种接口，以及如何处理鉴权、幂等性、送达回执、重试、限流和测试，并附有请求与响应的示意结构。如果您想把会话同步到CRM，请参阅配套文章：用Webhook连接CRM。

该选REST、SMPP还是Webhook？

发送用REST，接收用Webhook；SMPP只用于您已经在运行SMPP的高并发短信场景。三者是互补而不是竞争关系：大多数集成都是出站用REST调用、回传用Webhook。

SMPP（Short Message Peer-to-Peer）会话以bind开始（transmitter、receiver或transceiver），用submit_sm发送消息，通过deliver_sm接收送达回执和上行短信，并用enquire_link保持连接。它效率高，但运维成本比HTTPS更重。

应该如何鉴权？

使用服务商提供的最强方式，不要把密钥写进代码，并且双向都要鉴权。

• **出站调用：**通过TLS，在Authorization头中发送API密钥或OAuth 2.0 bearer token。把它们存放在密钥管理器中，定期轮换，人员变动后也要轮换。
• **SMPP：**bind时使用system ID和密码，通常限制为白名单IP，如服务商支持，再叠加TLS。
• **入站Webhook：**对每个事件都验证签名。Meta使用您的应用密钥，对WhatsApp Cloud API的Webhook载荷计算HMAC-SHA256签名，放在X-Hub-Signature-256头中；其他服务商通常也有类似机制。请在解析之前，基于原始请求体计算签名。

每个环境使用独立的凭证，这样泄露的测试密钥就无法发送生产流量。

如何安全地发送一条消息？

通过队列发送，带上幂等键，并把响应理解为“已接受”而不是“已送达”。

发送请求示例

下面的结构是用于说明的伪JSON，并非某家服务商的真实API。

POST /v1/messages
Authorization: Bearer <token>
Idempotency-Key: 7f3c9a2e-order-55821-shipped

{
  "channel": "whatsapp",
  "to": "+9715XXXXXXXX",
  "template": {
    "name": "order_shipped",
    "language": "ar",
    "variables": ["Layla", "55821", "15 March"]
  },
  "client_reference": "order-55821",
  "callback_url": "https://api.example.com/webhooks/messaging"
}

响应示例

202 Accepted

{
  "message_id": "msg_01HZX...",
  "status": "accepted",
  "client_reference": "order-55821",
  "created_at": "2026-10-09T12:00:00Z"
}

请立即把message_id与您自己的业务引用一并保存。此后发生的一切都会异步返回。

为什么幂等性很重要？

因为网络超时往往发生在服务端已经处理请求之后。如果发送请求超时而您盲目重试，客户可能收到两条验证码或两条发货通知。幂等键能让服务端识别出这是一次重试，并返回第一次的结果。

行之有效的规则：

1. 幂等键应由业务事件生成（例如订单ID加事件类型），而不是每次尝试都生成随机值。
2. 同一次发送的每次重试都使用同一个键。
3. 键的保留时间要覆盖您的重试窗口。
4. 如果服务商不支持幂等键，请在发送之前自行去重。

IETF的Idempotency-Key头草案把这一模式标准化到了HTTP API中；各服务商的实现并不相同，请阅读其文档。

送达回执是如何工作的？

送达状态会以事件形式稍后返回：WhatsApp和大多数REST API通过Webhook，SMPP则通过deliver_sm回执。各状态的含义因渠道而异；我们的消息送达状态指南对此逐一说明。

状态Webhook示例

POST /webhooks/messaging
X-Signature: sha256=<hmac>

{
  "event_id": "evt_9c1...",
  "type": "message.status",
  "message_id": "msg_01HZX...",
  "client_reference": "order-55821",
  "status": "delivered",
  "timestamp": "2026-10-09T12:00:04Z",
  "error": null
}

请以防御性的方式处理状态事件：

• **去重：**按event_id，或按消息ID加状态去重。
• **不要回退：**事件乱序到达时，不要把消息从已读退回已送达。
• 快速返回2xx，再从队列中异步处理。
• **记录错误码：**对失败的消息，判断哪些错误可以重试。
• **允许缺失：**部分短信线路只返回有限的回执，已读状态则取决于渠道和用户设置。

如何处理重试和限流？

只重试有可能成功的请求，采用带抖动的指数退避，并遵从服务端发出的信号。

RFC 9110定义了Retry-After头，其值可以是秒数或日期。请在发送前加一层客户端限流器，使发送速率始终低于服务商公布的限制，而不是靠错误响应来摸索限制。WhatsApp在Meta侧还限制了您能触达的独立客户数量，详见消息限额与质量评级。

上线前应该如何测试？

不仅要测顺利路径，更要测失败路径。

上线前检查清单

1. 用真实长度的变量值发送每个模板，包括阿拉伯语文本。
2. 人为制造超时，确认重试不会造成重复发送。
3. 向无效号码发送，确认错误被处理且不会重试。
4. 把同一个Webhook重放两次并打乱顺序，确认最终只有一个状态。
5. 发送一个签名错误的Webhook，确认被拒绝。
6. 如果允许，对沙箱做压测以触发429。
7. 轮换一次API密钥，确认没有停机。
8. 检查日志里有消息ID，但没有完整的消息正文或验证码。
9. 在每个渠道上用内部号码做小规模生产试点。

沙箱很难完全还原运营商和Meta的行为，所以上线后的最初几周请持续监控。

实战示例：验证码与订单通知服务

“Qafilah Logistics”（虚构）是沙特阿拉伯的一家包裹物流公司，通过WhatsApp发送订单更新、以短信作为备用，并发送身份验证验证码。

• **架构：**订单事件进入队列；发送worker以shipment-id:event作为幂等键调用REST API。
• **备用：**如果WhatsApp对非WhatsApp用户返回失败状态，worker会用新的键shipment-id:event:sms发送短信。
• **验证码：**验证码有效期很短，因此过了有效期不再重试发送；由用户重新申请新验证码。参见OTP验证消息指南。
• **回执：**Webhook接收端校验签名、去重，并更新一个永不回退的状态表。
• **限流：**令牌桶限流器把每个渠道的发送速率限制在公布的上限之下。

常见的集成错误有哪些？

• 把“已接受”当作“已送达”。
• 每次重试都换一个新的幂等键。
• 在Webhook请求内部做繁重处理。
• 跳过Webhook的签名校验。
• 反复循环重试4xx校验错误。
• 把验证码和完整消息内容写入日志。
• 在测试环境使用生产凭证。

OmniChannels.ai 如何提供帮助

OmniChannels.ai由BroadNet Technologies提供技术支持，提供公开文档化的REST/JSON API，配有OpenAPI 3.1规范和TypeScript SDK，覆盖SMS、WhatsApp、RCS、Messenger、Instagram、Telegram、邮件和推送，其中包括支持一键、零点击和复制验证码OTP的WhatsApp身份验证模板。Webhook以统一规范的格式回传送达状态，SMPP 3.4通过TLS服务高并发短信，MCP服务器则可连接AI Agent。带筛选和CSV导出的送达报告，有助于您对账集成实际发出的消息。请从开发者文档和快速入门开始。