快速入門

快速上手：在 WhatsApp 發出第一則訊息

連接一個 WhatsApp 訊息帳號，傳送文字訊息，並透過 Webhook 接收回覆。本指南使用電話號碼配對。

開始使用

1
備妥你的 API Key
準備工作區 API Key、WhatsApp 帳號及可接收公網 HTTPS 請求的 Webhook。API Key 與簽章密鑰保存在伺服器端。先用下方請求檢查 API Key。
curl "https://api.unifyport.ai/v1/workspace" \ -H "X-Api-Key: <YOUR_API_KEY>"
取得目前工作區

註冊 webhook 端點

請先做這一步：授權進度與即時入站訊息透過 webhook 送達，漏掉的投遞不保證重放。以 ["*"] 可訂閱全部公開標準事件；WhatsApp HistorySync 僅提供有限的近期連續性，不是持久歷史歸檔。

curl -X POST "https://api.unifyport.ai/v1/webhook-endpoints" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

建立 Webhook 端點

3
查詢可用區域
帳號會綁定到一個區域，且並非每個渠道都覆蓋所有區域。請先列出該渠道的區域，挑一個 allocatable: true 的——在無法分配的區域建立帳號會以 409 no_allocatable_server 失敗。
curl "https://api.unifyport.ai/v1/providers/whatsapp/regions" \ -H "X-Api-Key: <YOUR_API_KEY>"
列出渠道區域

建立 WhatsApp 帳號

在選定的可分配區域建立訊息帳號。WhatsApp 號碼配對使用 auth_mode=code，並在 provider_data.phone 填寫僅含數字的完整國際號碼。將回傳的 data.id 儲存為 account_id，供後續步驟使用。

curl -X POST "https://api.unifyport.ai/v1/accounts" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "WhatsApp Support",
  "provider": "whatsapp",
  "region": "<REGION>",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8600000000000" }
}'

建立帳號

5
配對手機
使用帳號已儲存的電話號碼，向 POST /auth/start 傳送 {}。將 data.verify_code 顯示給使用者在手機 WhatsApp 輸入，不必提交至 /auth/code。傳送訊息前繼續檢查授權狀態與執行狀態。
curl -X POST "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start" \ -H "X-Api-Key: <YOUR_API_KEY>"
開始驗證碼認證
6
確認帳號可以傳送
以相同 account_id 查詢 /auth 和帳號資訊，確認授權狀態為 authorized、runtime_status 為 running。需要授權操作時繼續流程；已授權但離線時檢查或重新整理執行狀態。
curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth" \ -H "X-Api-Key: <YOUR_API_KEY>" curl -X GET "https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>" \ -H "X-Api-Key: <YOUR_API_KEY>"
取得認證狀態

發送你的第一則訊息

使用建立時儲存的 account_id。本 WhatsApp 範例以完整國際號碼加 @s.whatsapp.net 作為收件方；回覆時沿用事件的 data.conversation.id。其他渠道不可直接套用此格式。

curl -X POST "https://api.unifyport.ai/v1/messages" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "<ACCOUNT_ID>",
  "to": { "id": "8600000000000@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'

傳送文字訊息

8
接收你的第一個事件
從測試收件方回覆。接收端驗證簽章、儲存事件並確認投遞。一般事件依事件 ID 去重並容許亂序；conversation.history 依 provider + account_id + conversation.id + messages[].id 合併訊息，不依事件 ID 丟棄整批資料。未收到時檢查訂閱、接收網址可達性與投遞回應。
Webhook 投遞與簽章驗證