← API 參考
帳號POST

建立帳號

建立一個渠道帳號。支援的 provider 包含 telegram、whatsapp、twitter、line、zalo 等；依帳號連接流程選擇對應 auth_mode。當所選 provider 與 auth_mode 組合需要電話號碼時（例如 WhatsApp 搭配 auth_mode=code），必須在此透過 provider_data.phone 寫入號碼 — 該號碼會持久化在帳號上，並在後續認證步驟自動帶入。

https://api.unifyport.ai/v1/accounts

請求標頭

X-Api-Key
string必填

工作區 API Key，工作區會由此標頭解析得到。

Content-Type
string必填

傳送 JSON 請求內容時請使用 application/json。

路徑參數

此介面沒有路徑參數。

請求內容

name
string必填

可讀的帳號名稱。

provider
string必填

渠道識別字，例如 telegram、whatsapp、line、zalo。

region
string必填

用於分配的渠道區域。請透過 列出渠道區域 選擇 allocatable: true 的區域。

auth_mode
string

認證流程：code、qrcode 或 session。

provider_data
object

渠道專屬設定，請勿在 log 中暴露其中的密鑰欄位。

metadata
object

平台側的環境標籤中繼資料。

回應內容

id
string

唯一的帳號識別字（acc_...）。請用於帳號層級的路由。

name
string

可讀的帳號名稱。

provider
string

渠道識別字，例如 telegram、whatsapp、line、twitter 或 zalo。

region
string

帳號所配置的渠道區域。

status
string

帳號生命週期狀態，例如 active。

runtime_status
string

標準化的執行階段狀態，為 unknown、starting、running、stopping、stopped、reconnecting、disconnected 或 error 其中之一。

auth_mode
string

帳號使用的認證流程：code、qrcode 或 session。

capabilities
string[]

帳號已啟用的能力，例如 send_message 與 receive_message。

provider_account_ref
string

渠道側的識別字，可附加用於將帳號與自有系統關聯對應。

回應

201
201 Created

請求成功，回應內容範例如上。

400
請求錯誤

請求內容、路徑或參數無效。

401
未授權

X-Api-Key 請求標頭缺少或無效。

409
衝突

目前操作與既有的渠道帳號或資源衝突。

500
伺服器錯誤

服務遇到了未預期的錯誤。

請求

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Telegram Production",
  "provider": "telegram",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["send_message", "receive_message"],
  "provider_data": {},
  "metadata": {
    "env": "production"
  },
  "provider_account_ref": "provider-side-identifier"
}'

回應

{
  "data": {
    "id": "acc_example",
    "name": "Telegram Production",
    "provider": "telegram",
    "region": "global",
    "status": "active",
    "runtime_status": "stopped",
    "auth_mode": "qrcode",
    "capabilities": ["send_message", "receive_message"],
    "provider_account_ref": "provider-side-identifier"
  }
}