← 所有文章
教程

TikTok Shop Customer Service API Webhook 上线检查清单

要把 TikTok Shop Customer Service API webhook 安全上线，应为已授权店铺订阅 NEW_MESSAGE，先校验每次通知，再在三秒内返回 200，业务处理全部放入异步队列。最后还要用 Get Conversation Messages 对账，因为 TikTok 明确说明不能把 webhook 当作完整事实来源。这条官方路径要求 Customer Service 自定义 scope 已获批，并完成卖家授权。

要点

  • Customer Service API 只覆盖 TikTok Shop 买家与卖家的客服会话，不是普通 TikTok 账号所有私信的通用接口。
  • New Message webhook 的事件类型为 14，载荷包含 tts_notification_id、shop_id、message_id、conversation_id、index、时间、消息类型和发送者等字段。
  • 接收端必须使用 TLS 1.2 及以上的 HTTPS、校验 Authorization 签名，并在三秒内返回 200。
  • webhook 失败会重试，队列消费必须幂等；网络和平台不确定性也意味着通知可能不完整。
  • 缺口应通过 GET /customer_service/202309/conversations/{conversation_id}/messages 补齐；查询消息不会自动标记已读。

TikTok Shop Customer Service API webhook 配置

本文从资格审批完成后开始。如果应用尚未获得 Customer Service 自定义 scope，请先使用申请资格检查清单。TikTok 当前为会话 API 标注 seller.customer_service，而 Update Shop Webhook 操作要求 seller.authorization.info。排查网络前，应同时确认应用已启用相应 scope，且卖家 token 已实际授权。

官方 Customer Service API 提供 New Conversation 和 New Message 两类 hook。消息接入应在 Partner Center 配置 NEW_MESSAGE，或调用：

PUT /event/202309/webhooks
event_type: NEW_MESSAGE
address: https://support.example.com/webhooks/tiktok-shop

该请求还需要常规签名参数、卖家 access token 和 shop_cipher。示例域名仅用于说明，生产环境必须使用你方稳定持有的地址。

生产实现清单

1. 把应答与业务处理分开

TikTok 要求在三秒内以空响应体返回 200。接收端应依次完成请求校验、最小持久化、写入队列和应答；不要在返回前调用订单系统、AI 模型或 CRM。

官方记录的失败重试最多四次：首次失败后两分钟，随后分别间隔 30 分钟、三小时和 12 小时。保存 tts_notification_id 与 message_id，让重复消费不产生副作用。这是工程保护措施，不代表任一字段可以替代你方事件台账。

2. 基于原始请求体校验 TikTok Shop 签名

TikTok Shop 在 Authorization 请求头中放置 HMAC-SHA256 签名。保留原始字节，严格按官方 webhook 指南用当前应用凭据计算期望值，并使用恒定时间比较。认证失败返回 401；排查时不要记录 app secret、卖家 access token、完整签名或买家消息正文。

TikTok Shop 的签名协议与 UnifyPort 的 X-Device-Timestamp、X-Device-Signature 不同，不能共用同一个验证器。

3. 先保留标识，再做内部标准化

在映射为工单前，完整保留 shop_id、conversation_id、message_id、index、create_time、发送者角色、type 和 is_visible。TikTok 文档说明较大的 index 代表较新的消息，不能假定 webhook 到达顺序就是消息顺序。

不可见或尚未支持的消息类型应进入明确的人工检查状态，不要静默转换成文本。

4. 对账会话历史

发现 index 缺口、worker 重启或需要人工重放时，调用官方历史接口：

GET /customer_service/202309/conversations/{conversation_id}/messages

该接口要求 seller.customer_service，page_size 最大为 10，后续页面使用 next_page_token。重建顺序时按 index 排序。查询本身不会标记已读，只有业务中的客服确实消费消息后，才应调用独立的 Read Message 操作。

5. 完成生产验收

使用已授权的开发或生产店铺，保留不含敏感信息的证据：

  1. 买家开始或继续一段 Shop 客服会话。
  2. 端点收到类型 14，签名通过，并在三秒内返回 200。
  3. 队列任务用 shop_id 与 conversation_id 更新正确会话。
  4. 主动重试 worker 不会生成重复消息。
  5. Get Conversation Messages 返回同一个 message_id，人为制造的 index 缺口可以补齐。
  6. Partner Center 的 Development Kits → Webhook Log 显示接收成功。

UnifyPort 适用位置

如果需要 Shop 买家身份、卖家授权、订单关联客服、原生坐席状态或官方 Shop 回复，应使用 TikTok Shop Customer Service API。UnifyPort 不会授予 seller.customer_service，也不会把普通 TikTok 私信变成 Shop 会话。

普通账号入站是另一条路径。UnifyPort 可把当前支持的 TikTok 消息作为标准 message.received 事件投递。选择前请阅读普通 TikTok DM API 的能力边界和当前平台消息支持矩阵，其接收端遵循独立的 UnifyPort webhook 投递与签名指南。

限制与权衡

官方 Shop API 最适合电商客服，但需要自定义 scope 审批、卖家授权、有效店铺凭据及消息类型适配。webhook 不能代替历史对账或授权生命周期管理。

非官方接口不能审批 Customer Service scope、提供 Seller Center 订单数据、复刻 TikTok Shop 坐席功能或保证官方回复能力。两套接口及凭据必须隔离。

FAQ

TikTok Shop Customer Service API webhook 应订阅哪个事件？

消息接入使用 NEW_MESSAGE，通知正文中的数字类型为 14。NEW_CONVERSATION 是独立事件，不能替代消息接入。

webhook 必须多快返回？

TikTok 要求三秒内返回空响应体的 200。完成验证与可靠入队后立即应答，耗时业务异步执行。

如何处理重复通知？

保存 tts_notification_id 和 message_id，用幂等写入保证任务可安全重试；同时保留 conversation_id 与 index，才能识别顺序缺口。

webhook 能替代 Get Conversation Messages 吗？

不能。TikTok 官方说明不能完全依赖通知；应使用历史接口修复漏收、乱序和 worker 停机期间的缺口。

这是否等同于普通 TikTok 私信 webhook？

不是。这是经审批的 TikTok Shop 买家客服能力。普通账号私信与 Shop 客服会话的权限、身份、数据和运行规则不同。

下一步

按照 TikTok Shop 官方 webhook 配置指南订阅 NEW_MESSAGE，再完成上面的六步验收。如果真实需求是普通账号入站，请改看 UnifyPort 的平台消息支持矩阵。

来源

以下 TikTok Shop 官方资料核验于 2026 年 8 月 11 日：