← 所有文章
更新日誌

UnifyPort v1 API 正式可用於生產:首個穩定版本有哪些內容 — UnifyPort

UnifyPort v1 API 現已正式可用於生產。這是首個穩定版本:一個傳送端點、一套標準化的 Webhook 事件層,以及涵蓋全部六大渠道——WhatsApp、Telegram、LINE、TikTok、Zalo、X——的帳號接入流程,全部收斂在同一個 API 之下。

這篇文章就是本次發布的更新日誌。如果你一直在等一個可以放心建構、不必擔心底層隨時出現破壞性變更的版本,那就是它。以下按端點逐一說明本次上線的內容,包含真實的事件名稱、認證流程與可靠性行為。

一個傳送 API,貫通六大渠道

v1 的核心是一個端點。POST /v1/messages 透過你選定的 provider 帳號傳送一則標準化的文字訊息。你不需要學六套 SDK 或六種酬載格式——只學一套。

平台特有的能力並未消失,而是收進了結構化的 provider_data 欄位。需要回覆某則特定訊息,或設定 Telegram 的 parse mode?這些都放在 provider_data 裡(例如 reply_to、parse_mode),頂層請求的結構保持不變。常見情境保持簡單,平台特定情境依然可行。

六大渠道為 WhatsApp、Telegram、LINE、TikTok、Zalo、X。在 API 裡,provider 帳號透過 telegram、whatsapp、twitter、line、zalo 等名稱建立。

11 個標準 Webhook 事件

v1 的另一半是標準事件層。每一則來自 provider 的訊息、每一次投遞狀態變更、每一個帳號生命週期事件,都會被轉換成同一套穩定的 JSON 結構。本次發布共有 11 個標準事件,你的後端透過同一個處理器消費它們全部。

最常用的兩個:

  • message.received —— 已連接帳號收到一則入站訊息
  • message.status.updated —— 你發出的某則訊息投遞狀態發生變化

帳號生命週期事件讓連線狀態變得可觀測,而不再是一團黑盒:

  • account.auth.required —— 帳號需要一次登入操作(掃碼或驗證碼)
  • account.auth.succeeded —— 登入完成;provider_account_ref 此時已填入,事件還攜帶標準資料欄位(display_name、picture_url、region、status_message)
  • account.started —— 帳號執行階段已上線
  • account.status.updated —— 帳號狀態發生變化

無論來自六大渠道中的哪一個,message.received 事件長得都一樣:

{
  "event": "message.received",
  "account_id": "acct_8Q2vK",
  "provider": "whatsapp",
  "from": "+6591234567",
  "text": "你好,我的訂單好了嗎?",
  "timestamp": 1749254400,
  "message_id": "wamid.HBgLNTU..."
}

把 whatsapp 換成 line 或 zalo,你的路由邏輯一行都不用改。這正是標準層存在的意義。

帳號接入:掃碼與驗證碼兩種流程

在 v1 裡,帳號接入是一條獨立的流程,其設計理念是:認證狀態是你的 Webhook 可以「觀察」的東西,而不是需要你時刻盯著的東西。

你透過向帳號端點 POST 建立帳號,並選擇與接入方式相符的 auth_mode:

{
  "provider": "whatsapp",
  "auth_mode": "code",
  "provider_data": { "phone": "+6591234567" }
}

對於驗證碼流程,E.164 格式的手機號碼透過 provider_data.phone 提供。它會被持久化在帳號上,並在後續認證動作中自動重放,因此你無需每一步都重新提交。建立重複的 provider 身分會回傳乾淨的 409 duplicate_provider_account,而不是悄悄產生第二個帳號。

對於掃碼流程,憑證透過你的 Webhook 非同步送達:

  • WhatsApp —— 呼叫 /auth/qr/start 開啟裝置工作階段。QR token 會作為 account.auth.required 事件落到你的 Webhook(auth_payload.qr_code 是你 UI 要渲染成 QR 碼的原始 token),同時也透過 /auth/qr/check 提供同步輪詢。掃碼後,account.auth.succeeded 到達並帶上 provider_account_ref,隨後是 account.started。
  • LINE —— QR 碼 URL 與 PIN 非同步送達。監聽 account.auth.required,或輪詢 /auth/session 讀取 auth_payload.url(QR 碼圖片)和 auth_payload.pin。

帳號設定好時,Webhook URL 會被自動注入——認證狀態變更與登入事件,與你的入站訊息走同一個端點。一個 Webhook,所有事件。

account.auth.succeeded 一旦到達,POST /v1/accounts/{account_id}/runtime/start 即可讓帳號上線(若執行階段已啟動則為空操作)。

Webhook 控制面

v1 裡的 Webhook 端點是一等公民、可設定的物件,而不是埋在設定裡的單一 URL 欄位。

建立 Webhook 接收器時,你精確選擇它接收哪些事件。subscribed_events 接受標準事件名(如 message.received、account.status.updated),或用 ["*"] 訂閱全部。未知的事件名在寫入時即被拒絕,而不是稍後悄悄失敗。

簽章是內建的。提供 signing_secret,每次投遞都會用 HMAC-SHA256 簽章,你的端點即可驗證真實性。留空則明確停用簽章——這是一個明確的選擇,而非意外。

重試行為由你設定。retry_policy.max_attempts 是非負整數;0 表示完全停用重試,非整數值會被拒絕。重投由平台負責,你的端點只需作出回應。

把波動留在平台層的可靠性

一個生產版本需要生產級的預設值,v1 自帶了它們。入站投遞經過一條帶限流、重試、冪等與故障隔離的佇列,因此 provider 端的波動被留在平台層內部,不會擴散到你的應用。

帳號執行階段狀態也被標準化。runtime_status 不再是各家 provider 自己的術語,而是八個平台標準值之一——unknown、starting、running、stopping、stopped、reconnecting、disconnected、error——provider 特有的標籤在你看到之前就已對映進這套取值。你只寫一個狀態機,而不是六個。

對於需要依地域路由的帳號,選用性的 proxy_config 物件會隨帳號持久化並自動套用。

這次發布意味著什麼

v1 達到生產可用,是一種承諾,而不只是一個版本號。傳送端點、11 個標準事件、認證流程、Webhook 控制面,就是你可以在其上建構產品的穩定面。UnifyPort 的初衷一直是:讓團隊不必把同一套整合做六遍;v1 就是這套面「停止移動」的那個版本。

如果你讀過我們關於「避開官方 API 摩擦接收訊息」的其他文章——不走官方 API 接收 WhatsApp 入站、無需官方帳號接收 LINE 訊息,或 WhatsApp 與 Telegram 成本比較——這就是那些路徑所執行的 API。

上手步驟:建立一個 API key,用與渠道相符的 auth_mode 連接第一個帳號,註冊一個帶 signing_secret 的 Webhook 端點,訂閱 message.received。在同一個工作時段內,你就能看到標準化的入站事件打到後端。從此每多接一個渠道,都是同樣的流程——而不是又一個整合專案。