ซิงก์รายชื่อสมาชิกกลุ่ม WhatsApp ด้วย group.updated

หากต้องการให้รายชื่อสมาชิกกลุ่ม WhatsApp ในแอปเป็นปัจจุบัน ให้ใช้ webhook group.updated ของ UnifyPort เป็นสัญญาณสำหรับอ่านรายชื่อใหม่ผ่าน List conversation members ประมวลผลทุกรายการใน data.changes[] แต่ไม่ถือว่า ID ผู้เข้าร่วมในเหตุการณ์คือรายชื่อสมาชิกทั้งหมด อัปเดตรายชื่อที่แสดงเมื่ออ่านครบทุกหน้าสำเร็จเท่านั้น และนัดอ่านใหม่หากมีการเปลี่ยนแปลงเข้ามาระหว่างทำงาน

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

• data.actor คือผู้ที่ทำการเปลี่ยนแปลง ส่วน changes[].members[] คือผู้เข้าร่วมที่ได้รับผล
• การเป็นสมาชิกกับการมีบทบาทผู้ดูแลเป็นข้อมูลคนละด้าน
• ผลลัพธ์บางส่วนหรือการอ่านล้มเหลวต้องไม่ลบรายชื่อเดิม
• ขั้นตอนนี้ซิงก์ข้อมูลฝั่งอ่าน ไม่ใช่ระบบจัดการสมาชิกอัตโนมัติ

อ่านการเปลี่ยนแปลงโดยไม่เปลี่ยนให้เป็นคำสั่ง

คู่มือผู้ดูแลกลุ่มของ WhatsApp แยกการแต่งตั้งและการถอดบทบาทผู้ดูแล หน้าจอรายชื่อควรแยกเช่นเดียวกัน เพราะการเปลี่ยนบทบาทไม่ได้หมายถึงการออกจากกลุ่ม

เอกสาร group.updated ของ UnifyPort ระบุ data.conversation, data.actor และ data.changes[] เหตุการณ์เดียวอาจมีหลายการเปลี่ยนแปลง ระบุกลุ่มด้วยบริบท workspace ของตัวรับ, provider, account_id และ data.conversation.id ไม่ใช่ชื่อกลุ่ม

ชนิดการเปลี่ยนแปลง	ผลต่อรายชื่อ	แนวทางที่แนะนำ
member_added / member_removed	สมาชิกอาจเปลี่ยน	นัดรีเฟรชรายชื่อ
promoted / demoted	บทบาทอาจเปลี่ยน	อ่านทั้งตัวตนและบทบาทใหม่
renamed / description_changed / avatar_changed	ข้อมูลกลุ่มเปลี่ยน	ส่งไปยังงานรีเฟรชข้อมูลกลุ่มแยกต่างหาก
dissolved	สถานะวงจรชีวิตกลุ่มเปลี่ยน	ทำเครื่องหมายให้ตรวจสอบ ไม่ลบประวัติที่เก็บไว้โดยอัตโนมัติ

ตรวจทั้งอาร์เรย์ ไม่ใช่แค่ changes[0] หากมีทั้งเปลี่ยนชื่อและเพิ่มสมาชิกในเหตุการณ์เดียว ต้องเรียกงานที่เกี่ยวข้องทั้งสองแบบ เก็บชนิดที่ไม่รู้จักหรือข้อมูลผิดรูปแบบไว้ตรวจสอบแทนการเดาผล

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

สร้างรายชื่อจากการอ่านที่เสร็จครบ

เอกสาร List conversation members ส่งคืน peer_id, display_name, avatar_url และ role บทบาทคือ member, admin และ superadmin โดยค่าหลังหมายถึงเจ้าของหรือผู้สร้างกลุ่ม

ตัวอย่างคำขอฝั่ง backend ต่อไปนี้ใช้ตัวแปรสภาพแวดล้อมจากบัญชีรับส่งข้อความและกลุ่มที่เลือกจริง บทความนี้ไม่ได้รันคำขอดังกล่าว:

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/conversations/members" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "conversation_id=${WHATSAPP_GROUP_ID}" \
  --data-urlencode "type=group" \
  --data-urlencode "limit=50"

เมื่อ data.has_more เป็น true ให้ส่ง data.next_cursor ในพารามิเตอร์ query ชื่อ cursor ของคำขอถัดไป รวบรวมทุกหน้าในพื้นที่พักข้อมูล โดยใช้ peer_id ที่ได้รับเป็นคีย์ เก็บ API key ไว้ที่ backend

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

รักษา ID ตามที่ได้รับ ID ผู้เข้าร่วมจากเหตุการณ์อาจใช้แทน peer_id จากรายชื่อไม่ได้ โดยเฉพาะ endpoint จัดการสมาชิก WhatsApp ต้องใช้ LID สมาชิกที่ส่งคืนมา อย่าสร้างจากหมายเลขโทรศัพท์หรือดัดแปลงสตริงเพื่อถือว่า ID ต่างรูปแบบเป็นตัวเดียวกัน

อย่าให้การรีเฟรชทำสัญญาณรอบถัดไปหาย

ต่อไปนี้เป็นอัลกอริทึมที่แนะนำสำหรับแอป ไม่ใช่ฟิลด์ใหม่ของ UnifyPort หรือการรับประกัน transaction ฝั่งเซิร์ฟเวอร์:

1. รับเหตุการณ์ลงพื้นที่จัดเก็บถาวร สมัครรับ group.updated โดยคง subscription อื่นที่จำเป็น ตรวจลายเซ็นและเวลาให้ตรงตามข้อกำหนดการส่ง webhook ก่อนเชื่อถือเนื้อหา ลายเซ็นใช้ signing_secret คำนวณ HMAC-SHA256 แบบเลขฐานสิบหกจาก X-Device-Timestamp ตามด้วยจุดและ raw body
2. บันทึกความต้องการรีเฟรชแบบ atomic ภายใน transaction เดียว ให้เก็บเหตุการณ์ทั่วไปที่ผ่านการตรวจสอบพร้อมตัดซ้ำด้วย event ID และเพิ่มเลขรุ่นการรีเฟรชภายในของกลุ่มนั้น จากนั้นจึงตอบ 2xx การส่งซ้ำต้องไม่สร้างการกระทำทางธุรกิจใหม่
3. ให้ worker เดียวอ่านกลุ่มในขอบเขตเดียวกัน จดเลขรุ่นปัจจุบัน แล้วอ่านสมาชิกครบทุกหน้า รวมหลายเหตุการณ์ที่ค้างอยู่เป็นการอ่านรอบเดียวได้ ไม่ต้องอ่านใหม่ต่อผู้เข้าร่วมแต่ละคน
4. ตรวจอีกครั้งก่อนเผยแพร่ ใน transaction ที่ประสานกับตัวรับ ให้เปรียบเทียบเลขรุ่นตอนเริ่มกับเลขรุ่นปัจจุบัน หากเปลี่ยนระหว่างอ่านหน้า ให้ถือข้อมูลพักเป็นผลชั่วคราวและนัดรอบใหม่ อย่าระบุว่ารายชื่อเป็นปัจจุบันแล้ว
5. เผยแพร่ผลที่อ่านเสร็จครบ เมื่อทุกหน้าสำเร็จและไม่มีสัญญาณใหม่ค้างอยู่ จึงแทนที่รายชื่อบนหน้าจอและทำเครื่องหมายว่าเลขรุ่นนั้นเสร็จแล้ว เหตุการณ์ที่ commit หลังจากนั้นจะสร้างงานรีเฟรชใหม่

worker ต้องกู้คืนรุ่นที่ยังไม่เสร็จหลังหยุดทำงานได้ แฟล็กในหน่วยความจำอย่างเดียวอาจทำงานรีเฟรชหาย ควรรันตามลำดับหรือมีตัวป้องกันการเขียน เพื่อไม่ให้การอ่านรอบเก่าที่ช้ากว่าเขียนทับผลรอบใหม่

กลไกนี้ตรวจพบเฉพาะเหตุการณ์ที่แอปได้รับระหว่างอ่าน ไม่ได้พิสูจน์ว่าสมาชิกบนต้นทางไม่เปลี่ยน เพราะ API ไม่ได้ระบุ revision ของ snapshot ที่ใช้ร่วมกันระหว่างหน้ากับ webhook แสดงเวลาที่สังเกตข้อมูลล่าสุดแทนการรับรองว่าตรงปัจจุบันทุกขณะ เหตุการณ์ที่มาช้าสามารถกระตุ้นให้อ่านใหม่ โดยไม่ต้องย้อนรายชื่อตามผลต่างเก่า

รับมือเมื่อไม่มีแจ้งเตือนหรืออ่านล้มเหลว

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

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

การอ่านสมาชิกล้มเหลวเพียงอย่างเดียวไม่ได้พิสูจน์ว่ากลุ่มยุบหรือทุกคนออกแล้ว แยกสถานะเข้าถึงไม่ได้และข้อมูลเก่าออกจากรายชื่อว่าง ผู้ขอเข้าร่วมก็เป็นอีกกระบวนการหนึ่ง: group.join_request ไม่ใช่หลักฐานว่าเข้ากลุ่มแล้ว

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

ใช้ changes[].members[] สร้างรายชื่อทั้งกลุ่มได้หรือไม่?

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

data.actor คือคนที่เข้าหรือออกจากกลุ่มหรือไม่?

เป็นคนที่ทำการเปลี่ยนแปลง ดูผู้ได้รับผลใน members[] ที่เกี่ยวข้อง และใช้การอ่านรายชื่อสำหรับสมาชิกปัจจุบัน

ใช้การเปลี่ยนบทบาทเพื่อให้สิทธิ์ในแอปได้ทันทีหรือไม่?

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

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

สร้าง worker ตามเอกสาร List conversation members ควรทดสอบสมาชิกที่อยู่หน้าถัดไป หน้าระหว่างทางล้มเหลว เหตุการณ์ซ้ำ หลายการเปลี่ยนแปลงในเหตุการณ์เดียว การเปลี่ยนระหว่างอ่านหน้า และ worker หยุดก่อนเผยแพร่ นี่เป็นรายการทดสอบที่แนะนำ ไม่ใช่ผลที่ทดสอบแล้ว

ตรวจสอบเอกสารเมื่อ 2026-11-09:

• WhatsApp: การจัดการผู้ดูแลกลุ่ม
• UnifyPort: group.updated
• UnifyPort: List conversation members
• UnifyPort: การส่ง webhook