快速上手

快速開始：喺 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>"
攞目前工作區
2
註冊一個 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 投遞同簽章驗證