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

ย้ายแชต WhatsApp ระหว่างป้ายกำกับ: ส่งต่องานผ่าน API อย่างปลอดภัย

การย้ายแชต WhatsApp ระหว่างป้ายกำกับขั้นตอนงานผ่าน UnifyPort ต้องเปลี่ยนความสัมพันธ์สองครั้ง: เพิ่มป้ายปลายทาง ตรวจสอบผล แล้วจึงนำป้ายต้นทางออก เอกสารไม่ได้รับประกันการย้ายแบบอะตอมมิก ควรเก็บป้ายที่ไม่เกี่ยวข้องไว้ และแสดงงานส่งต่อที่ยังไม่แน่นอนว่าไม่เสร็จ อย่าลบตัวป้ายกำกับ หรือถือว่า timeout ยืนยันว่าไม่มีการเปลี่ยนแปลงเกิดขึ้น

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

  • action: "remove" นำป้ายออกจากบทสนทนาที่เลือก ไม่ใช่การลบตัวป้ายกำกับ
  • แชตมีหลายป้ายพร้อมกันได้ จึงไม่ได้บังคับให้มีผู้รับผิดชอบหรือขั้นตอนงานเพียงหนึ่งเดียว
  • เพิ่มก่อนนำออกช่วยรักษาการมองเห็น แต่ระหว่างทางจะมีทั้งสองป้ายชั่วคราว
  • เก็บข้อมูลมอบหมายงานหลักและความคืบหน้าการส่งต่อไว้ในแอป ไม่อนุมานจากป้ายเพียงอย่างเดียว

กำหนดสิ่งที่จะย้าย ไม่ใช่แทนที่ป้ายทั้งหมด

คำแนะนำเรื่องป้ายกำกับของ WhatsApp อธิบายการจัดระเบียบแชตและการใช้หลายป้ายกับแชตเดียว อีกทั้งระบุว่ากำลังทยอยเปลี่ยนป้ายกำกับเป็นรายการ การเปลี่ยนชื่อในหน้าจอไม่ได้หมายความว่าฟิลด์ label_id ของ UnifyPort เปลี่ยนชื่อ หรือทุกรายการในแอปมี API ที่เทียบกันได้

ลองดู สถานการณ์สมมติ: แชตมีป้าย “รอดำเนินการ” และ “VIP” เจ้าหน้าที่ต้องการย้ายไป “กำลังดำเนินการ” สิ่งที่ต้องทำคือเพิ่ม “กำลังดำเนินการ” นำ “รอดำเนินการ” ออก และคง “VIP” ไว้ ไม่ใช่แทนที่ป้ายทั้งหมดด้วยป้ายใหม่

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

เจตนาคำสั่งเป้าหมาย
สร้างหรือเปลี่ยนชื่อหมวดสร้างหรืออัปเดตป้ายตัวป้ายกำกับ
เพิ่มปลายทางความสัมพันธ์ action: "add"บทสนทนาที่เลือกภายใต้ป้ายนั้น
นำต้นทางออกความสัมพันธ์ action: "remove"บทสนทนาที่เลือกภายใต้ป้ายนั้น
เลิกใช้หมวดลบป้ายตัวป้าย ไม่ใช่ความสัมพันธ์ของแชตเดียว

อย่าใช้การลบป้ายแทนการนำป้ายออกจากแชตหนึ่งรายการ เพราะแชตอื่นอาจยังใช้หมวดนั้นอยู่

เตรียมคำสั่งทั้งสอง

อ่านรายการป้ายกำกับ ของบัญชีรับส่งข้อความที่เลือก เพื่อหา ID ต้นทางและปลายทาง อ่านให้ครบตามการแบ่งหน้า ชื่อเป็นข้อความแสดงผล ไม่ใช่กุญแจระบุตัวตนที่คงที่ หากต้องสร้างปลายทาง ให้ใช้สร้างหรืออัปเดตป้าย แล้วเก็บ data.id ที่ตอบกลับ

ระบุ conversation_id ของแชตภายใต้บัญชีเดียวกัน อย่าใช้ชื่อป้าย ชื่อที่แสดงของผู้ติดต่อ หรือ ID ข้อความแทน ID บทสนทนา ตรวจสอบตารางรองรับคำสั่ง ก่อน: คำสั่งป้ายเหล่านี้รองรับ whatsapp ในปัจจุบัน ไม่รองรับ LINE, Telegram, Zalo หรือผู้ให้บริการแยกต่างหากอย่าง whatsapp-protocol หากทีมใช้ LINE ร่วมกับ WhatsApp ต้องออกแบบหมวดหมู่ของ LINE ในแอปแยกจากคำสั่งนี้

เอกสารความสัมพันธ์ของป้าย กำหนดให้ใช้ POST /v1/accounts/{account_id}/conversations/labels พร้อม label_id, action และอาร์เรย์ conversation_ids ที่ไม่ว่าง

ฟังก์ชัน JavaScript ฝั่งเซิร์ฟเวอร์ต่อไปนี้ทำเพียง หนึ่งคำสั่ง โดยตั้งใจไม่ทำการส่งต่อทั้งหมดอัตโนมัติ ส่ง ID จริงที่แบ็กเอนด์เลือกและ API key ที่เก็บอย่างปลอดภัยเข้าไป โค้ดนี้เป็นตัวอย่างประกอบ ไม่ใช่ไคลเอนต์ production ที่ผ่านการทดสอบแล้ว

async function changeLabelMembership({
  apiKey, accountId, labelId, conversationIds, action
}) {
  const validId = value => typeof value === 'string' && value.trim() !== '';
  if (!validId(accountId) || !validId(labelId) ||
      !Array.isArray(conversationIds) || conversationIds.length === 0 ||
      !conversationIds.every(validId) || !['add', 'remove'].includes(action)) {
    throw new Error('Select an account, label, conversations, and action');
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/conversations/labels`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify({
        label_id: labelId,
        action,
        conversation_ids: [...new Set(conversationIds)]
      })
    }
  );
  const result = await response.json();
  return { httpStatus: response.status, result };
}

ครั้งแรกใช้ ID ปลายทางและ add ส่วนครั้งถัดไปใช้ ID ต้นทางและ remove กับแชตเดิม ปฏิเสธกรณีต้นทางและปลายทางเป็น ID เดียวกันในแอป ตรวจสอบ HTTP status และข้อมูลตอบกลับ เพราะ fetch ที่จบตามปกติไม่ได้แปลว่าสำเร็จเสมอไป ข้อมูลสำเร็จตามเอกสารระบุ label_id, action และ conversation_ids ที่ได้รับผล

ตรวจสอบระหว่างเพิ่มและนำออก

ขั้นตอนนี้เป็นคำแนะนำในการออกแบบแอป ไม่ใช่การรับประกันธุรกรรมจาก UnifyPort:

  1. บันทึกบัญชี บทสนทนา ต้นทาง และปลายทางไว้ในระบบของคุณ ตรวจสอบสิทธิ์ของเจ้าหน้าที่ในการเปลี่ยนการมอบหมาย
  2. เพิ่มป้ายปลายทาง เก็บผลตอบกลับและ request_id โดยไม่บันทึก API key
  3. เรียกรายการบทสนทนา พร้อม label_id ของปลายทางอย่างชัดเจน ยืนยันว่าแชตที่เลือกปรากฏก่อนนำต้นทางออก
  4. นำออกเฉพาะความสัมพันธ์กับต้นทาง คงป้ายอิสระอย่าง VIP ไว้
  5. ตรวจสอบทั้งสองมุมมอง หากผลไม่ตรงกับที่ตั้งใจ ให้แสดงว่างานยังไม่เสร็จ

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

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

กู้คืนโดยไม่ทำเจตนาเก่าซ้ำ

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

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

เอกสารสาธารณะไม่ได้รับประกันความเป็นอะตอมมิกระหว่างสองคำสั่ง การสำเร็จหรือล้มเหลวทั้งแบตช์ เงื่อนไขตรวจเวอร์ชันก่อนเขียน หรือ webhook เฉพาะสำหรับการเปลี่ยนป้าย สำหรับงานจำนวนมาก ให้เก็บความคืบหน้าแยกตามบทสนทนา ไม่ใช่ถือว่าทั้งแบตช์เป็นการมอบหมายที่เสร็จแล้ว set_label_members_failed ใช้กับความล้มเหลวฝั่งเซิร์ฟเวอร์หรือระบบต้นทางตามเอกสาร ส่วน unsupported_by_provider คือขอบเขตความสามารถ ไม่ใช่เหตุผลให้ retry ไม่สิ้นสุด

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

เพิ่มป้ายใหม่แล้วป้ายเก่าจะหายเองหรือไม่?

ไม่ API มีคำสั่งเพิ่มและนำออกแยกกัน ให้จัดการความสัมพันธ์ของแต่ละป้ายอย่างอิสระ

ใช้ป้ายบังคับให้มีเจ้าหน้าที่เพียงคนเดียวได้หรือไม่?

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

conversation.updated จะยืนยันการส่งต่อหรือไม่?

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

นี่เป็นคำสั่งทางการของ WhatsApp Cloud API หรือไม่?

ไม่ใช่ เป็น endpoint ของ UnifyPort ผ่านอินเทอร์เฟซที่ไม่เป็นทางการสำหรับบัญชีที่เชื่อมต่อแล้ว คู่มือแอป WhatsApp อธิบายแนวคิดสำหรับผู้ใช้ ไม่ใช่สัญญา API นี้

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

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

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

UnifyPort API

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

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

รับ API Keyดูเอกสารอ้างอิง API