チュートリアル August 11, 2026

TikTok Shop Customer Service API Webhook 本番導入チェックリスト

TikTok Shop Customer Service API webhook を本番導入するには、認可済みショップで NEW_MESSAGE を購読し、通知を検証して3秒以内に 200 を返し、実処理を非同期キューへ渡します。さらに Get Conversation Messages で履歴を照合してください。TikTok は webhook だけに完全依存しないよう明記しています。この公式経路には Customer Service のカスタム scope 承認とセラー認可が必要です。

要点

Customer Service API は TikTok Shop の購入者とセラーのサポート会話向けで、通常の TikTok アカウントに届く全DMの汎用 API ではありません。
New Message webhook はイベントタイプ 14 で、tts_notification_id、shop_id、message_id、conversation_id、index、時刻、メッセージ種別、送信者を含みます。
受信先は TLS 1.2 以上の HTTPS、Authorization 署名検証、3秒以内の 200 応答が必要です。
失敗時には再送されるため、キュー処理を冪等にし、webhook の欠落にも備えます。
欠落は GET /customer_service/202309/conversations/{conversation_id}/messages で照合します。この取得だけでは既読になりません。

TikTok Shop Customer Service API webhook の設定

ここでは審査通過後を扱います。まだ Customer Service のカスタム scope がない場合は、先に申請資格チェックリストを確認してください。会話 API には seller.customer_service、Update Shop Webhook には seller.authorization.info が記載されています。通信障害と判断する前に、app 側の scope とセラートークンの権限を両方確認します。

メッセージ受信は Partner Center で NEW_MESSAGE を設定するか、次の操作を使います。

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

通常の署名済みリクエストパラメータ、セラー access token、shop_cipher も必要です。例の URL は本番に流用せず、自社管理の安定したエンドポイントを使ってください。

本番実装チェックリスト

1. 応答と業務処理を分離する

TikTok は空の response body と 200 を3秒以内に返すよう求めています。受信時には検証、最小限の永続化、キュー投入だけを行い、すぐ応答します。注文システム、AI、CRM の呼び出しは応答後に実行します。

失敗時の再送は最大4回で、初回失敗から2分後、その後30分、3時間、12時間の順です。tts_notification_id と message_id を保存し、同じジョブを再実行しても重複を作らないようにします。これは実装上の防御であり、どちらかの値だけで独自のイベント台帳を置き換えられるという保証ではありません。

2. raw body で TikTok Shop 署名を検証する

TikTok Shop は Authorization header に HMAC-SHA256 署名を置きます。raw bytes を保持し、公式 webhook ガイドどおりに現在の app credentials から期待値を計算し、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、sender role、type、is_visible を保存します。TikTok によると、大きい index ほど新しいメッセージです。到着順を会話順とみなしてはいけません。

非表示または未対応の message type は黙ってテキスト化せず、明示的な確認状態へ送ります。

4. 会話履歴を照合する

index の欠落、worker 再起動、手動 replay があれば次を呼び出します。

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

必要 scope は seller.customer_service、page_size は最大10、次ページは next_page_token を使います。順序復元は index 基準にします。取得だけでは既読にならないため、実際にエージェントが処理した時点で別の Read Message 操作を使います。

5. 本番受入テストを行う

認可済みの開発または本番ショップで、機密情報を含まない証跡を残します。

購入者が Shop のサポート会話を開始または継続する。
endpoint がタイプ 14 を受信し、署名検証後3秒以内に 200 を返す。
キューが shop_id と conversation_id で正しい会話を更新する。
worker を意図的に再試行しても重複メッセージができない。
Get Conversation Messages で同じ message_id を確認し、意図的な index 欠落も回復する。
Partner Center の Development Kits → Webhook Log で成功を確認する。

UnifyPort が適する場所

Shop 購入者ID、セラー認可、注文連携サポート、公式エージェント状態、Shop 返信が必要なら TikTok Shop Customer Service API を使います。UnifyPort は seller.customer_service を付与せず、通常DMを Shop 会話へ変換しません。

通常アカウントの受信は別経路です。UnifyPort は対応する TikTok メッセージを標準 message.received イベントとして配信できます。一般 TikTok DM API の境界とプロバイダー別メッセージ対応表を確認し、受信側は別の UnifyPort webhook 配信・署名ガイドに従ってください。

制限とトレードオフ

公式 Shop API はコマースサポートに最適ですが、カスタム scope 審査、セラー認可、有効な Shop credentials、message type 対応が必要です。webhook は履歴照合や認可ライフサイクル管理を不要にはしません。

非公式インターフェースは Customer Service scope の承認、Seller Center の注文データ、Shop のエージェント機能、公式 Shop 返信を提供できません。2つの経路と認証情報を分離してください。

FAQ

Customer Service API webhook では何を購読しますか？

メッセージ受信には NEW_MESSAGE を使います。通知本文の数値タイプは 14 です。NEW_CONVERSATION は別イベントです。

webhook は何秒以内に応答しますか？

TikTok の要件は3秒以内の空 body の 200 です。検証と確実なキュー投入後すぐ応答します。

重複通知はどう処理しますか？

tts_notification_id と message_id を保存して冪等に書き込み、conversation_id と index で順序欠落も検出します。

webhook だけで履歴を管理できますか？

できません。TikTok は通知に完全依存しないよう案内しています。欠落、順不同、停止後は履歴 API で照合します。

一般 TikTok DM webhook と同じですか？

違います。これは承認済み TikTok Shop の購入者サポート機能であり、通常DMとは権限、ID、データ、運用ルールが異なります。

次のステップ

TikTok Shop 公式の webhook configuration guideで NEW_MESSAGE を設定し、上記6項目を検証してください。通常アカウント受信が目的なら、UnifyPort のメッセージ対応表を確認します。

参照元

以下の TikTok Shop 公式資料を2026年8月11日に確認しました。