← 所有文章
更新日誌

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。喺同一個工作時段裡面,你就會見到標準化嘅入站事件打到後端。之後每多接一個渠道,都係同樣嘅流程——而唔係又一個整合專案。