快速入門

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

六個步驟，從空白工作區到發出一則 WhatsApp 訊息、收到你的第一個入站 webhook 事件。每一步都附上完整端點參考的連結。

開始使用

1
備妥你的 API Key
UnifyPort 目前僅向特定客戶開放——請聯絡團隊取得工作區存取權。下面每個請求都以 X-Api-Key 標頭認證。
curl https://api.unifyport.ai/v1/workspace \ -H "X-Api-Key: <YOUR_API_KEY>"
取得目前工作區

註冊 webhook 端點

請先做這一步：授權進度與每一則入站訊息都只會以 webhook 事件送達，漏掉的事件不會重放。以 ["*"] 訂閱即可收到全部標準事件目錄。

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",
  "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 帳號

一個帳號就是一台虛擬裝置。請使用上一步確認為 allocatable 的區域。WhatsApp 手機號配對請用 auth_mode=code，並把 provider_data.phone 設為 E.164 號碼（僅數字）——號碼會儲存在帳號上，下一步自動重用。

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": "global",
  "status": "active",
  "auth_mode": "code",
  "provider_data": { "phone": "8613800138000" }
}'

建立帳號

5
配對手機
以空的請求內容啟動流程——已儲存的手機號會被重用，回應的 auth_payload 內帶有 8 個字元的 verify_code。在手機上開啟 WhatsApp → 已連結的裝置 → 改用電話號碼連結，並於約 3 分鐘內輸入。成功後你的 webhook 會先收到 account.auth.succeeded、再收到 account.started；執行環境自動啟動，無需呼叫 /runtime/start。
curl -X POST https://api.unifyport.ai/v1/accounts/<ACCOUNT_ID>/auth/start \ -H "X-Api-Key: <YOUR_API_KEY>"
開始驗證碼認證

發送你的第一則訊息

發送標準化 JSON——UnifyPort 會替你轉換成渠道格式。WhatsApp 的收件人 id 為 <E.164>@s.whatsapp.net。

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": "8613912345678@s.whatsapp.net", "type": "user" },
  "message": { "type": "text", "text": "Hello from UnifyPort" }
}'

傳送文字訊息

7
接收你的第一個事件
用另一支手機回覆：幾秒內 message.received 事件就會到達你的 webhook 端點。接下來，可以驗證投遞簽章，並依標準事件目錄進行處理。
Webhook 投遞與簽章驗證