教程 August 29, 2026

用 GitHub Copilot 搭一个 TikTok DM Webhook 接收器

如果你要做 TikTok 私信客服，先别让 AI 写“猜出来”的 TikTok JSON。更稳的做法是把真实契约给 GitHub Copilot：UnifyPort 会把 TikTok 入站消息整理成统一的 message.received 事件，并用 X-Device-Signature 对原始请求体做 HMAC-SHA256 签名。

要点

TikTok 官方开发者文档里，私信相关内容主要出现在 Data Portability 的导出范围与数据类型里，不是通用实时客服 webhook。
让 Copilot 依据 UnifyPort API reference 写代码：POST /v1/webhook-endpoints、subscribed_events、signing_secret、X-Device-Timestamp、X-Device-Signature。
必须先校验 raw body，再解析 JSON；重新序列化后的 JSON 字节会导致签名校验失败。
对跨境团队来说，先存事件，再路由到 Slack、CRM 或 AI 分流 worker，比直接把业务逻辑写进入口更安全。

如果你还在确认“TikTok DM API 到底有没有实时入口”，先看这篇：TikTok DM API：为什么没有官方通用端点。如果你已经确定需要实时入站流，再参考 TikTok Data Portability 与实时 DM 的区别。

你会得到什么

最终 demo 是一个小型 Node.js 服务，只有一个 /webhook 路由。它接收 UnifyPort 事件，验证 X-Device-Timestamp 与 X-Device-Signature，解析 message.received，把必要字段写入队列，然后返回 200。

实现时请把 Webhook delivery & signature verification 打开作为唯一技术依据。这里的重点不是 TikTok 的某个特殊字段，而是统一事件层：同一个 receiver 后续也能接 WhatsApp、LINE、Zalo、Telegram 或 X。

给 Copilot 的第一段上下文

把以下提示交给 Copilot，而不是只说“帮我做一个 TikTok inbox”：

Build a minimal Express service for a UnifyPort webhook receiver.
Use express.raw({ type: 'application/json' }). Verify X-Device-Signature as hex HMAC-SHA256 over X-Device-Timestamp + '.' + raw request body using WEBHOOK_SIGNING_SECRET.
Only process event.type === 'message.received'. Store provider, account_id, conversation.id, sender.id, message.id, message.text, message.direction, and occurred_at.
Return 200 after storing; return 401 on invalid signature.

Copilot 生成的核心代码应接近这样：

import crypto from 'crypto';
import express from 'express';

const app = express();
const secret = process.env.WEBHOOK_SIGNING_SECRET;
const queue = [];

function verifySignature(req) {
  const timestamp = req.get('X-Device-Timestamp') || '';
  const signature = req.get('X-Device-Signature') || '';
  const expected = crypto.createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(req.body)
    .digest('hex');
  return signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();
  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type !== 'message.received') return res.status(200).end();
  queue.push({
    provider: event.provider,
    account_id: event.account_id,
    conversation_id: event.data.conversation.id,
    sender_id: event.data.sender.id,
    message_id: event.data.message.id,
    text: event.data.message.text || '',
    direction: event.data.message.direction,
    occurred_at: event.occurred_at,
  });
  res.status(200).end();
});

注册 webhook

部署 HTTPS receiver 后，用真实端点创建 webhook。subscribed_events 可以写精确事件名；signing_secret 用来启用签名头。

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

如果你想看更完整的 AI 编程流程，可以对照 AI coding agent 自动回复 bot 教程。

运行与扩展

当 TikTok 账号出现新消息时，receiver 应按文档字段处理：id、type、provider、account_id、occurred_at、data.conversation.id、data.sender.id、data.message.id。第二个提示可以让 Copilot 加上幂等：使用 X-Device-Event-Id 去重重试，保存 raw event，只把 direction === 'inbound' 的消息进入客服分流。

限制

如果你需要官方内容发布、登录、研究工具或数据导出，请使用 TikTok 官方 API。UnifyPort 的非官方接口适合已有账号的实时入站消息接收；它不等于 TikTok 官方产品范围，而是提供可校验、可存储的事件流。

FAQ

GitHub Copilot 能直接完成整个 inbox 吗？

它可以生成 receiver、测试和队列代码，但签名校验、密钥管理、存储策略仍然需要人工 review。

TikTok Data Portability 是实时 DM 吗？

不是。官方文档列出的是私信导出范围和数据类型；客服系统通常需要实时事件流。

应该订阅哪个事件？

只做入站消息时订阅 message.received。只有在做全量事件采集时才考虑 ["*"]。

Sources checked on 2026-08-29

UnifyPort API

让消息接入变成一条稳定的产品管线。

先用统一 API 跑通发送，再用标准事件把所有入站消息接回业务系统。

获取 API Key 浏览 API 参考