สร้างกลุ่ม WhatsApp ผ่าน API: ตรวจสอบ ID และสมาชิกเริ่มต้น

หากต้องการสร้างกลุ่ม WhatsApp ผ่าน UnifyPort ให้ส่ง POST /v1/accounts/{account_id}/groups/create พร้อม name ซึ่งเป็นฟิลด์บังคับ และอาร์เรย์ members ซึ่งไม่บังคับ สำหรับคำขอสร้างนี้ สมาชิกเริ่มต้นของ WhatsApp ระบุด้วยหมายเลขโทรศัพท์ เมื่อสำเร็จ API จะคืน data.id ไม่ใช่รายงานการเข้าร่วมของสมาชิกแต่ละคน ให้บันทึก ID ทันที แล้วอ่านข้อมูลกลุ่มและรายชื่อสมาชิกก่อนเริ่มระบบอัตโนมัติที่ต้องใช้ผลเหล่านี้

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

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

อ่านข้อกำหนดการสร้างก่อนออกแบบแบบฟอร์ม

เอกสาร Create group กำหนดสัญญาดังตารางด้านล่าง UnifyPort ให้บริการ อินเทอร์เฟซที่ไม่เป็นทางการ สำหรับบัญชีรับส่งข้อความที่เชื่อมต่ออยู่ ไม่ใช่ endpoint ของ WhatsApp Cloud API ปัจจุบันตารางรองรับการดำเนินการ ระบุการสร้างกลุ่มสำหรับ whatsapp เท่านั้น ไม่รวม LINE, Telegram หรือผู้ให้บริการแยกต่างหากอย่าง whatsapp-protocol การอ่านกลุ่ม LINE ได้ไม่ได้แปลว่าสร้างกลุ่มด้วยคำขอเดียวกันได้

ค่า	ความหมาย	ไม่ใช่สิ่งที่ใช้แทนกันได้
account_id ใน path	บัญชีที่จะสร้างกลุ่ม	ID ของ workspace
name ใน body	ชื่อกลุ่มที่ต้องระบุ ยาวได้ไม่เกิน 100 อักขระ	ตัวระบุทรัพยากรที่ไม่ซ้ำ
members ใน body	สมาชิกเริ่มต้นที่ระบุหรือไม่ก็ได้ โดย WhatsApp ใช้หมายเลขโทรศัพท์	อาร์เรย์ LID ที่คัดลอกมาจากรายชื่อสมาชิก
data.id ในคำตอบ	ID ของกลุ่มที่เพิ่งสร้าง	รหัสเชิญหรือ ID ของ operation

ส่วน data ในคำตอบการสร้างมีเพียง ID กลุ่มใหม่ ไม่มีผลการเพิ่มรายบุคคล จึงควรแยก “สมาชิกเริ่มต้นที่ต้องการ” ออกจาก “สมาชิกที่ตรวจพบจริงภายหลัง”

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

เตรียมส่งคำขอสร้างที่ยืนยันแล้วเพียงครั้งเดียว

ตรวจสอบว่าบัญชีที่เลือกได้รับอนุญาตแล้วและ runtime เป็น running ตามเอกสารวงจรชีวิตบัญชี เก็บ API key ไว้ที่ backend และตรวจสิทธิ์ผู้ปฏิบัติงานที่ backend ด้วย

มาตรการที่แนะนำสำหรับแอปพลิเคชัน:

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

ตัวอย่าง JavaScript ฝั่งเซิร์ฟเวอร์ต่อไปนี้สร้างคำขอจากข้อมูลที่ยืนยันแล้ว ยังไม่ได้รันในงานนี้ และตั้งใจไม่ทำ retry อัตโนมัติ:

async function createGroupOnce({ apiKey, accountId, name, phones }) {
  if (!apiKey || !accountId || typeof name !== 'string' || !name.trim()) {
    throw new Error('Missing credential, account, or group name');
  }
  const body = { name };
  if (phones !== undefined) {
    if (!Array.isArray(phones) ||
        phones.some(p => typeof p !== 'string' || !/^[0-9]+$/.test(p))) {
      throw new Error('Use confirmed phone-number strings');
    }
    body.members = phones;
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/create`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

ใช้หมายเลขจริงที่ยืนยันแล้วตามรูปแบบในเอกสาร การตรวจว่าเป็นตัวเลขเป็นเพียงการป้องกันข้อมูลผิดรูปแบบในแอป ไม่ใช่หลักฐานว่าผู้ใช้หมายเลขนั้นเข้าร่วมได้ ต้องตรวจความยาวชื่อที่เอกสารกำหนดด้วย โค้ดใช้งานจริงต้องรองรับปัญหาเครือข่ายและคำตอบที่ไม่ใช่ JSON เก็บ request_id อย่างปลอดภัยเมื่อมี และไม่บันทึกข้อมูลรับรองหรือรายชื่อหมายเลขโทรศัพท์ลง log

แยกการบันทึก ID กลุ่มออกจากการตรวจสมาชิก

เมื่อได้รับ 200 OK พร้อม data.id ให้บันทึก ID แบบถาวรควบคู่กับบัญชีที่เลือกและเจตนาการสร้างในระบบ จากนั้นใช้ Get group โดยส่ง ID นี้เป็น group_id

ตรวจผู้เข้าร่วมผ่าน List conversation members โดยใช้ ID กลุ่มเป็น conversation_id และกำหนด type=group อ่านให้ครบตาม has_more และ next_cursor การไม่พบบางคนในหน้าแรกยังไม่ใช่การตรวจสมาชิกที่เสร็จสมบูรณ์ เก็บ peer_id และ role ตามค่าที่คืนมา อย่าสร้าง LID จากหมายเลขโทรศัพท์

การจัดการสมาชิกกลุ่ม ในภายหลังใช้สัญญาอีกชุดหนึ่ง: หนึ่งคำขอมี member_id แบบเอกพจน์และหนึ่ง action สำหรับ WhatsApp ใช้ LID ที่รายชื่อสมาชิกคืนมาใน peer_id อย่านำ payload ตอนสร้างไปใช้ตรง ๆ หากขั้นตอนถัดไปคือแต่งตั้งผู้ดูแล ให้ดูคู่มือเปลี่ยนบทบาทผู้ดูแล

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

สถานะเหล่านี้เป็นของแอปพลิเคชัน ไม่ใช่ค่าคำตอบ API ที่เพิ่มขึ้นมา

กู้สถานการณ์โดยไม่สร้างกลุ่มซ้ำ

รายการเหตุการณ์มาตรฐาน ไม่มี group.created และการสร้างสำเร็จไม่ได้รับประกัน callback นี้ ส่วน group.updated ก็ไม่ใช่ใบยืนยันที่รับประกันว่าจะมีให้ทุกคำขอสร้าง

หากคำตอบหาย ให้ตรวจ List groups ภายใต้บัญชีเดิมและอ่านให้ครบทุกหน้า รายการนี้รวมกลุ่มที่บัญชีเข้าร่วมแล้วแม้ยังไม่มีข้อความ ใช้ข้อมูลที่มีและแอป WhatsApp ช่วยตรวจสอบ ชื่อเหมือนกันอย่างเดียวไม่ยืนยันว่าเป็นกลุ่มเดียวกัน และการอ่านล้มเหลวหรืออ่านไม่ครบก็ไม่ยืนยันว่าการสร้างล้มเหลว

สัญญาการสร้างสาธารณะไม่ได้ระบุ idempotency key บันทึกเจตนาในระบบช่วยลดการส่งซ้ำจากแอปของคุณ แต่ไม่ทำให้การดำเนินการต้นทางมีการรับประกันแบบ exactly-once ระงับคำเชิญและข้อความอัตโนมัติที่เกี่ยวข้องไว้ขณะผลยังไม่แน่ชัด และให้ผู้ปฏิบัติงานตรวจทานก่อนสร้างอีกครั้ง

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

ไม่ส่ง members ได้หรือไม่?

ได้ เอกสาร API ระบุว่าไม่บังคับ แต่เป็นข้อกำหนดของโครงสร้างคำขอ ไม่ใช่การรับประกันพฤติกรรมของทุกบัญชีต้นทาง จึงยังต้องตรวจผลจริง

HTTP สำเร็จแปลว่าทุกคนเข้าร่วมแล้วหรือไม่?

ไม่ใช่ ผลตามเอกสารคืน ID กลุ่ม ไม่ใช่ผลรายบุคคล ต้องอ่านสมาชิกแยกต่างหาก

ส่งคำอธิบายและรูปกลุ่มพร้อมสร้างได้หรือไม่?

เอกสารไม่ได้ระบุสองค่านี้เป็นฟิลด์สร้าง ใช้ขั้นตอนแก้ไขข้อมูลกลุ่ม หลังสร้างแทน

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

พัฒนาตามเอกสาร Create group ก่อนเปิดใช้งาน ให้ทดสอบการกดซ้ำ คำตอบสูญหาย ชื่อกลุ่มซ้ำ การแบ่งหน้าสมาชิก และผู้ที่เข้าร่วมไม่ได้ด้วยบัญชีที่คุณควบคุม นี่คือรายการทดสอบที่เสนอ ไม่ใช่ผลทดสอบที่ทำแล้ว

ตรวจสอบแหล่งข้อมูลเมื่อ 2026-10-24:

• WhatsApp: เพิ่มและนำสมาชิกออกจากกลุ่ม
• UnifyPort: Create group
• UnifyPort: List conversation members
• UnifyPort: เหตุการณ์มาตรฐาน