Kết nối tài khoản TikTok vào signed webhook bằng QR authorization

Để nhận tin nhắn TikTok qua UnifyPort, bước đầu tiên không phải là màn hình QR mà là webhook. Thứ tự an toàn là: đăng ký webhook endpoint có signing_secret, tạo tài khoản TikTok với auth_mode: "qrcode", bắt đầu QR authorization, poll trạng thái QR, để chủ tài khoản quét mã, rồi lưu các sự kiện message.received trước khi route sang Slack, helpdesk, AI worker hoặc queue nội bộ.

Ở Việt Nam, nhiều đội hỗ trợ phải chạy song song TikTok, Zalo và WhatsApp. Điểm hữu ích của UnifyPort là bạn có thể đưa các kênh này về cùng một event envelope, thay vì viết ba receiver khác nhau. Nếu đang thiết kế queue đa kênh, bài Zalo, WhatsApp và LINE trong một inbound queue là một ví dụ kiến trúc liên quan.

Tóm tắt nhanh

• Tạo webhook trước authorization, vì tiến trình auth và tin nhắn inbound đều được gửi dưới dạng events.
• TikTok authorization trong UnifyPort dùng account và QR auth endpoints chuẩn; response đầu tiên có thể chưa có QR URL, nên cần poll QR check endpoint.
• Verify X-Device-Signature từ X-Device-Timestamp + "." + raw body trước khi parse JSON.
• Lưu event vào durable storage trước, rồi mới route sang các workflow khác.
• Flow này khác với TikTok Login Kit QR authorization chính thức, vốn phục vụ app login, profile và scoped access.

Nếu bạn vẫn đang hỏi TikTok có public DM API tổng quát hay không, hãy đọc hướng dẫn TikTok DM API trước. Bài này tập trung vào bước sau: khi bạn đã chọn unofficial interface của UnifyPort và cần kết nối TikTok vào signed inbound stream. Checklist receiver tổng quát nằm trong webhook-first inbound integration checklist.

Thứ tự thiết lập

1. Tạo HTTPS webhook endpoint và đặt signing_secret.
2. Trong lần test đầu, chỉ subscribe message.received.
3. Tạo TikTok account với auth_mode: "qrcode".
4. Bắt đầu QR authorization flow.
5. Poll QR check endpoint cho tới khi có QR material, success state hoặc failure state.
6. Để chủ tài khoản TikTok quét và xác nhận.
7. Chờ auth/runtime events, sau đó gửi tin nhắn test và kiểm tra message.received.

Lý do phải tạo webhook trước: tài liệu UnifyPort xem webhook là bản ghi bền vững của inbound traffic. Đừng thiết kế hệ thống dựa trên giả định rằng mọi delivery bị bỏ lỡ đều có thể khôi phục đầy đủ sau này.

1. Đăng ký signed webhook endpoint

Trong production, hãy dùng HTTPS URL ổn định do đội bạn kiểm soát. Development có thể dùng tunnel, nhưng signature verification phải giống production.

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 reference mô tả url, status, subscribed_events, signing_secret và retry_policy.max_attempts. Nếu cần mọi public standard event, dùng ["*"]; còn lần test TikTok inbound đầu tiên thì message.received rõ ràng hơn.

2. Tạo TikTok account

Một channel login trong UnifyPort tương ứng với một account. TikTok provider guide mô tả TikTok là QR-code authorization flow.

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" }
}'

Lưu account ID trả về. Các ví dụ bên dưới dùng $ACCOUNT_ID để tránh dán production identifier thật vào log hoặc chat.

3. Bắt đầu QR authorization và poll

Bắt đầu QR flow với body rỗng:

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 '{}'

Với TikTok, initial start response có thể chưa chứa QR URL. Tiếp tục poll:

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 '{}'

Khi QR material xuất hiện, chỉ hiển thị cho người sở hữu tài khoản TikTok cần kết nối. Sau khi họ quét và approve, theo dõi webhook để nhận auth/runtime events rồi đến message.received.

4. Verify signature trước khi parse JSON

Webhook delivery and signature verification định nghĩa delivery contract. Khi signing bật, mỗi delivery có X-Device-Timestamp và X-Device-Signature; chữ ký là hex HMAC-SHA256 của:

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

Express receiver nên giữ 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') {
    // store event.id, event.account_id, event.occurred_at và event.data trước khi route
  }

  res.sendStatus(202);
});

Nếu signature mismatch, kiểm tra raw body, timestamp, secret và thứ tự middleware theo webhook HMAC replay-protection guide. Lỗi thường gặp là verify sau khi JSON đã bị parse hoặc format lại.

Hình dạng của message.received

Standard event envelope luôn có id, type, provider, account_id, occurred_at và data. Receiver nên lưu contract chung này, không hard-code schema riêng của TikTok.

{
  "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"
    }
  }
}

Store first, route second. AI classification, CRM enrichment hoặc assignment cho agent nên chạy sau khi event đã được accepted bền vững.

Giới hạn và đánh đổi

• Chủ tài khoản TikTok vẫn phải quét QR và authorize thật.
• Provider support và upstream availability có thể khác nhau theo account hoặc region; UI cần hiển thị auth failure và re-authentication states.
• Webhook delivery là at-least-once, nên dùng event.id hoặc X-Device-Event-Id làm idempotency key.
• HMAC xác thực nguồn và integrity, nhưng không mã hóa logs, queues hoặc databases.
• Nếu cần official app-login scopes hoặc profile APIs của TikTok, hãy dùng TikTok Developer Platform. Flow UnifyPort ở đây dành cho inbound messaging event stream.

FAQ

Flow này có cần TikTok developer app không?

Không. Kết nối account dùng account và QR authorization endpoints của UnifyPort. TikTok Login Kit là flow khác cho app login và scoped access.

Vì sao response đầu tiên chưa có QR URL?

TikTok provider guide ghi rằng initial start response có thể chưa chứa QR URL. Hãy poll QR check cho đến khi có QR material, success hoặc failure.

Nên subscribe ["*"] hay message.received?

Lần test đầu nên dùng message.received. Khi đã có handler cho auth, runtime, receipt và events khác, hãy mở rộng event list.

Bước tiếp theo

Mở song song TikTok authorization provider guide và Webhook delivery guide. Nếu đang thiết kế queue đa kênh cho Zalo và WhatsApp nữa, đọc tiếp Zalo Official Account API vs personal-account webhook.

Sources

Official sources checked on 2026-09-03:

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