← บทความทั้งหมด
บทช่วยสอน

Webhook TikTok Shop Customer Service API: เช็กลิสต์ก่อนขึ้น Production

การนำ webhook ของ TikTok Shop Customer Service API ขึ้น production ต้องสมัคร NEW_MESSAGE ให้ร้านค้าที่อนุญาตแล้ว ตรวจสอบทุก notification ตอบ 200 ภายในสามวินาที และส่งงานประมวลผลเข้า queue แบบ asynchronous จากนั้นต้องกระทบยอดด้วย Get Conversation Messages เพราะ TikTok ระบุชัดว่าไม่ควรพึ่ง webhook เพียงอย่างเดียว เส้นทางทางการนี้ต้องมี custom scope Customer Service ที่ผ่านอนุมัติและ seller authorization ที่ยังใช้งานได้

ประเด็นสำคัญ

  • Customer Service API ครอบคลุมบทสนทนาระหว่างผู้ซื้อกับผู้ขายใน TikTok Shop ไม่ใช่ API รวมสำหรับ DM ทั้งหมดของบัญชี TikTok ทั่วไป
  • New Message webhook ใช้ event type 14 และมี tts_notification_id, shop_id, message_id, conversation_id, index, เวลา ประเภทข้อความ และผู้ส่ง
  • Endpoint ต้องเป็น HTTPS ที่ใช้ TLS 1.2 ขึ้นไป ตรวจลายเซ็น Authorization และตอบ 200 ภายในสามวินาที
  • TikTok จะ retry เมื่อส่งไม่สำเร็จ จึงต้องประมวลผลแบบ idempotent และเตรียมรับกรณี notification ไม่ครบ
  • ใช้ GET /customer_service/202309/conversations/{conversation_id}/messages เพื่อเติมช่องว่าง โดยการดึงข้อมูลนี้ไม่ทำเครื่องหมายว่าอ่านแล้ว

วิธีตั้งค่า TikTok Shop Customer Service API webhook

บทความนี้เริ่มหลังผ่านการอนุมัติสิทธิ์ หาก app ยังไม่มี custom scope Customer Service ให้เริ่มจากเช็กลิสต์คุณสมบัติการสมัคร ก่อน TikTok ระบุ seller.customer_service สำหรับ conversation API ส่วน Update Shop Webhook ต้องใช้ seller.authorization.info ควรตรวจทั้ง scope ที่เปิดใน app และสิทธิ์จริงใน seller token ก่อนสรุปว่าเป็นปัญหา network

ตั้ง NEW_MESSAGE ใน Partner Center หรือเรียก:

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

Request ยังต้องมีพารามิเตอร์ลายเซ็นตามปกติ seller access token และ shop_cipher URL ตัวอย่างไม่ควรใช้จริง; production endpoint ต้องอยู่ภายใต้การควบคุมของบริการคุณ

เช็กลิสต์การติดตั้ง Production

1. แยกการตอบรับออกจาก business logic

TikTok ต้องการ 200 ที่มี body ว่างภายในสามวินาที Receiver ควรตรวจ request บันทึกข้อมูลขั้นต่ำอย่างทนทาน ใส่งานลง queue แล้วตอบทันที อย่าเรียกระบบ order, AI หรือ CRM ก่อนตอบ

เอกสารระบุ retry สูงสุดสี่ครั้ง: สองนาทีหลังครั้งแรกไม่สำเร็จ แล้วตามด้วย 30 นาที สามชั่วโมง และ 12 ชั่วโมง เก็บ tts_notification_id กับ message_id เพื่อให้รันซ้ำไม่สร้างข้อมูลซ้ำ นี่คือมาตรการทางวิศวกรรม ไม่ใช่การรับประกันว่า field ใด field หนึ่งแทน event ledger ของคุณได้

2. ตรวจลายเซ็นจาก raw body

TikTok Shop ใส่ลายเซ็น HMAC-SHA256 ใน header Authorization เก็บ raw bytes คำนวณค่าที่คาดหวังด้วย credentials ปัจจุบันตามคู่มือทางการ และเปรียบเทียบแบบ constant-time ส่ง 401 เมื่อไม่ผ่าน และห้าม log app secret, seller token, ลายเซ็นเต็ม หรือเนื้อหาข้อความของผู้ซื้อ

รูปแบบนี้ต่างจาก X-Device-Timestamp และ X-Device-Signature ของ UnifyPort ห้ามใช้ verifier เดียวกันกับสอง protocol

3. เก็บ identifier ก่อน normalize

ก่อนแปลงเป็น ticket ให้เก็บ shop_id, conversation_id, message_id, index, create_time, sender role, type และ is_visible TikTok ระบุว่า index ที่มากกว่าคือข้อความใหม่กว่า จึงห้ามถือว่าลำดับมาถึงเท่ากับลำดับข้อความ

ส่งประเภทข้อความที่มองไม่เห็นหรือยังไม่รองรับไปยังสถานะ review ที่ชัดเจน แทนการแปลงเป็น text แบบเงียบ ๆ

4. กระทบยอดประวัติ conversation

เมื่อพบ index ขาด worker restart หรือต้อง replay ให้เรียก:

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

Endpoint ต้องใช้ seller.customer_service; page_size สูงสุด 10 และหน้าถัดไปใช้ next_page_token เรียงใหม่ตาม index การดึงประวัติไม่ทำเครื่องหมายอ่านแล้ว ให้เรียก Read Message แยกเมื่อ agent ใช้ข้อความจริงเท่านั้น

5. ทดสอบรับรองระบบจริง

ใช้ development shop หรือ production shop ที่อนุญาตแล้ว และเก็บหลักฐานที่ไม่มีข้อมูลลับ:

  1. ผู้ซื้อเริ่มหรือคุยต่อใน Shop customer service
  2. Endpoint รับ type 14 ตรวจลายเซ็น และตอบ 200 ภายในสามวินาที
  3. Queue อัปเดต conversation ถูกต้องด้วย shop_id และ conversation_id
  4. บังคับ retry worker แล้วไม่เกิดข้อความซ้ำ
  5. Get Conversation Messages คืน message_id เดียวกันและเติม index gap ที่ทดสอบไว้ได้
  6. Development Kits → Webhook Log ใน Partner Center แสดงว่าส่งสำเร็จ

UnifyPort เหมาะกับส่วนใด

ใช้ TikTok Shop Customer Service API เมื่อจำเป็นต้องมีตัวตนผู้ซื้อ Shop, seller authorization, support ที่เชื่อม order, สถานะ agent หรือการตอบผ่าน Shop อย่างเป็นทางการ UnifyPort ไม่ได้ให้ seller.customer_service และไม่เปลี่ยน DM ทั่วไปเป็น Shop conversation

Inbound ของบัญชีทั่วไปเป็นอีกเส้นทางหนึ่ง UnifyPort สามารถส่งข้อความ TikTok ที่รองรับเป็น event มาตรฐาน message.received ได้ โปรดอ่านขอบเขตของ TikTok DM API ทั่วไปและตาราง provider message support โดย receiver ของ UnifyPort ใช้คู่มือ webhook delivery และ signatureแยกต่างหาก

ข้อจำกัดและสิ่งที่ต้องแลก

Shop API ทางการเหมาะที่สุดกับ commerce support แต่ต้องผ่านอนุมัติ custom scope มี seller authorization, Shop credentials ที่ถูกต้อง และรองรับ message type หลายแบบ Webhook ไม่ได้แทนการกระทบยอดหรือการจัดการวงจร authorization

อินเทอร์เฟซที่ไม่เป็นทางการไม่สามารถอนุมัติ Customer Service scope ให้ข้อมูล order ของ Seller Center ทำซ้ำฟีเจอร์ agent ของ Shop หรือรับประกันการตอบแบบทางการได้ ควรแยกสองระบบและ credentials ออกจากกัน

FAQ

Customer Service API webhook ควรสมัคร event ใด?

ใช้ NEW_MESSAGE สำหรับข้อความเข้า โดย numeric type คือ 14 ส่วน NEW_CONVERSATION เป็นอีก event หนึ่ง

Webhook ต้องตอบเร็วแค่ไหน?

TikTok กำหนดให้ตอบ 200 พร้อม body ว่างภายในสามวินาที ตรวจสอบและนำเข้า queue อย่างทนทานแล้วตอบทันที

จัดการ notification ซ้ำอย่างไร?

เก็บ tts_notification_id กับ message_id เขียนข้อมูลแบบ idempotent และเก็บ conversation_id กับ index เพื่อตรวจทั้งข้อมูลซ้ำและช่องว่างของลำดับ

Webhook แทน Get Conversation Messages ได้หรือไม่?

ไม่ได้ TikTok แนะนำไม่ให้พึ่ง notification ทั้งหมด ต้องกระทบยอดเมื่อข้อมูลขาด ลำดับผิด หรือ worker หยุดทำงาน

นี่คือ webhook สำหรับ TikTok DM ทั่วไปหรือไม่?

ไม่ใช่ นี่คือฟังก์ชัน support ผู้ซื้อ TikTok Shop ที่ผ่านอนุมัติแล้ว DM ทั่วไปมีสิทธิ์ ตัวตน ข้อมูล และกฎต่างกัน

ขั้นตอนถัดไป

ตั้ง NEW_MESSAGE ตามคู่มือ webhook ทางการของ TikTok Shop แล้วทำการทดสอบหกขั้นตอนข้างต้น หากต้องการ inbound ของบัญชีทั่วไป ให้ดูตารางรองรับของ UnifyPort

แหล่งข้อมูล

ตรวจสอบเอกสารทางการของ TikTok Shop ต่อไปนี้เมื่อ 11 สิงหาคม 2026: