Spun 為你提供一套 REST API,用的正是你的團隊在共用 WhatsApp 收件匣中回覆訊息的那個號碼:發送文字和媒體、讀取訊息、更新聯絡人和標籤,以及訂閱 Webhook。它直接對接你掃描 QR code 連接的號碼,因此不需要 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 限制,無論訊息經由哪條路徑發出。