← 所有文章
教學

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 帳戶所有私訊的通用 API。
  • New Message webhook 的事件類型為 14，payload 包含 tts_notification_id、shop_id、message_id、conversation_id、index、時間、訊息類型及發送者資料。
  • 接收端必須使用 TLS 1.2 或以上的 HTTPS、驗證 Authorization 簽署，並於三秒內回傳 200。
  • 投遞失敗會重試，因此佇列消費必須冪等；通知亦可能因網絡或平台狀態而不完整。
  • 缺漏要用 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。在歸因為網絡問題前，應同時確認 app 已啟用所需 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 要求三秒內以空 body 回傳 200。接收端只做驗證、最小可靠儲存、寫入佇列，然後立即回應；不要在回應前呼叫訂單系統、AI 模型或 CRM。

官方記載最多四次重試：首次失敗後兩分鐘，再依次於 30 分鐘、三小時及 12 小時後重試。保存 tts_notification_id 及 message_id，令重複工作不產生副作用。這是工程保護，不代表任何欄位可取代自己的事件帳本。

2. 以原始 body 驗證 TikTok Shop 簽署

TikTok Shop 在 Authorization header 放入 HMAC-SHA256 簽署。保留原始 bytes，嚴格按官方 webhook 指南及目前 app 憑證計算預期值，並以 constant-time comparison 比對。驗證失敗回傳 401；除錯時不可記錄 app secret、賣家 access token、完整簽署或買家訊息內容。

這套格式與 UnifyPort 的 X-Device-Timestamp、X-Device-Signature 不同，不能共用同一驗證器。

3. 先保存識別欄位再標準化

映射成內部工單前，完整保留 shop_id、conversation_id、message_id、index、create_time、發送者角色、type 及 is_visible。TikTok 說明較大的 index 代表較新的訊息，不能假設抵達次序等同訊息次序。

不可見或前端尚未支援的訊息類型應進入明確的人手檢查狀態，不可靜默轉成文字。

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 客服功能或保證官方 Shop 回覆。兩套整合及憑證必須隔離。

FAQ

TikTok Shop Customer Service API webhook 應訂閱哪個事件？

訊息接收使用 NEW_MESSAGE，通知 body 的數字類型為 14。NEW_CONVERSATION 是另一事件，不能取代訊息接收。

webhook 必須多快回應？

TikTok 要求三秒內回傳空 body 的 200。完成驗證及可靠入列後立即回應，耗時工作非同步執行。

如何處理重複通知？

保存 tts_notification_id 及 message_id，使用冪等寫入令工作可安全重試；同時保存 conversation_id 及 index，才可識別次序缺口。

webhook 能取代 Get Conversation Messages 嗎？

不能。TikTok 官方提醒不要完全依賴通知；漏收、亂序或 worker 停機後都要以歷史 API 核對。

這等同一般 TikTok 私訊 webhook 嗎？

不等同。這是經審批的 TikTok Shop 買家客服能力；一般帳戶私訊與 Shop 對話有不同權限、身份、資料及操作規則。

下一步

依 TikTok Shop 官方 webhook 設定指南訂閱 NEW_MESSAGE，完成上述六步驗收。若需求其實是一般帳戶入站，請改看 UnifyPort 的平台訊息支援矩陣。

來源

以下 TikTok Shop 官方資料於 2026 年 8 月 11 日完成核對：