เชื่อมต่อบัญชี TikTok เข้ากับ Signed Webhook ด้วย QR Authorization

ถ้าต้องการรับข้อความ TikTok ผ่าน UnifyPort ให้เริ่มจาก webhook ไม่ใช่หน้าจอ QR ก่อน ลำดับที่ปลอดภัยคือสร้าง webhook endpoint ที่มี signing_secret สร้างบัญชี TikTok ด้วย auth_mode: "qrcode" เริ่ม QR authorization แล้ว poll สถานะ QR ให้เจ้าของบัญชีสแกน จากนั้นเก็บอีเวนต์ message.received ที่ส่งเข้ามาไว้ก่อนค่อย route ต่อไปยัง Slack, helpdesk, AI worker หรือ queue ภายใน

สำหรับทีมในไทย LINE มักเป็นช่องทางหลัก ส่วน TikTok เป็นช่องทาง discovery และ customer inquiry ที่เพิ่มขึ้นเรื่อย ๆ จุดสำคัญของ UnifyPort คือคุณสามารถรับ TikTok และ LINE ด้วยรูปแบบ webhook เดียวกันได้ หากกำลังออกแบบฝั่ง LINE ควบคู่กัน อ่าน LINE service messages กับ webhook intake เพิ่มเติมได้

สรุปสำคัญ

• สร้าง webhook ก่อน authorization เพราะ progress ของ auth และข้อความ inbound จะถูกส่งมาเป็น events
• TikTok authorization ใน UnifyPort ใช้ account และ QR auth endpoints มาตรฐาน; response แรกอาจยังไม่มี QR URL จึงต้อง poll QR check endpoint
• ตรวจ X-Device-Signature จาก X-Device-Timestamp + "." + raw body ก่อน parse JSON
• เก็บ event ลง durable storage ก่อน route ไป workflow อื่น
• Flow นี้ไม่ใช่ TikTok Login Kit QR authorization ของทางการ ซึ่งเป็น flow สำหรับ app login, profile และ scoped access

ถ้าคำถามของคุณคือ TikTok มี public DM API ทั่วไปหรือไม่ ให้อ่าน คู่มือ TikTok DM API ก่อน บทความนี้โฟกัสเฉพาะขั้นตอนเมื่อเลือกใช้ unofficial interface ของ UnifyPort แล้ว และควรเปิด webhook-first inbound integration checklist ควบคู่เพื่อเช็กฝั่ง receiver

ลำดับการตั้งค่า

1. สร้าง HTTPS webhook endpoint พร้อม signing_secret
2. ระหว่างทดสอบ subscribe เฉพาะ message.received
3. สร้าง TikTok account โดยตั้ง auth_mode เป็น qrcode
4. เริ่ม QR authorization flow
5. Poll QR check endpoint จนได้ QR material, success state หรือ failure state
6. ให้เจ้าของบัญชี TikTok สแกนและยืนยัน
7. รอ auth/runtime events แล้วส่งข้อความทดสอบเพื่อดู message.received

เหตุผลที่ต้องสร้าง webhook ก่อนคือ UnifyPort ถือ webhook เป็น record หลักของ inbound traffic อย่าวางแผนโดยคิดว่าข้อความที่พลาดไปจะกู้คืนได้ครบภายหลัง

1. สร้าง signed webhook endpoint

ใช้ HTTPS URL ที่ทีมคุณควบคุม ใน development อาจใช้ tunnel ได้ แต่ signature verification ต้องเหมือน 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 อธิบาย url, status, subscribed_events, signing_secret และ retry_policy.max_attempts ถ้าต้องการทุก public standard event ใช้ ["*"] ได้ แต่สำหรับ first test ของ TikTok inbound ให้เริ่มจาก message.received ก่อนจะ debug ง่ายกว่า

2. สร้าง TikTok account

UnifyPort มองหนึ่ง channel login เป็นหนึ่ง account และ TikTok provider guide ระบุว่า TikTok ใช้ QR-code authorization

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 เพื่อไม่ให้ต้องวาง production identifier จริงใน log หรือ chat

3. เริ่ม QR authorization และ poll

เริ่ม QR flow ด้วย body ว่าง:

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 response แรกอาจยังไม่มี QR URL ให้ poll endpoint นี้ต่อ:

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 material ให้แสดงเฉพาะกับเจ้าของบัญชีที่จะเชื่อมต่อ หลังจากสแกนและยืนยัน ให้ดู webhook สำหรับ auth/runtime events แล้วตามด้วย message.received

4. Verify signature ก่อน parse JSON

Webhook delivery and signature verification คือสัญญาหลักของ delivery เมื่อเปิด signing จะมี X-Device-Timestamp และ X-Device-Signature โดย signature คือ hex HMAC-SHA256 ของ:

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

Express receiver ควรเก็บ 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 และ event.data ก่อน route
  }

  res.sendStatus(202);
});

ถ้า signature ไม่ตรง ให้เทียบกับ webhook HMAC replay protection guide โดยตรวจ raw body, timestamp, secret และ middleware order สาเหตุยอดนิยมคือ parse หรือ format JSON ใหม่ก่อน verify

รูปแบบของ message.received

Standard event envelope มี id, type, provider, account_id, occurred_at และ data เสมอ อย่าออกแบบ handler ให้ผูกกับ schema เฉพาะ 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 ก่อน route เสมอ งานช้าอย่าง AI classification, CRM enrichment หรือ agent assignment ควรทำหลัง event ถูกยอมรับแบบ durable แล้ว

ข้อจำกัดและ trade-offs

• เจ้าของบัญชี TikTok ต้องสแกน QR และ authorize จริง
• ความพร้อมของ provider อาจแตกต่างตามบัญชีและ region UI ควรแสดง auth failure และ re-authentication state ได้
• Webhook delivery เป็น at-least-once ใช้ event.id หรือ X-Device-Event-Id เป็น idempotency key
• HMAC ยืนยัน source และ integrity แต่ไม่ได้ encrypt logs, queues หรือ databases
• ถ้าต้องการ official app-login scopes หรือ profile APIs ของ TikTok ให้ใช้ TikTok Developer Platform; UnifyPort ใน flow นี้ใช้สำหรับ inbound messaging event stream

FAQ

ต้องมี TikTok developer app ไหม?

ไม่ต้อง Flow นี้ใช้ account และ QR authorization endpoints ของ UnifyPort ส่วน TikTok Login Kit เป็นอีก flow สำหรับ app login และ scoped access

ทำไม response แรกยังไม่มี QR URL?

TikTok provider guide ระบุว่า initial start response อาจไม่มี QR URL ให้ poll QR check จนมี QR material, success หรือ failure

ควร subscribe ["*"] หรือ message.received?

เริ่มจาก message.received สำหรับ first test แล้วค่อยเพิ่ม auth, runtime, receipt หรือ events อื่นเมื่อ handler พร้อม

ขั้นถัดไป

เปิด TikTok authorization provider guide และ Webhook delivery guide คู่กัน หากต้องขยายไป LINE ในไทยด้วย ดู LINE inbound handler build log ต่อได้

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