← Все статьи
Руководство

Webhook TikTok Shop Customer Service API: чек-лист запуска

Для безопасного запуска webhook TikTok Shop Customer Service API подпишите авторизованный магазин на NEW_MESSAGE, проверяйте каждое уведомление, возвращайте 200 не позднее трех секунд и обрабатывайте сообщения через асинхронную очередь. Затем сверяйте данные с Get Conversation Messages: TikTok прямо предупреждает, что нельзя полностью полагаться только на webhooks. Для этого официального пути нужны одобренный scope Customer Service и авторизация продавца.

Главное

  • Customer Service API обслуживает диалоги покупателей и продавцов TikTok Shop, а не все личные сообщения обычного аккаунта TikTok.
  • Webhook New Message имеет тип события 14; payload содержит tts_notification_id, shop_id, message_id, conversation_id, index, время, тип сообщения и отправителя.
  • Приемник должен работать по HTTPS с TLS 1.2+, проверять подпись Authorization и отвечать 200 в течение трех секунд.
  • Неудачные доставки повторяются, поэтому обработка должна быть идемпотентной; сам поток уведомлений может быть неполным.
  • Пропуски сверяются через GET /customer_service/202309/conversations/{conversation_id}/messages; этот запрос не помечает сообщения прочитанными.

Настройка webhook TikTok Shop Customer Service API

Этот материал начинается после проверки права доступа. Если приложение еще не получило пользовательский scope Customer Service, сначала пройдите чек-лист допуска. Для API диалогов TikTok указывает seller.customer_service, а для Update Shop Webhook — seller.authorization.info. До диагностики сети проверьте и scope приложения, и фактически выданные продавцом разрешения токена.

Подпишите приемник на NEW_MESSAGE в Partner Center или вызовите:

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

Запрос также требует стандартные подписанные параметры, seller access token и shop_cipher. Пример адреса нельзя использовать в production: endpoint должен стабильно контролироваться вашим сервисом.

Чек-лист production-реализации

1. Отделите подтверждение от бизнес-логики

TikTok требует пустой ответ 200 в пределах трех секунд. Проверьте запрос, надежно сохраните минимальную запись, поставьте задачу в очередь и ответьте. Обращения к заказам, AI или CRM выполняйте после подтверждения.

Документация описывает до четырех повторов: через две минуты после первой ошибки, затем через 30 минут, три часа и 12 часов. Храните tts_notification_id и message_id, чтобы повтор задачи не создавал дубликат. Это инженерная защита, а не гарантия, что одно поле заменяет ваш журнал событий.

2. Проверяйте подпись по исходному body

TikTok Shop передает HMAC-SHA256 в header Authorization. Сохраните исходные bytes, рассчитайте ожидаемое значение по официальной инструкции с текущими credentials приложения и сравните за постоянное время. При ошибке верните 401. Не записывайте app secret, seller token, полную подпись или текст покупателя в диагностические логи.

Это не формат UnifyPort X-Device-Timestamp и X-Device-Signature; один verifier для двух протоколов использовать нельзя.

3. Сохраните идентификаторы до нормализации

До преобразования в тикет сохраните shop_id, conversation_id, message_id, index, create_time, роль отправителя, type и is_visible. По документации TikTok больший index означает более новое сообщение, поэтому порядок доставки нельзя считать порядком диалога.

Невидимые или неподдержанные типы направляйте на явную проверку, а не молча превращайте в текст.

4. Сверяйте историю диалога

При разрыве index, перезапуске worker или replay вызовите:

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

Нужен seller.customer_service; максимум page_size равен 10, следующая страница берется по next_page_token. Восстанавливайте порядок по index. Получение истории не ставит отметку о прочтении — отдельный Read Message вызывайте только после фактической обработки агентом.

5. Проведите приемочный тест

На авторизованном тестовом или production-магазине сохраните несекретные подтверждения:

  1. Покупатель начинает или продолжает Shop-диалог.
  2. Endpoint принимает тип 14, проверяет подпись и отвечает 200 за три секунды.
  3. Очередь обновляет нужный диалог по shop_id и conversation_id.
  4. Принудительный повтор worker не создает второе сообщение.
  5. Get Conversation Messages возвращает тот же message_id и закрывает искусственный разрыв index.
  6. Development Kits → Webhook Log в Partner Center показывает успешную доставку.

Где подходит UnifyPort

Официальный TikTok Shop Customer Service API нужен для Shop-идентичности покупателя, авторизации продавца, связанного с заказом саппорта, статусов агентов и официальных ответов. UnifyPort не выдает seller.customer_service и не превращает обычные DM в Shop-диалоги.

Входящие сообщения обычного аккаунта — отдельный сценарий. UnifyPort может доставлять поддерживаемые сообщения TikTok как стандартные события message.received. Перед выбором изучите границу общего TikTok DM API и матрицу поддержки провайдеров; приемник UnifyPort следует отдельному руководству по доставке и подписи.

Ограничения и компромиссы

Официальный Shop API лучше для commerce-поддержки, но требует одобрения scope, авторизации продавца, действующих Shop credentials и поддержки типов сообщений. Webhook не отменяет сверку истории и управление сроком авторизации.

Неофициальный интерфейс не может одобрить Customer Service scope, предоставить заказы Seller Center, воспроизвести функции Shop-агента или гарантировать официальный ответ. Разделяйте оба пути и их credentials.

FAQ

На какое событие подписывать 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.

Это общий webhook для TikTok DM?

Нет. Это одобренная поверхность поддержки покупателей TikTok Shop. У обычных DM и Shop-диалогов разные права, идентичности, данные и правила.

Следующий шаг

Настройте NEW_MESSAGE по официальному руководству TikTok Shop и выполните шесть проверок. Если нужны входящие обычного аккаунта, изучите матрицу поддержки UnifyPort.

Источники

Официальные материалы TikTok Shop проверены 11 августа 2026 года: