สร้างสาย WhatsApp สำเร็จแต่ไม่ดัง? ตรวจสอบตั้งแต่ preparing จนเชื่อมต่อ

หากสร้างสายเสียง WhatsApp แล้วได้ 201 แต่โทรศัพท์ผู้รับไม่ดัง ให้เริ่มจากขั้นตอนล่าสุดที่ยืนยันได้ก่อน การตอบกลับ state: preparing หมายถึงลิงก์สำหรับโทรผ่านเบราว์เซอร์พร้อมแล้วเท่านั้น ไม่ได้หมายความว่าเริ่มโทรออกแล้ว การส่งคำขอสร้างซ้ำอาจทำให้ติดตามความพยายามครั้งแรกได้ยากขึ้น

คู่มือนี้ใช้กับ สายเสียงขาออกแบบตัวต่อตัวที่มนุษย์เป็นผู้เริ่ม ในรุ่นทดสอบแบบปิดของ UnifyPort ผ่านอินเทอร์เฟซที่ไม่เป็นทางการ ไม่ใช่คู่มือ Meta WhatsApp Business Calling API สำหรับการตั้งค่าเริ่มต้นและตัวอย่างคำขอแบบครบถ้วน โปรดดูบทสอนการเชื่อมต่อสายเสียง บทความนี้เน้นหาจุดที่เกิดปัญหาจากหลักฐานที่มีอยู่แล้วในแอป

1. แยกให้ชัดว่าหลักฐานยืนยันอะไรได้บ้าง

หลักฐาน	สิ่งที่ยืนยันได้	สิ่งที่ยังยืนยันไม่ได้
การสร้างตอบกลับ 201 และ preparing	เตรียมลิงก์โทรแล้ว	เริ่มโทร มีเสียงเรียกเข้า หรือเชื่อมต่อแล้ว
การตรวจสอบสายปัจจุบันตอบกลับ active	สายที่ระบบจัดการเชื่อมต่อแล้วและยังไม่สิ้นสุด	Webhook ถึงแอปแล้ว
ได้รับ call.answered	สายที่เกี่ยวข้องเชื่อมต่อแล้ว	อัปเดตทิกเก็ตฝ่ายบริการแล้ว
ได้รับ call.ended	สายที่เกี่ยวข้องสิ้นสุดแล้ว	ระยะเวลาเป็นศูนย์แปลว่าไม่มีการรับสาย
การตรวจสอบสายปัจจุบันตอบกลับ data: {}	ไม่พบสายปัจจุบันที่ UnifyPort จัดการ	ผลของสายก่อนหน้าหรือสถานะว่างบนแอปมือถือ

ก่อนนำข้อมูลมารวมกัน ให้ตรวจสอบเวิร์กสเปซ account_id และรหัสสายให้ตรงกัน การตอบกลับ API ใช้ call_id ส่วนเหตุการณ์การโทรใช้ data.call.id เจ้าหน้าที่คนอื่นอาจเริ่มอีกสายบนบัญชีรับส่งข้อความเดียวกันได้

2. สร้างสำเร็จ แต่โทรศัพท์ผู้รับไม่ดัง

ตรวจสอบตามลำดับต่อไปนี้โดยเทียบกับข้อกำหนดการสร้างสาย:

1. ยืนยันว่าแอปเลือกบัญชีรับส่งข้อความ WhatsApp ที่ต้องการและได้รับอนุญาตแล้ว โดยมี runtime_status เป็น running
2. ตรวจสอบคำขอที่บันทึกไว้: to.id ต้องเป็น conversation_id ที่ได้จากบัญชีนั้น to.type ต้องเป็น user และ media_type ต้องเป็น voice ห้ามใช้สตริงหมายเลขโทรศัพท์แทน
3. เปรียบเทียบเวลาปัจจุบันกับ expires_at ที่ตอบกลับมา ช่วงเตรียมการมีค่าเริ่มต้นสองนาทีนับจากสร้าง แต่เซิร์ฟเวอร์ปรับได้ จึงต้องยึดเวลาที่ตอบกลับ กำหนดเวลานี้ไม่จำกัดความยาวของสายที่เชื่อมต่อแล้ว
4. ยืนยันว่าเจ้าหน้าที่ที่ได้รับมอบหมายเปิดลิงก์ส่วนตัวแบบใช้ครั้งเดียว join_url และกด Start call ก่อนหมดอายุ การเปิดหน้าอย่างเดียวไม่เริ่มโทร ต้องอนุญาตไมโครโฟน ส่วนกล้องเป็นตัวเลือก การอนุญาตแล้วก็ยังไม่ใช่หลักฐานว่าเชื่อมต่อสำเร็จ

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

3. หมดเวลารอหรือเกิดข้อขัดแย้ง ทำให้ยังไม่ทราบผล

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

curl 'https://api.unifyport.ai/v1/calls/active?account_id=acc_example' \
  -H 'X-Api-Key: <YOUR_API_KEY>'

สายเสียงขาออกที่เชื่อมต่อแล้วอาจตอบกลับดังนี้:

{
  "request_id": "req_example",
  "data": {
    "call_id": "call_example",
    "state": "active",
    "direction": "outbound",
    "media_type": "voice"
  }
}

เมื่อไม่มีสายปัจจุบันที่ระบบจัดการ จะตอบกลับดังนี้:

{
  "request_id": "req_example",
  "data": {}
}

การตรวจสอบอาจตอบกลับ preparing, dialing, ringing หรือ connecting ได้เช่นกัน อย่าสมมติว่าทุกสายต้องผ่านทุกสถานะ การตรวจสอบนี้ไม่กู้คืนลิงก์สายที่หายไป ไม่ให้ประวัติการโทร และไม่บอกว่าฝ่ายใดกำลังใช้สายในแอป WhatsApp บนมือถือ การตรวจสอบที่ล้มเหลวไม่ใช่การตอบกลับสำเร็จที่มีข้อมูลว่าง

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

4. เชื่อมต่อแล้ว แต่ไม่มี callback

ตรวจสอบตั้งแต่สิทธิ์ใช้งานไปจนถึงสถานะที่บันทึกในแอป:

• สิทธิ์ใช้งาน: is_beta เป็นแฟล็กเวิร์กสเปซแบบอ่านอย่างเดียวที่ฝ่ายสนับสนุนเปิดให้ การสมัครแบบ wildcard ไม่ได้ให้สิทธิ์ทดสอบ เวิร์กสเปซที่ไม่มีสิทธิ์จะได้รับ 403 beta_feature_not_enabled เมื่อระบุสมัครเหตุการณ์การโทรโดยตรง
• การสมัครเหตุการณ์: สำหรับเวิร์กสเปซที่มีสิทธิ์ subscribed_events ต้องมีชื่อเหตุการณ์ที่ต้องการ หรือใช้ * รายการว่าง หรือละฟิลด์นี้ หากระบุรายการชัดเจน จะตรงกับเหตุการณ์ที่ระบุเท่านั้น ตรวจสอบทั้งเหตุการณ์เชื่อมต่อและเหตุการณ์สิ้นสุด
• การส่ง: ตรวจสอบ URL และสถานะของ endpoint ที่ตั้งค่าไว้ บันทึกการเข้าถึงของผู้รับ และการตอบกลับ HTTP ค่า 2xx เป็นการยืนยันการส่ง ไม่ได้พิสูจน์ว่าอัปเดตทิกเก็ตสำเร็จ
• การประมวลผล: ทำตามคู่มือการส่งและตรวจสอบลายเซ็น เมื่อตั้งค่า signing_secret แล้ว ให้ตรวจสอบ X-Device-Signature ด้วย X-Device-Timestamp และเนื้อหาคำขอดิบ ตรวจสอบการตัดข้อมูลซ้ำด้วย id ของเหตุการณ์ การจัดเก็บถาวร และการเชื่อมโยงสายกับทิกเก็ตแยกกัน

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

5. ระยะเวลาศูนย์วินาทีและผลลัพธ์ว่างต้องดูข้อมูลประกอบ

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

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

6. เตรียมบันทึกที่ใช้ส่งต่อให้ตรวจสอบได้

บันทึกรหัสเวิร์กสเปซ บัญชีรับส่งข้อความ บทสนทนาและสาย รวมถึง request_id เวลา UTC การตอบกลับที่ปกปิดข้อมูลลับแล้ว การกระทำและสถานะสิทธิ์ของเจ้าหน้าที่ ตลอดจนบันทึกฝั่งผู้รับที่มีอยู่ ระบุแต่ละข้อว่า “ยืนยันแล้ว” หรือ “ยังไม่ทราบ” อย่าใส่ API key คีย์ลับสำหรับลายเซ็น หรือลิงก์สายส่วนตัวแบบเต็มในภาพหน้าจอและบันทึกที่แชร์

หากยังมีขั้นตอนที่อธิบายไม่ได้ ให้ส่งบันทึกให้ฝ่ายสนับสนุนด้านเทคนิค คู่มือนี้ไม่ได้หมายความว่ารองรับสายเข้า การโทรกลุ่ม การบันทึกเสียง การถอดเสียง การเชื่อมต่อ SIP/PBX หรือ AI โทรออกโดยอัตโนมัติ