ใบตอบรับการเล่นข้อความเสียง 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_iddata.message.idสำหรับup_to_message_iddata.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 ผู้ให้บริการ บัญชี บทสนทนา และผู้ส่งใบตอบรับไว้ด้วย คู่มือใบตอบรับส่งถึงและอ่านแล้วแบบชุด อธิบายการแยกรหัส การรับซ้ำ และใบตอบรับที่มาก่อนเนื้อหาข้อความ ให้เพิ่มการเล่นเป็นหลักฐานแยก ไม่ใช่แทนที่สถานะทั้งหมดด้วยอีเวนต์ที่มาถึงล่าสุด การอ่านปกติที่มาทีหลังต้องไม่ลบหลักฐานการเล่นเดิม
การทดสอบและข้อจำกัด
รายการต่อไปนี้เป็นการทดสอบที่เสนอ ไม่ใช่ผลการทดสอบที่ทำแล้ว:
- เปิดบทสนทนาหรือดาวน์โหลดเสียงแล้วไม่ส่งใบตอบรับการเล่น
- เมื่อเริ่มเล่นจริง ใช้ข้อความที่เลือกกับผู้ส่งต้นฉบับ รวมถึงในกลุ่ม
- ไม่มีเป้าหมายหรือใช้ผิดช่องทางแล้วไม่เข้าสู่วงรอบส่งซ้ำ
- คำขอสำเร็จไม่สร้างหลักฐานว่ารับใบตอบรับการเล่นขึ้นเอง
- ใบตอบรับซ้ำหรือแบบชุดอัปเดตเฉพาะข้อความที่ระบุชัดเจน
- ไม่มี
played_atให้คงสถานะเวลาไม่ทราบ และการอ่านที่มาทีหลังไม่ลบประวัติการเล่น
UnifyPort เป็น unofficial interface ข้อกำหนดนี้เกี่ยวกับการเล่นเสียง WhatsApp เท่านั้น แม้กล่องข้อความร่วมจะมี LINE ด้วย ก็ไม่ควรขยายพฤติกรรมนี้ไปยัง LINE, Telegram หรือสื่อทุกประเภทเพียงเพราะใช้ API ร่วมกัน การได้รับใบตอบรับไม่ใช่สิ่งที่รับประกัน และการเล่นหรืออ่านไม่ได้พิสูจน์ความเข้าใจ ความยินยอม หรือการแก้เคสเสร็จสิ้น
คำถามที่พบบ่อย
message.read แปลว่าเล่นเสียงแล้วหรือไม่?
ดูชื่ออีเวนต์อย่างเดียวไม่ได้ ต้องตรวจ data.event.receipt_type: "played"
ส่งเฉพาะ conversation_id เพื่อรายงานการเล่นได้ไหม?
ไม่ได้ ต้องมีรหัสข้อความและรหัสผู้ส่งต้นฉบับด้วย
played พิสูจน์ว่าฟังจบหรือไม่?
ไม่ใช่ การดำเนินการที่ระบุในเอกสารรายงานการเริ่มเล่น ไม่ใช่การเล่นจบหรือระยะเวลาที่ฟัง
ทำไมคำขอสำเร็จแต่ยังเป็นการอ่านปกติ?
เอกสารระบุว่าช่องทาง WhatsApp รุ่นเก่าอาจประมวลผลเช่นนั้น ต้องตรวจผลการประมวลผลคำขอกับพฤติกรรมใบตอบรับการเล่นแยกกัน
ขั้นตอนถัดไปและแหล่งข้อมูล
เริ่มจากทำกระบวนการเล่นเสียงแบบควบคุมหนึ่งกรณีตามเอกสารการทำเครื่องหมายว่าอ่านแล้ว แล้วตรวจใบตอบรับขาเข้าแยกต่างหากก่อนเปิดใช้ป้ายสถานะการเล่น
ตรวจเอกสารผลิตภัณฑ์เมื่อ 2026-11-20:
เปลี่ยนการเชื่อมต่อข้อความให้เป็น pipeline ผลิตภัณฑ์ที่เสถียร
เริ่มจากการส่งผ่าน API เดียว แล้วส่งข้อความขาเข้าทั้งหมดกลับสู่ระบบธุรกิจของคุณด้วย event มาตรฐาน