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. 執行正式環境驗收
使用已授權的開發或正式商店，保存不含機密的驗收證據：
- 買家開始或繼續 Shop 客服對話。
- 端點收到類型
14、簽章通過，並在三秒內回傳200。 - 佇列以
shop_id與conversation_id更新正確對話。 - 人為重試 worker 不會建立重複訊息。
- Get Conversation Messages 找到同一個
message_id，也能補回刻意製造的 index 缺口。 - 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 日完成核對：