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

ใบตอบรับการเล่นข้อความเสียง WhatsApp: played ต่างจากอ่านแล้วอย่างไร

หากต้องการรายงานว่าข้อความเสียง WhatsApp เริ่มเล่นแล้ว ผ่าน UnifyPort ให้เรียกการทำเครื่องหมายบทสนทนาว่าอ่านแล้ว พร้อม receipt_type: "played" รหัสข้อความ และรหัสผู้ส่งต้นฉบับ ส่วนการตรวจใบตอบรับการเล่นที่เข้ามา ให้ดู data.event.receipt_type ภายใน message.read สถานะอ่านแล้วตามปกติไม่ใช่หลักฐานว่าเล่นเสียงแล้ว และการเริ่มเล่นก็ไม่ใช่หลักฐานว่าฟังจนจบ

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

  • การเล่นใช้การดำเนินการอ่านเดิมและอีเวนต์ message.read ไม่ใช่ endpoint หรือชื่ออีเวนต์ใหม่
  • การส่งใบตอบรับการเล่นกับการรับใบตอบรับเป็นหลักฐานคนละทิศทาง
  • data.ok: true ยืนยันว่าประมวลผลคำขอแล้ว แต่ช่องทาง WhatsApp รุ่นเก่าอาจประมวลผลเป็นการอ่านปกติ
  • เก็บหลักฐานการเล่นแยกจากสถานะอ่านของบทสนทนา การปิดเคส และความยาวเสียง

แยกก่อนว่ากำลังจัดการฝั่งใด

เอกสารการทำเครื่องหมายว่าอ่านแล้ว อธิบายการรายงานว่าเสียง WhatsApp เริ่มเล่น ส่วนเอกสารอีเวนต์มาตรฐาน กำหนดให้ใบตอบรับการเล่นที่เข้ามาอยู่ใน message.read

สถานการณ์การจัดการที่แนะนำสิ่งที่ห้ามสรุป
เจ้าหน้าที่เปิดบทสนทนาใช้นโยบายอ่านแล้วของกล่องข้อความตามปกติเล่นข้อความเสียงแล้ว
ข้อความเสียงขาเข้าที่เลือกเริ่มเล่นจริงพิจารณาส่ง played สำหรับข้อความนั้นเจ้าหน้าที่ฟังจนจบแล้ว
ได้รับใบตอบรับการเล่นของเสียงที่ส่งออกบันทึกตามข้อความและผู้ส่งใบตอบรับสมาชิกทุกคนฟังแล้ว หรือเคสจบแล้ว
ไม่ได้รับใบตอบรับการเล่นคงสถานะยังไม่ยืนยันอีกฝ่ายไม่ได้เล่นแน่นอน

สัญญาณเริ่มเล่นจากตัวเล่นในแอปเป็นจุดกระตุ้นที่แนะนำ ไม่ใช่ฟิลด์ใหม่ของ UnifyPort อย่าส่งใบตอบรับเพียงเพราะดาวน์โหลดไฟล์ แสดงรูปคลื่นเสียง หรือกดปุ่มเล่นแต่เสียงไม่เริ่ม ส่วนงานคิวทั่วไปดูได้ในแนวทางซิงก์อ่านแล้วและยังไม่อ่านในกล่องข้อความร่วม

รายงานการเล่นของข้อความที่เลือก

เรียก POST /v1/accounts/{account_id}/conversations/read จาก backend ด้วย X-Api-Key และอย่าส่งคีย์ไปยังเบราว์เซอร์ เก็บตัวระบุจากอีเวนต์ขาเข้าเดียวกันไว้ด้วยกัน:

  • account_id ที่ระดับบนสุด
  • data.conversation.id สำหรับ conversation_id
  • data.message.id สำหรับ up_to_message_id
  • data.sender.id สำหรับ up_to_message_sender_id

ผู้ส่งหมายถึงผู้เขียนข้อความต้นฉบับ ไม่ใช่เจ้าหน้าที่ที่เล่นเสียง และในกลุ่มก็ไม่ใช่รหัสกลุ่ม หลังเสียงเริ่มเล่น อย่าอ่านค่าจากตัวเลือก “ข้อความล่าสุด” ที่อาจเปลี่ยนไปแล้ว

ตัวอย่างเนื้อหาคำขอต่อไปนี้ใช้รหัสสมมติ ไม่ใช่ข้อมูลลูกค้าที่บันทึกมาจริง:

{
  "conversation_id": "100000000000002@lid",
  "up_to_message_id": "VOICE_EXAMPLE_001",
  "up_to_message_sender_id": "100000000000002@lid",
  "receipt_type": "played"
}

การรายงานการเล่นต้องมีฟิลด์เป้าหมายข้อความทั้งสองและต้องไม่ว่าง เอกสารระบุว่า receipt type ที่ไม่รู้จัก การใช้ played บนช่องทางอื่น หรือการไม่มีเป้าหมายการเล่น จะได้ 400 invalid_request พร้อมรหัสตัวเลข 10000 ให้แก้อินพุตหรือช่องทางแทนการส่งซ้ำอัตโนมัติ

หากละ receipt type หรือส่งค่าว่าง จะใช้ความหมายแบบ read ปกติ จึงไม่ใช่สิ่งทดแทนการระบุการเล่นโดยตรง การอ่าน WhatsApp ปกติอาจละฟิลด์เป้าหมายทั้งสองเพื่อทำเครื่องหมายทั้งบทสนทนาได้ แต่ห้ามใช้ทางลัดนี้กับคำขอเล่นเสียง

ตีความผลคำขออย่างระมัดระวัง

data.ok: true แปลว่าประมวลผลคำขอสำเร็จ ไม่ได้ยืนยันการทำงานของใบตอบรับการเล่นตั้งแต่ต้นจนจบ เอกสารเตือนชัดเจนว่าช่องทาง WhatsApp รุ่นเก่าอาจจัดการ played เป็นการอ่านปกติ และไม่ได้ระบุเลขเวอร์ชันขั้นต่ำไว้ที่นี่ จึงไม่ควรเติมเลขขึ้นเอง

แอปควรเก็บเป้าหมายที่เลือก การดำเนินการที่ลอง และผลที่สังเกตได้เป็นบันทึกภายใน ไม่ใช่ฟิลด์ API เพิ่มเติม HTTP timeout หมายถึงผลยังไม่แน่นอน ไม่ใช่เหตุให้สรุปล้มเหลวหรือส่งซ้ำโดยไม่ตรวจสอบ ทดสอบด้วยบัญชีรับส่งข้อความที่คุณควบคุมก่อนแสดงข้อความสำเร็จที่ยืนยันมากกว่า “ประมวลผลคำขอแล้ว”

ตรวจ played ภายใน message.read

เอกสาร message.read ใช้ data.event.receipt_type: "played" สำหรับใบตอบรับการเล่น เวลาที่ผู้ให้บริการรายงานอาจอยู่ใน data.message.played_at หากไม่มีค่านี้ อย่าแทนด้วย read_at เวลาที่ Webhook มาถึง หรือความยาวของไฟล์เสียง

ฟังก์ชันสั้นนี้ใช้กับอีเวนต์ที่ผ่านการยืนยันแหล่งที่มาและตรวจโครงสร้างแล้วเท่านั้น ไม่ได้ตรวจลายเซ็นหรือบันทึกข้อมูล:

function isWhatsAppPlaybackReceipt(event) {
  return event.provider === 'whatsapp' &&
    event.type === 'message.read' &&
    event.data?.event?.receipt_type === 'played';
}

สมัครรับ message.read โดยคงรายการที่ต้องรับเดิมไว้ ทำตามข้อกำหนดการส่ง Webhook: ตั้ง signing_secret ตรวจ HMAC-SHA256 จาก X-Device-Timestamp ตามด้วยจุดและ body ดิบ ตรวจความใหม่ของ timestamp และเก็บข้อมูลที่ยืนยันแล้วอย่างถาวรก่อนตอบ 2xx

ใบตอบรับแบบชุดอาจมี data.message.ids มิฉะนั้นใช้ data.message.id เก็บขอบเขต workspace ผู้ให้บริการ บัญชี บทสนทนา และผู้ส่งใบตอบรับไว้ด้วย คู่มือใบตอบรับส่งถึงและอ่านแล้วแบบชุด อธิบายการแยกรหัส การรับซ้ำ และใบตอบรับที่มาก่อนเนื้อหาข้อความ ให้เพิ่มการเล่นเป็นหลักฐานแยก ไม่ใช่แทนที่สถานะทั้งหมดด้วยอีเวนต์ที่มาถึงล่าสุด การอ่านปกติที่มาทีหลังต้องไม่ลบหลักฐานการเล่นเดิม

การทดสอบและข้อจำกัด

รายการต่อไปนี้เป็นการทดสอบที่เสนอ ไม่ใช่ผลการทดสอบที่ทำแล้ว:

  1. เปิดบทสนทนาหรือดาวน์โหลดเสียงแล้วไม่ส่งใบตอบรับการเล่น
  2. เมื่อเริ่มเล่นจริง ใช้ข้อความที่เลือกกับผู้ส่งต้นฉบับ รวมถึงในกลุ่ม
  3. ไม่มีเป้าหมายหรือใช้ผิดช่องทางแล้วไม่เข้าสู่วงรอบส่งซ้ำ
  4. คำขอสำเร็จไม่สร้างหลักฐานว่ารับใบตอบรับการเล่นขึ้นเอง
  5. ใบตอบรับซ้ำหรือแบบชุดอัปเดตเฉพาะข้อความที่ระบุชัดเจน
  6. ไม่มี played_at ให้คงสถานะเวลาไม่ทราบ และการอ่านที่มาทีหลังไม่ลบประวัติการเล่น

UnifyPort เป็น unofficial interface ข้อกำหนดนี้เกี่ยวกับการเล่นเสียง WhatsApp เท่านั้น แม้กล่องข้อความร่วมจะมี LINE ด้วย ก็ไม่ควรขยายพฤติกรรมนี้ไปยัง LINE, Telegram หรือสื่อทุกประเภทเพียงเพราะใช้ API ร่วมกัน การได้รับใบตอบรับไม่ใช่สิ่งที่รับประกัน และการเล่นหรืออ่านไม่ได้พิสูจน์ความเข้าใจ ความยินยอม หรือการแก้เคสเสร็จสิ้น

คำถามที่พบบ่อย

message.read แปลว่าเล่นเสียงแล้วหรือไม่?

ดูชื่ออีเวนต์อย่างเดียวไม่ได้ ต้องตรวจ data.event.receipt_type: "played"

ส่งเฉพาะ conversation_id เพื่อรายงานการเล่นได้ไหม?

ไม่ได้ ต้องมีรหัสข้อความและรหัสผู้ส่งต้นฉบับด้วย

played พิสูจน์ว่าฟังจบหรือไม่?

ไม่ใช่ การดำเนินการที่ระบุในเอกสารรายงานการเริ่มเล่น ไม่ใช่การเล่นจบหรือระยะเวลาที่ฟัง

ทำไมคำขอสำเร็จแต่ยังเป็นการอ่านปกติ?

เอกสารระบุว่าช่องทาง WhatsApp รุ่นเก่าอาจประมวลผลเช่นนั้น ต้องตรวจผลการประมวลผลคำขอกับพฤติกรรมใบตอบรับการเล่นแยกกัน

ขั้นตอนถัดไปและแหล่งข้อมูล

เริ่มจากทำกระบวนการเล่นเสียงแบบควบคุมหนึ่งกรณีตามเอกสารการทำเครื่องหมายว่าอ่านแล้ว แล้วตรวจใบตอบรับขาเข้าแยกต่างหากก่อนเปิดใช้ป้ายสถานะการเล่น

ตรวจเอกสารผลิตภัณฑ์เมื่อ 2026-11-20:

UnifyPort API

เปลี่ยนการเชื่อมต่อข้อความให้เป็น pipeline ผลิตภัณฑ์ที่เสถียร

เริ่มจากการส่งผ่าน API เดียว แล้วส่งข้อความขาเข้าทั้งหมดกลับสู่ระบบธุรกิจของคุณด้วย event มาตรฐาน