用 QR 授權將 TikTok 帳戶接入簽名 Webhook

要用 UnifyPort 接收 TikTok 訊息，第一步唔係打開 QR 畫面，而係先建立 webhook。建議流程係：註冊帶 signing_secret 的 webhook endpoint，建立 auth_mode: "qrcode" 的 TikTok 帳戶，啟動 QR 授權，輪詢 QR 狀態，讓帳戶持有人掃描確認，然後將送達的 message.received 事件先寫入資料庫或 queue。

重點

• 先建立 webhook，再做授權；授權進度同之後的入站訊息都會以事件形式送達。
• UnifyPort 的 TikTok 授權用標準 account 同 QR auth endpoint；首次 start response 可能未有 QR URL，所以要輪詢 QR check。
• 收到 delivery 後，先用 X-Device-Timestamp + "." + raw body 驗證 X-Device-Signature，再解析 JSON。
• 入站事件應先落地，再轉去 Slack、客服系統、AI worker 或內部 queue。
• 呢個流程唔等於 TikTok 官方 Login Kit 的 QR 授權；官方 Login Kit 係應用登入、profile 同 scope 授權流程。

如果你仲想確認 TikTok 有冇通用 DM API，請先睇 TikTok DM API 可用性說明。本文只講選擇 UnifyPort 非官方接口之後，點樣將 TikTok 帳戶接到一條簽名入站事件流。一般接收端設計可以配合 webhook-first 入站整合清單 一齊睇。

接入次序

1. 建立 HTTPS webhook endpoint，並設定 signing_secret。
2. 開發階段先訂閱 message.received；handler 準備好後再加入其他事件。
3. 建立 TikTok account，將 auth_mode 設為 qrcode。
4. 啟動 QR 授權流程。
5. 輪詢 QR check endpoint，直到取得可顯示 QR 資料、成功狀態或失敗狀態。
6. 讓 TikTok 帳戶持有人掃描確認。
7. 觀察授權 / runtime 事件，再發測試訊息，確認 message.received 抵達。

第一步最重要。UnifyPort 文件將 webhook 視為入站流量的持久記錄；唔應該假設漏接的 delivery 之後可以完整補回。

1. 建立簽名 webhook endpoint

正式環境應使用你控制的穩定 HTTPS URL。開發時可以用 tunnel，但驗簽流程要同正式環境一致。

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://inbox.example.com/unifyport/tiktok",
  "status": "active",
  "subscribed_events": ["message.received"],
  "signing_secret": "sea-support-tiktok-2026"
}'

Create webhook endpoint 參考列出 url、status、subscribed_events、signing_secret 同 retry_policy.max_attempts。第一次測試 TikTok 入站時，保留 message.received 會比直接用 ["*"] 更易排查。

2. 建立 TikTok 帳戶

建立 TikTok 連線帳戶。UnifyPort 將一次渠道登入視為一個 account，而 TikTok provider guide 說明此渠道採用 QR 授權。

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "TikTok Support Inbox",
  "provider": "tiktok",
  "region": "global",
  "status": "active",
  "auth_mode": "qrcode",
  "capabilities": ["receive_message"],
  "provider_data": {},
  "metadata": { "workflow": "support-intake" }
}'

保存回傳的 account ID。以下用 $ACCOUNT_ID 表示，避免將真實識別碼貼入 log 或聊天工具。

3. 啟動 QR 授權並輪詢

先啟動 QR 流程：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

TikTok 首次 start response 可能暫時未有 QR URL。繼續輪詢：

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/check" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

取得 QR 資料後，只展示俾需要連接該 TikTok 帳戶的人。掃描確認後，等 webhook 收到授權/runtime 事件，再查看第一個 message.received。

4. 先驗簽，再解析 JSON

Webhook delivery 同 signature verification 文件定義了 delivery contract。啟用簽名後，delivery 會包含 X-Device-Timestamp 和 X-Device-Signature；簽名內容係：

<X-Device-Timestamp>.<raw request body>

Node.js 接收端應保留 raw body：

import crypto from 'node:crypto';
import express from 'express';

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

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

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

  if (signature.length !== expected.length) return res.sendStatus(401);
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type === 'message.received' && event.provider === 'tiktok') {
    // 先儲存 event.id、event.account_id、event.occurred_at 同 event.data，再路由
  }

  res.sendStatus(202);
});

如果驗簽失敗，對照 webhook HMAC replay protection 指南檢查 raw body、timestamp、secret 同 middleware 次序。最常見問題係 JSON 已被 parse 或重新格式化。

message.received 的形狀

標準 event envelope 一定包含 id、type、provider、account_id、occurred_at 同 data。handler 應處理呢個標準形狀，而唔係寫死 TikTok 專屬 schema：

{
  "id": "evt_2f9c1a4b7e",
  "type": "message.received",
  "provider": "tiktok",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:34:56Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "text": "Hi - is this item still available?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:34:55Z"
    }
  }
}

先存，再分發。AI 分類、CRM 補資料或客服分派，都應該喺事件持久化之後進行。

限制與取捨

• TikTok 帳戶仍然需要真人持有人掃描 QR 並授權。
• 渠道能力同上游可用性可能因帳戶或地區而變；產品介面要能顯示授權失敗同重新授權狀態。
• Webhook delivery 是 at-least-once；請用 event.id 或 X-Device-Event-Id 做冪等。
• HMAC 驗證來源同完整性，但唔會加密你的 log、queue 或 database。
• 如果你需要 TikTok 官方 app-login scope 或 profile API，請使用 TikTok 官方開發者平台；UnifyPort 呢條路負責入站訊息事件流。

FAQ

呢個流程需要 TikTok developer app 嗎？

唔需要。UnifyPort 帳戶連線使用 UnifyPort 的 account 同 QR 授權端點。TikTok 官方 Login Kit 係另一條 app-login 同 scope 授權路徑。

點解首次 start 無 QR URL？

TikTok provider guide 說明首次 start response 可能沒有 QR URL。繼續輪詢 QR check，直到 QR 資料、成功或失敗狀態出現。

應訂閱 ["*"] 定 message.received？

第一次測試建議只訂閱 message.received。等你準備好處理 auth、runtime、receipt 等事件，再改成 ["*"] 或加入更多事件名。

下一步

並排閱讀 TikTok authorization provider guide 同 Webhook delivery guide。若仍在設計入站 queue，可以繼續睇 TikTok live-DM queue 教學。

來源

官方來源核對日期：2026-09-03：

• UnifyPort：TikTok authorization
• UnifyPort：Create webhook endpoint
• UnifyPort：Webhook delivery and signature verification
• TikTok for Developers：QR Code Authorization