TikTok 資料可攜唔等於即時私訊：建立客服真正需要嘅入站隊列

TikTok 嘅開發者介面愈來愈清楚，但文件更精準，唔代表佢啱啱好解決客服團隊眼前嘅問題。

6 月 4 日，TikTok 喺 Data Portability API changelog 入面說明，Data Types 文件已更新，用嚟反映目前支援嘅資料類別同欄位。Data Portability API 產品頁說明，呢個 API 面向歐洲經濟區同英國嘅 TikTok 用戶，容許用戶授權將自己嘅資訊傳輸到另一個應用程式。現時 data types 頁面 亦列出 Direct Messages 作為可匯出類別，欄位包括日期、傳送者同內容。

呢件事對資料可攜、封存、備份同合規流程有價值。但佢唔係即時客服收件箱。

如果你嘅團隊做 TikTok Shop、創作者活動或者直播銷售，真正需要係另一件事：每一則新私訊都應該進入隊列，被去重，觸發 CRM 查詢，再分配畀同事或 AI 助手。用戶授權嘅歷史匯出無法提供呢個事件循環。帶簽名嘅入站 webhook 可以。

先定義整合要完成嘅工作

揀 API 之前，先用普通語句寫低工作流：

1. 客戶送出一則 TikTok 私訊。
2. 後端喺幾秒內收到呢則訊息。
3. 投遞帶簽名，伺服器可以確認來源可信。
4. 訊息被儲存，因為錯過嘅事件之後無法補回。
5. 同一個隊列將來仲可以接收 WhatsApp、LINE、Zalo、Telegram 或 X 訊息。

TikTok Data Portability API 唔係為呢個順序設計。佢係用戶授權嘅資料傳輸產品。申請方需要服務歐洲經濟區或英國用戶，通過私隱同安全審查，並請求明確嘅資料範圍。佢嘅資料模型圍繞匯出：帖文同個人資料、活動、私訊或完整封存。

呢個唔係客服需要嘅時間模型。客服問嘅唔係「呢個用戶可唔可以匯出昨日嘅封存」，而係「十秒前入嚟嗰則訊息，我哋可唔可以即刻處理」。

UnifyPort 嘅 webhook 結構

UnifyPort 嘅 TikTok 非官方接口面向第二種模型。你連接 TikTok 帳號，註冊 webhook endpoint，並訂閱 message.received。客戶訊息到達後，UnifyPort 會向你嘅後端送出一個標準事件包：

{
  "id": "evt_7a4d2c91b6",
  "type": "message.received",
  "provider": "tiktok",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-07-05T03:18:42Z",
  "data": {
    "conversation": { "id": "tt_conv_9172", "type": "user", "title": "Mai Nguyen" },
    "sender": { "id": "tt_user_4839", "name": "Mai Nguyen", "type": "user" },
    "message": {
      "id": "tt_msg_20260705_001",
      "type": "text",
      "text": "今晚直播前黑色 tote bag 仲有貨嗎？",
      "direction": "inbound",
      "sent_at": "2026-07-05T03:18:41Z"
    }
  }
}

重點係呢個事件包：id、type、provider、account_id、occurred_at 同 data。同一個處理器今日可以處理 provider: "tiktok"，聽日可以處理 provider: "zalo"。路由層只應該喺平台行為確實唔同時先分支。

先註冊 endpoint

連接隊列之前，先建立 webhook。endpoint 會保存 URL、訂閱事件、簽名狀態同重試策略。設定 signing_secret 後，每次投遞都會帶上 X-Device-Timestamp 同 X-Device-Signature。

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["message.received"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

UnifyPort 使用 HMAC-SHA256 對時間戳、一個點同原始請求 body 進行簽名。必須喺解析 JSON 前用原始 bytes 驗證。唔好先解析再重新序列化，因為嗰樣會改變被驗證嘅 bytes。

import crypto from "crypto";
import express from "express";

const app = express();
const signingSecret = process.env.WEBHOOK_SIGNING_SECRET;

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-Device-Timestamp");
  const signature = req.get("X-Device-Signature");

  const hmac = crypto.createHmac("sha256", signingSecret);
  hmac.update(timestamp);
  hmac.update(".");
  hmac.update(req.body);
  const expected = hmac.digest("hex");

  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!valid) {
    res.status(401).end();
    return;
  }

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.type === "message.received") {
    console.log(event.provider, event.data.sender.id, event.data.message.text);
  }

  res.status(200).end();
});

app.listen(3000);

呢個已經足夠作為入站邊界。正式環境可以將事件寫入隊列，但邊界不變：帶簽名嘅投遞入嚟，驗證後嘅事件出去。

先儲存，再路由

UnifyPort 文件明確說明，webhook 事件係入站流量嘅唯一記錄。冇訊息讀取 API，亦冇錯過 payload 後嘅回補路徑。因此隊列設計要先圍繞儲存。

第一步寫入應按 id 保存事件，同時保存原始請求 body 或解析後嘅 JSON、provider、account ID 同 occurred_at。寫入成功後，再非同步路由：

TikTok message
  -> UnifyPort message.received webhook
  -> Signature verification
  -> Event store keyed by id
  -> Routing queue
  -> CRM lookup, Slack alert, helpdesk ticket, or AI triage

呢度亦可以睇清 Data Portability API 應該放喺咩位置。匯出適合用戶授權嘅資料移動。即時客服隊列適合營運處理。兩者可以共存，但唔應該混為一談。

只有需要回覆時再加入傳送流程

有啲團隊只需要入站分流。有啲團隊希望隊列喺人工或 AI 助手決策後產生回覆。將回覆作為明確第二步。

傳送訊息時，UnifyPort 使用 POST /v1/messages，並傳入帳號、接收者同標準訊息 body。入站事件會畀你 provider、account、sender、conversation 同 message text；回覆流程再決定是否傳送。

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "acc_8c21d0",
  "to": { "id": "tt_user_4839", "type": "user" },
  "message": { "type": "text", "text": "黑色 tote bag 仲有貨，可以喺今晚直播前下單。" }
}'

入站同出站應該喺程式碼中保持分離。第一條路徑負責捕獲同保存客戶訊息。第二條路徑只喺業務邏輯決定後傳送回應。

點解 2026 年 7 月要重新區分呢件事

TikTok 6 月 4 日嘅文件更新提醒我哋：平台 API 往往只服務某個政策或產品面。Data portability 係用戶控制嘅資料傳輸。Content Posting 係發布。Display API 係創作者內容展示。呢啲名稱都唔會自動等於「即時客服私訊收件箱」。

小團隊常見嘅時間浪費，就係將每一個新文件化嘅 API 類別都當成客服事件流。更穩嘅做法係先命名工作流，再選擇符合佢時間模型嘅接口。

如果工作流係匯出，就用匯出工具。如果工作流係客服，就用 webhook。如果工作流今日覆蓋 TikTok、下個月仲要覆蓋 Zalo 或 LINE，就由一開始保持標準化事件包。

呢個就係實際分工：TikTok Data Portability 幫用戶移動自己嘅資料；UnifyPort 幫你嘅客服系統喺訊息到達時收到佢哋。