更新日誌 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。