← Tất cả bài viết
Hướng dẫn

Webhook TikTok Shop Customer Service API: Checklist lên production

Để đưa webhook TikTok Shop Customer Service API lên production, hãy đăng ký NEW_MESSAGE cho shop đã ủy quyền, xác minh từng thông báo, trả 200 trong vòng ba giây và chuyển việc xử lý sang hàng đợi bất đồng bộ. Sau đó phải đối soát bằng Get Conversation Messages vì TikTok nói rõ không nên phụ thuộc hoàn toàn vào webhook. Luồng chính thức này cần custom scope Customer Service đã được duyệt và seller authorization hợp lệ.

Điểm chính

  • Customer Service API chỉ dành cho hội thoại hỗ trợ giữa người mua và người bán TikTok Shop, không phải API chung cho mọi DM của tài khoản TikTok thông thường.
  • Webhook New Message có event type 14; payload gồm tts_notification_id, shop_id, message_id, conversation_id, index, thời gian, loại tin nhắn và người gửi.
  • Endpoint phải dùng HTTPS với TLS 1.2+, xác minh chữ ký Authorization và trả 200 trong ba giây.
  • TikTok sẽ retry khi giao thất bại, vì vậy consumer phải idempotent; luồng thông báo vẫn có thể thiếu dữ liệu.
  • Dùng GET /customer_service/202309/conversations/{conversation_id}/messages để bù khoảng trống; API này không tự đánh dấu đã đọc.

Thiết lập webhook TikTok Shop Customer Service API

Bài này bắt đầu sau bước xét duyệt. Nếu app chưa có custom scope Customer Service, hãy dùng checklist điều kiện phê duyệt trước. TikTok ghi seller.customer_service cho API hội thoại, còn Update Shop Webhook yêu cầu seller.authorization.info. Trước khi kết luận lỗi mạng, hãy kiểm tra cả scope đã bật cho app và quyền thực tế của seller token.

Đăng ký NEW_MESSAGE trong Partner Center hoặc gọi:

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

Request còn cần các tham số ký thông thường, seller access token và shop_cipher. Không dùng địa chỉ ví dụ cho production; endpoint phải thuộc quyền kiểm soát ổn định của dịch vụ.

Checklist triển khai production

1. Tách acknowledgement khỏi xử lý nghiệp vụ

TikTok yêu cầu body rỗng và status 200 trong ba giây. Receiver chỉ nên xác minh, lưu tối thiểu một bản ghi bền vững, đưa job vào queue rồi phản hồi. Không gọi hệ thống đơn hàng, AI hay CRM trước khi trả lời.

TikTok mô tả tối đa bốn lần retry: hai phút sau lần lỗi đầu, rồi lần lượt sau 30 phút, ba giờ và 12 giờ. Lưu tts_notification_id và message_id để chạy lại không tạo bản sao. Đây là biện pháp kỹ thuật, không phải cam kết rằng một field có thể thay thế event ledger của bạn.

2. Xác minh chữ ký trên raw body

TikTok Shop đặt chữ ký HMAC-SHA256 trong header Authorization. Giữ nguyên raw bytes, tính giá trị mong đợi bằng credentials hiện tại đúng theo hướng dẫn chính thức và so sánh constant-time. Trả 401 khi sai; không log app secret, seller token, toàn bộ chữ ký hoặc nội dung tin nhắn của người mua.

Đây không phải định dạng X-Device-Timestamp và X-Device-Signature của UnifyPort. Không dùng chung verifier cho hai giao thức.

3. Giữ identifier trước khi chuẩn hóa

Trước khi ánh xạ sang ticket, lưu shop_id, conversation_id, message_id, index, create_time, vai trò người gửi, type và is_visible. Theo TikTok, index lớn hơn là tin nhắn mới hơn; thứ tự webhook đến không nhất thiết là thứ tự hội thoại.

Đưa loại tin nhắn ẩn hoặc chưa hỗ trợ vào trạng thái review rõ ràng thay vì âm thầm chuyển thành text.

4. Đối soát lịch sử hội thoại

Khi có khoảng trống index, worker khởi động lại hoặc cần replay, gọi:

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

Endpoint yêu cầu seller.customer_service; page_size tối đa 10 và trang kế tiếp dùng next_page_token. Khôi phục thứ tự theo index. Việc lấy lịch sử không đánh dấu đã đọc; chỉ gọi Read Message riêng khi agent thực sự xử lý tin nhắn.

5. Chạy kiểm thử nghiệm thu

Với development shop hoặc production shop đã ủy quyền, lưu bằng chứng không chứa bí mật:

  1. Người mua bắt đầu hoặc tiếp tục hội thoại hỗ trợ Shop.
  2. Endpoint nhận type 14, xác minh chữ ký và trả 200 trong ba giây.
  3. Queue cập nhật đúng hội thoại bằng shop_id và conversation_id.
  4. Retry worker có chủ đích không tạo tin nhắn trùng.
  5. Get Conversation Messages trả cùng message_id và bù được khoảng trống index thử nghiệm.
  6. Development Kits → Webhook Log trong Partner Center hiển thị giao thành công.

UnifyPort phù hợp ở đâu

Hãy dùng TikTok Shop Customer Service API khi cần danh tính người mua Shop, seller authorization, hỗ trợ gắn với đơn hàng, trạng thái agent hoặc phản hồi Shop chính thức. UnifyPort không cấp seller.customer_service và không biến DM thông thường thành hội thoại Shop.

Inbound của tài khoản thường là một luồng khác. UnifyPort có thể giao các tin nhắn TikTok được hỗ trợ dưới dạng sự kiện message.received. Hãy xem ranh giới TikTok DM API chung và ma trận hỗ trợ provider; receiver của UnifyPort dùng hướng dẫn giao webhook và chữ ký riêng.

Giới hạn và đánh đổi

Shop API chính thức phù hợp nhất cho hỗ trợ thương mại nhưng cần duyệt custom scope, seller authorization, Shop credentials hợp lệ và xử lý nhiều message type. Webhook không loại bỏ nhu cầu đối soát lịch sử hoặc quản lý vòng đời ủy quyền.

Giao diện không chính thức không thể duyệt Customer Service scope, cung cấp dữ liệu đơn hàng Seller Center, tái tạo chức năng agent Shop hoặc bảo đảm reply chính thức. Hãy tách biệt hai luồng và credentials.

FAQ

Webhook Customer Service API nên đăng ký event nào?

Dùng NEW_MESSAGE để nhận tin nhắn; numeric type trong thông báo là 14. NEW_CONVERSATION là event riêng.

Webhook phải phản hồi nhanh đến mức nào?

TikTok yêu cầu 200 với body rỗng trong ba giây. Xác minh, đưa vào queue bền vững rồi phản hồi ngay.

Xử lý thông báo trùng như thế nào?

Lưu tts_notification_id và message_id, ghi idempotent, đồng thời giữ conversation_id và index để phát hiện khoảng trống thứ tự.

Webhook có thay Get Conversation Messages không?

Không. TikTok khuyến cáo không phụ thuộc hoàn toàn vào thông báo. Dùng history API khi thiếu, sai thứ tự hoặc worker ngừng hoạt động.

Đây có phải webhook chung cho TikTok DM không?

Không. Đây là bề mặt hỗ trợ người mua TikTok Shop đã được duyệt; DM thường có quyền, danh tính, dữ liệu và quy tắc khác.

Bước tiếp theo

Thiết lập NEW_MESSAGE theo hướng dẫn webhook chính thức rồi hoàn thành sáu bước nghiệm thu. Nếu cần inbound của tài khoản thường, xem ma trận hỗ trợ UnifyPort.

Nguồn

Các tài liệu TikTok Shop chính thức được kiểm tra ngày 11/08/2026: