更新日誌 June 28, 2026

UnifyPort API 更新：會話標籤、聯絡人訊息同請求追蹤 — UnifyPort

v1 穩定版發佈三週後，UnifyPort API 迎嚟首批功能更新：用嚟組織 WhatsApp 對話嘅會話標籤、聯絡人名片訊息類型、貫穿每個調用嘅請求追蹤機制，同埋一系列令 webhook 事件參考文檔更加實用嘅開發者體驗改進。

以下係今次更新嘅完整內容，包含真實嘅端點同欄位名稱。

會話標籤 — 4 個新端點

而家可以建立、列出、更新同刪除會話標籤，並批量為會話加標籤或移除標籤。呢個同 WhatsApp 原生提供嘅標籤系統一致——UnifyPort 透過 Conversations 分類下嘅四個端點將佢統一呈現。

列出標籤

GET /v1/accounts/{account_id}/conversations/labels?limit=50&cursor=

回傳分頁嘅標籤清單，每個標籤包含 id 同 name：

{
  "data": {
    "items": [
      { "id": "label_example", "name": "VIP" }
    ],
    "next_cursor": "",
    "has_more": false
  }
}

建立或更新標籤

POST /v1/accounts/{account_id}/conversations/labels/upsert

label_id 為空時建立，傳入已有 label_id 時重新命名：

{
  "label_id": "",
  "name": "VIP"
}

刪除標籤

POST /v1/accounts/{account_id}/conversations/labels/delete

{
  "label_id": "label_example"
}

為會話加標籤或移除標籤

POST /v1/accounts/{account_id}/conversations/labels

action 為 add 或 remove；conversation_ids 至少包含一個 ID：

{
  "label_id": "label_example",
  "action": "add",
  "conversation_ids": ["peer_example"]
}

四個端點目前淨支援 WhatsApp。其他頻道回傳 501 unsupported_by_provider。對應嘅錯誤碼——list_conversation_labels_failed、upsert_label_failed、delete_label_failed、set_label_members_failed——已喺錯誤參考文檔中列出。

聯絡人（vCard）訊息類型

POST /v1/messages 而家接受 message.type: "contact"，攜帶結構化嘅 contacts 陣列。UnifyPort 自動生成 vCard——你只需發送結構化 JSON，對方收到嘅係標準聯絡人名片。

{
  "account_id": "acc_example",
  "to": {
    "id": "user_example",
    "type": "user"
  },
  "message": {
    "type": "contact",
    "contacts": [
      {
        "name": "Jane Doe",
        "phones": [{ "number": "+8613800000000", "type": "CELL" }],
        "emails": [{ "address": "jane@example.com" }],
        "organization": "ACME",
        "title": "PM"
      }
    ]
  }
}

每張名片必須包含 name。phones[].number、emails[].address、organization 同 title 係選填欄位。可以喺陣列入面發送單張或多張名片——WhatsApp 將單張對應為 contact 類型，多張對應為 contact_array。

空嘅 contacts 陣列或缺少 name 嘅名片回傳 400 invalid_request。非 WhatsApp 頻道喺支援上線前回傳 400 unsupported_message_type。

請求追蹤 — request_id 同 X-Request-Id

每個 API 回應——無論成功定錯誤——而家都攜帶頂層 request_id 欄位，並以 X-Request-Id 回應標頭回傳相同嘅值。喺報告問題或除錯失敗調用時，引用呢個 ID 就得。

對於客戶端側嘅請求關聯，發送自訂嘅 X-Request-Id 請求標頭，佢會喺回應中以 client_request_id 回傳。咁你就唔使維護額外嘅對應層即可將出站 API 調用同內部請求 ID 關聯起嚟。

真實 webhook 載荷示例

API 參考文檔而家包含從實際設備 webhook 解析器（Telegram 同 WhatsApp）提取嘅真實載荷結構。

message.received 按內容類型展示載荷——文字、圖片、語音、文件同位置——令你可以睇到每種變體嘅精確欄位結構，而唔係猜測一個空嘅 data: {} 佔位符。

group.updated 按變更類型展示載荷：

重新命名 — changes[].kind: "renamed"，攜帶新嘅群組 name
成員增減 — changes[].kind: "member_added" 或 "member_removed"，攜帶參與者 ID 嘅 members[] 陣列
管理員提升/降級 — changes[].kind: "promoted" 或 "demoted"，攜帶 members[]

單個 group.updated 事件可以攜帶多個變更——例如，一次快照中同時包含重新命名同成員新增。

三個新開發者工具

工具頁面新增三個瀏覽器端工具，全部喺客戶端執行：

HMAC 簽章生成器 — 喺瀏覽器中生成同驗證 HMAC-SHA1/SHA256/SHA512 簽章；除錯 webhook signing_secret 驗證時好有用
Unix 時間戳轉換器 — Unix 時間戳同人類可讀日期互轉，自動識別秒級同毫秒級
JSON 格式化工具 — 格式化、壓縮同驗證 JSON，支援語法高亮同一鍵複製 JSON Path

破壞性變更：移除兩個欄位

POST /v1/messages 參考文檔中移除咗兩個未實現嘅欄位，以符合實際 API 表面：

idempotency_key — 已移除。該欄位喺文檔中存在但從未喺設備 API 中實現。
provider_data.reply_to — 已從文檔表面移除。provider_data 物件而家以 parse_mode 作為範例欄位。

如果你嘅程式碼中用咗 idempotency_key 或 provider_data.reply_to，請檢查你係咪依賴咗實際上從未生效嘅行為。呢兩個欄位均未被 API 處理。

下一步

會話標籤同聯絡人訊息首先支援 WhatsApp，因為 WhatsApp 嘅上游 API 原生支援呢啲功能。隨住其他頻道增加等效能力——或者歸一化層能夠彌合差異——呢啲功能將以相同嘅端點表面喺更多頻道上線。501 unsupported_by_provider 回應係有意為之：佢明確話俾你知邊個頻道未支援某項功能，而唔係靜默丟棄請求。

完整嘅 API 參考文檔已上線：unifyport.ai/docs。