快速上手

快速開始：喺 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
配對手機
用空 body 啟動流程——已保存嘅手機號會被複用，回應嘅 auth_payload 入面帶住 8 位 verify_code。喺手機打開 WhatsApp → 已連結嘅裝置 → 用電話號碼連結，大概 3 分鐘內打入個碼。成功之後 account.auth.succeeded 會落你個 webhook，跟住係 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 投遞同簽章驗證