ซิงก์ชื่อบัญชี WhatsApp ด้วย account.profile.updated

หากต้องการซิงก์ ชื่อของบัญชี WhatsApp ที่เชื่อมต่อเอง ในแอป ให้ประมวลผลอีเวนต์ account.profile.updated ของ UnifyPort และอ่าน data.profile.display_name ซึ่งเลือกชื่อธุรกิจก่อน แล้วจึงใช้ชื่อ push เมื่อไม่มีชื่อธุรกิจ สิ่งที่ควรอัปเดตคือส่วนแสดงโปรไฟล์บัญชี ไม่ใช่ผู้ติดต่อของลูกค้า ป้ายชื่อภายใน หรือสถานะการเชื่อมต่อ เอกสารระบุว่าอีเวนต์นี้เกิดจากอีเวนต์ชื่อของ WhatsApp ไม่ใช่การแจ้งเปลี่ยนโปรไฟล์ที่ใช้ได้กับทุกช่องทาง

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

• ระบุบัญชีด้วย workspace, provider และ account_id ไม่ใช่ชื่อที่แสดง
• แยก name ในการตั้งค่าบัญชีออกจากชื่อสาธารณะบนแพลตฟอร์ม
• full_sync บอกแหล่งที่มาของโปรไฟล์ ไม่ได้ยืนยันว่ากู้คืนประวัติข้อความครบแล้ว
• การแจ้งโปรไฟล์ไม่ใช่หลักฐานว่าการยืนยันตัวตนสำเร็จหรือการเชื่อมต่อกำลังทำงาน

เลือกก่อนว่าหน้าจอควรแสดงชื่อใด

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

ค่าหรืออีเวนต์	ความหมาย	ตำแหน่งที่แนะนำ
name ในการตั้งค่าบัญชี	ป้ายชื่อที่จัดการผ่านการตั้งค่า	ตัวเลือกบัญชีภายใน
data.profile.display_name	ชื่อสาธารณะจากโปรไฟล์แพลตฟอร์ม	บรรทัดชื่อช่องทางแยกต่างหาก
data.profile.business_name / push_name	องค์ประกอบชื่อในเอกสารอีเวนต์	รายละเอียดโปรไฟล์เพิ่มเติม
contact.updated	ชื่อผู้ติดต่อในสมุดรายชื่อ	มุมมองข้อมูลลูกค้า
account.status.updated	สถานะการยืนยันตัวตนหรือ runtime	มุมมองสถานะการเชื่อมต่อ

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

เอกสาร Get account ส่งคืนการตั้งค่าและ provider_profile แยกกัน จึงใช้เป็นข้อมูลเริ่มต้นของหน้าจอได้ หากไม่มีชื่อสาธารณะ ให้แสดงว่ายังไม่มีข้อมูล อย่านำป้ายชื่อภายในมาแสดงเสมือนเป็นชื่อที่ได้รับจากแพลตฟอร์ม

อ่าน account.profile.updated ให้ตรงขอบเขต

ตัวอย่างต่อไปนี้ใช้โครงสร้างจาก เอกสารอีเวนต์ ค่าและชื่อเป็นตัวอย่างในเอกสาร ไม่ใช่ข้อมูลจากลูกค้าจริง

{
  "id": "evt_profile_7e91d2c4",
  "type": "account.profile.updated",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-08-28T09:51:51Z",
  "data": {
    "account": { "provider_account_ref": "provider_account_example" },
    "profile": {
      "display_name": "Example Business",
      "business_name": "Example Business",
      "push_name": "Example Account"
    },
    "event": {
      "kind": "account_profile_updated",
      "source": "self_rename"
    }
  }
}

ใช้ display_name ที่ได้รับ แทนการสร้างกฎลำดับความสำคัญอีกชุดหนึ่ง หากชื่อธุรกิจยังมีลำดับความสำคัญสูงกว่า การเปลี่ยน push_name อาจไม่ทำให้ชื่อบนหน้าจอเปลี่ยน

เอกสารระบุค่า data.event.source ไว้สองแบบ:

• self_rename: บัญชีที่เชื่อมต่อเปลี่ยนชื่อของตัวเอง
• full_sync: โปรไฟล์มาจากภาพข้อมูลของการซิงก์แบบเต็ม

ทั้งสองค่าไม่ได้ระบุบุคคลที่ลงมือแก้ไข อย่าสร้างบันทึกตรวจสอบที่ระบุผู้ปฏิบัติงานโดยไม่มีหลักฐาน และ full_sync ไม่ได้ยืนยันว่าข้อความ ผู้ติดต่อ รูปโปรไฟล์ หรือข้อมูลบัญชีทั้งหมดซิงก์ครบแล้ว

สร้างมุมมองโปรไฟล์บัญชีแยกต่างหาก

ลำดับการพัฒนาที่แนะนำ:

1. สมัครรับอีเวนต์ก่อนพึ่งพาการอัปเดต เพิ่ม account.profile.updated ในชุดอีเวนต์ที่ต้องใช้ โดยรักษาการสมัครรับเดิมและการตั้งค่าลายเซ็นไว้ คู่มือตัวกรองอีเวนต์ อธิบายรายการแบบระบุชื่อกับ wildcard
2. ตรวจสอบแล้วบันทึกถาวร ทำตาม ข้อกำหนดการส่ง Webhook ใช้ signing_secret ตรวจสอบ HMAC-SHA256 แบบ hex ของ X-Device-Timestamp ตามด้วยจุดและ body ต้นฉบับ พร้อมตรวจสอบความใหม่ของ timestamp บันทึกอีเวนต์ที่ผ่านการยืนยันอย่างคงทนก่อนตอบ 2xx
3. ค้นหาบัญชีเดิม ใช้บริบท workspace ของตัวรับ ร่วมกับ provider และ account_id ใน envelope ชื่อใหม่ต้องไม่สร้างบัญชีที่สองหรือย้ายบทสนทนาไปบัญชีอื่น
4. อัปเดตเฉพาะการแสดงโปรไฟล์ ไม่เปลี่ยนป้ายชื่อภายใน ชื่อลูกค้า การยืนยันตัวตน หรือ runtime แสดงชื่อเป็นข้อความ ไม่ใช่ HTML
5. บันทึกแหล่งที่มาในแอป เก็บ ID อีเวนต์ เวลาเกิด และ source คู่กับข้อมูลแสดงผล นี่คือการออกแบบข้อมูลภายใน ไม่ใช่ฟิลด์ API ใหม่

JavaScript นี้ดึงชื่อจากอีเวนต์ที่ผ่านการยืนยันแล้วเท่านั้น ไม่รวมฐานข้อมูล การจัดลำดับ หรือเซิร์ฟเวอร์รับ Webhook แบบสมบูรณ์

function profileNameCandidate(event) {
  if (event.type !== 'account.profile.updated' ||
      event.provider !== 'whatsapp') return null;
  if (typeof event.account_id !== 'string' || !event.account_id) {
    throw new Error('Missing account identity');
  }
  const name = event.data?.profile?.display_name;
  if (typeof name !== 'string') {
    throw new Error('Profile display name needs review');
  }
  return { accountId: event.account_id, displayName: name };
}

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

จัดการอีเวนต์เก่าและการอ่านครั้งแรก

ตัดข้อมูลซ้ำของการส่งอีเวนต์ทั่วไปซ้ำด้วย ID อีเวนต์ ลำดับการส่งไม่ได้รับการรับประกัน จึงควรใช้ occurred_at และใช้ ID เป็นเกณฑ์ตัดสินที่แน่นอนเมื่อเวลาเท่ากัน บันทึกการประมวลผลและการอัปเดตมุมมองร่วมกันในการ commit เดียว

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

UnifyPort เป็นอินเทอร์เฟซที่ไม่เป็นทางการ อีเวนต์นี้ไม่ใช่คำสั่งเปลี่ยนโปรไฟล์บนแพลตฟอร์ม ไม่ใช่คลังข้อมูลครบถ้วน และไม่รับประกันการส่งข้อมูลที่พลาดซ้ำ หากใช้ LINE ร่วมกับ WhatsApp ในหน้าจอเดียวกัน อย่าสรุปว่า LINE รองรับอีเวนต์นี้เพียงเพราะ envelope เหมือนกัน ข้อควรระวังเดียวกันใช้กับ Zalo, Telegram และ whatsapp-protocol

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

ทำไม push_name เปลี่ยน แต่ display_name เหมือนเดิม?

เอกสารกำหนดให้ BusinessName มาก่อน PushName ตรวจสอบองค์ประกอบชื่อที่ได้รับก่อนสรุปว่าการอัปเดตล้มเหลว

full_sync หมายถึงประวัติข้อความครบแล้วหรือไม่?

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

ควร PATCH ค่า name หลังรับอีเวนต์หรือไม่?

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

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

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

ตรวจสอบแหล่งอ้างอิงเมื่อ 2026-11-05:

• UnifyPort: account.profile.updated
• UnifyPort: Get account
• UnifyPort: การส่ง Webhook