功能

在你自己的 WhatsApp 號碼上使用 WhatsApp API

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"
}
發送一條訊息。冪等鍵是可選的;用相同的鍵重複同一個呼叫,你會拿回原始訊息的 ID,而不會再發送第二次。

為 Spun MCP 伺服器建立的密鑰,即使有效,也會被這個 API 有意拒絕。這兩套介面的審批機制不同,為其中一方簽發的密鑰不會被悄悄用在另一方。

相關:連接 AI 助理,而不是自己寫程式碼

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 限制,無論訊息經由哪條路徑發出。

相關:Spun 如何連接 WhatsApp

常見問題

使用它需要 WhatsApp Business API 嗎?

不需要。這是 Spun 自己的 REST API,對接你自己的 WhatsApp 號碼,號碼透過掃描 QR code 連接。不需要 Meta 應用程式,沒有範本審批隊列,也沒有按訊息收取的費用。

如何獲取 API 密鑰?

帳戶管理員在應用程式中建立密鑰,選擇它的權限範圍,並可選擇設定到期日期和 IP 白名單。原始密鑰只在建立時顯示一次;之後 Spun 只儲存它的哈希值。

有 OpenAPI 規範嗎?

有,發佈在 /api/integrations/openapi.json,無需密鑰即可讀取,這樣工具在憑據發放之前就能生成客戶端。

同一個請求發送兩次會怎樣?

傳入冪等鍵。使用相同鍵的重複呼叫會返回原始訊息 ID,並把回應標記為冪等,而不會發送第二條訊息。沒有冪等鍵時,呼叫兩次就是兩條訊息。

如何驗證 Webhook 確實來自 Spun?

為訂閱設定簽名密鑰,並檢查簽名請求頭:它是對原始請求體計算的 HMAC-SHA256,格式為 sha256 後接十六進位摘要。在解析之前,用你收到的原始位元組自行計算一遍,再與之比對。

在客戶已經在聯絡的號碼上建立整合

有權限範圍的密鑰、精簡穩定的介面、主動推送而無需輪詢的 Webhook,而且不按訊息計費。

免費開始:7 日體驗全部功能

查看 Spun 全部功能