用 QR 授權把 TikTok 帳號接到簽名 Webhook

要透過 UnifyPort 接收 TikTok 訊息，第一步不是打開 QR 畫面，而是先建立 webhook。建議順序是：註冊帶 signing_secret 的 webhook endpoint，建立 auth_mode: "qrcode" 的 TikTok 帳號，啟動 QR 授權，輪詢 QR 狀態，讓帳號持有人掃描確認，最後把送達的 message.received 事件先寫入資料庫或佇列。

重點整理

• 先建立 webhook，再做授權；授權進度與後續入站訊息都會以事件形式送達。
• UnifyPort 的 TikTok 授權使用標準 account 與 QR auth endpoint；首次 start 回應可能還沒有 QR URL，因此要輪詢 QR check。
• 收到 delivery 後，先用 X-Device-Timestamp + "." + raw body 驗證 X-Device-Signature，再解析 JSON。
• 入站事件要先持久化，再轉送到 Slack、客服系統、AI worker 或內部佇列。
• 這不是 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 表示，避免把真實識別碼貼到記錄或聊天軟體中。

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 回應可能暫時沒有 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 與簽名驗證文件定義了 UnifyPort delivery contract。啟用簽名後，delivery 會包含 X-Device-Timestamp 和 X-Device-Signature；簽名內容為：

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

Node.js 接收端應保留原始 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 已被解析或重新格式化。

message.received 長什麼樣

標準事件 envelope 永遠包含 id、type、provider、account_id、occurred_at 與 data。接收端應處理這個標準形狀，而不是寫死 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。若還在設計入站佇列，可以接著看 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