Spun 为你提供一套 REST API,用的正是你的团队在共享 WhatsApp 收件箱中回复消息的那个号码:发送文字和媒体、读取消息、更新联系人和标签,以及订阅 Webhook。它直接对接你扫描二维码绑定的号码,因此不需要 Business API,也没有按条收取的消息费用。
人们对 WhatsApp API 的需求,大多归结为四件事:发送消息、查询信息、修改记录,以及在某件事发生时收到通知。Spun 通过普通的 HTTP 提供全部四项能力,作用于你的团队在收件箱中回复消息的同一个号码;认证使用你自己创建的密钥,其权限范围可以精确限定在这项集成所需的内容上。
本页是实用版说明:有哪些端点,认证和权限范围如何运作,调用时你的 WhatsApp 线路恰好离线会发生什么,以及机器可读的接口契约在哪里。
密钥、权限范围,以及泄露时的波及范围
认证方式是 Bearer 令牌。你在应用中创建密钥,它只向你显示一次,之后每个请求都在 Authorization 请求头中携带它。Spun 只存储密钥的哈希值,所以丢失的密钥无法找回,只能替换。
值得花一分钟了解的是权限范围。密钥并不只是简单的“账号访问权限”:它带有一份权限范围列表,每个端点都会检查自己所需的特定权限范围。只有 read_contacts 的密钥无法发送消息。只有 send_message 的密钥无法遍历你的联系人列表。除了权限范围,密钥还可以设置到期日期和 IP 白名单,这样,发给固定地址服务器的密钥一旦从其他任何地方使用,就会立即失效。
- send_message 涵盖文字和媒体发送,以及查询已排队的发送。
- read_contacts、read_messages 和 read_labels 属于读取类,可以分别授予。
- manage_contacts 和 manage_labels 涵盖创建、更新和添加标签。
- check_phone 用于判断一个号码能否通过 WhatsApp 联系到。
- manage_webhooks 用于创建、列出和删除 Webhook 订阅。
请求
curl -X POST https://api.spun.com/api/integrations/send-message \
-H "Authorization: Bearer wap_0f3c9a1d7b524e86a1c05d9e2f7b48ac" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550142",
"text": "Your appointment is confirmed for Thursday at 10:00.",
"idempotency_key": "booking-8871"
}'响应
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"message_id": "yq0Zt9C1sK2mfE7x"
}为 Spun MCP 服务器创建的密钥,即使有效,也会被这个 API 有意拒绝。这两套接口的审批机制不同,为其中一方签发的密钥不会被悄悄用在另一方。
WhatsApp API 端点实际涵盖哪些内容
这套接口刻意保持精简和稳定,而不是对产品功能的完整镜像。它的目的,是让外部系统能做外部系统真正需要做的事。
- 发送:一条文字消息,或以 URL 或 base64 形式提供的媒体,可附带说明文字。
- 联系人:创建联系人、更新联系人,以及使用游标分页列出联系人。
- 标签:列出工作区中的标签,为对话添加标签,移除标签。
- 消息:使用游标分页列出消息,用于同步到数据仓库或 CRM。
- 号码检查:在围绕某个号码建立名单之前,先确认它在 WhatsApp 上。
- 队列:查询因线路离线而进入队列的发送。
- Webhook:创建、列出和删除订阅。
机器可读的接口契约发布在 /api/integrations/openapi.json,无需密钥即可读取,因此 n8n 节点作者、Zapier 应用开发者或你自己的代码生成器,都能在任何人向他们发放凭据之前获取这份规范。
WhatsApp 线路离线时会发生什么
这部分常常出乎人们意料,所以值得说清楚。Spun 通过在线的 WhatsApp 会话发送消息,而在线会话可能恰好在你的代码发起调用的那一秒断开。API 不会假装没有这回事,并且有意对文字和媒体采取不同的处理方式。
向离线线路发送文字时,返回的是 202 而不是错误,并附带一个队列 ID。消息会被保留,在线路重新连接后送达,你可以轮询队列端点了解它的结果。向离线线路发送媒体则会返回冲突,并且不发送任何内容。这种不对称是刻意的:队列以文字形式发出消息,所以排队的图片到达时只剩说明文字,没有图片。明确报错是更好的结果,由你的重试逻辑来决定下一步。
速率限制为每个密钥每分钟 60 个请求,每个响应都带有标准的速率限制响应头,客户端可以依据响应头主动降速,而不必等到收到意料之外的 429。
Webhook:等待通知,而不是轮询
定时轮询消息端点并不适合对话这种场景,所以 API 可以改为主动推送。你注册一个 URL 和你关心的事件,事件发生时,Spun 会向该地址发送一个 JSON 请求体。
每次投递都会在请求头中携带事件名称和唯一的投递 ID;如果订阅设置了签名密钥,还会携带对完整请求体计算的 HMAC-SHA256 签名。在信任载荷之前,先验证签名:它是把你的端点与任何得知该 URL 的人区分开来的唯一屏障。签名密钥只在你创建订阅时返回一次,之后不会再返回。
- 消息事件,包括收到和发出的消息。
- 联系人已创建、已更新和已删除。
- 标签已分配。
- 对话流已完成、排队发送已处理、线索已认定合格。
- 对话已关闭、通话已结束,以及销售管道阶段已变更。
相关:将 Spun 连接到 Zapier 和 Make · 将 Spun 连接到 n8n · 连接服务台:Zendesk、Zoho Desk、Freshdesk、HubSpot Service Hub、Jira
限制与坦诚说明
- 这不是 WhatsApp Business API。这是 Spun 自己的 API,对接你已绑定的号码,所以没有需要审批的消息模板,也没有按条收取的消息费用,但同样也没有 Meta 的官方保障。
- 每个密钥每分钟六十个请求。批量任务应交给群发活动,它们会自行合理控制节奏,而不是放进密集的 API 循环里。
- 上面的端点列表就是目前的全部接口。不在列表上的功能均未开放,也不应依赖任何未写入文档的端点。
- 密钥有权限范围,但不区分用户。请把它当作工作区凭据,有访问权限的人离开时就轮换它。
- 向从未同意接收消息的人发送消息,会导致号码被 WhatsApp 限制,无论消息经由哪条路径发出。