บทช่วยสอน August 12, 2026

คู่มือกู้คืน Runtime ของบัญชีข้อความ: ควร Refresh, Reconnect, Start หรือยืนยันตัวตนใหม่?

เมื่อบัญชีข้อความ UnifyPort หยุดรับข้อความ อย่าเริ่มด้วยการให้ผู้ใช้เข้าสู่ระบบใหม่ ให้ตรวจทั้งสถานะการยืนยันตัวตนและ runtime_status ก่อน: ใช้ refresh เมื่อสถานะไม่ทราบหรือไม่ใหม่, reconnect เมื่อบัญชียังยืนยันตัวตนแล้วแต่การเชื่อมต่อมีปัญหา, start เมื่อ runtime ถูกหยุดไว้ และยืนยันตัวตนใหม่เฉพาะเมื่อสถานะ auth หรือเหตุการณ์ account.auth.required ระบุว่าต้องมีการดำเนินการจากผู้ใช้

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

status, สถานะการยืนยันตัวตน และ runtime_status เป็นคนละสถานะกัน
หลังยืนยันตัวตนสำเร็จ runtime มักเริ่มทำงานอัตโนมัติ
POST /runtime/refresh ซิงก์สถานะ แต่ไม่รีสตาร์ตการเชื่อมต่อ
POST /runtime/reconnect สร้างการเชื่อมต่อใหม่โดยเก็บการยืนยันตัวตนเดิมไว้
Webhook เป็นสัญญาณแจ้งเตือน หลังสั่งงานต้องตรวจยืนยันด้วยการอ่านบัญชีหรือ refresh

แยกสถานะสามชั้นให้ชัดเจน

เอกสารวงจรชีวิตบัญชีกำหนดสถานะสามชั้นดังนี้:

status คือสวิตช์ทางธุรกิจที่ workspace ควบคุม
สถานะ auth มาจาก GET /v1/accounts/{account_id}/auth และอาจเป็น pending_auth, awaiting_qr_scan, awaiting_code, awaiting_password, authorized หรือ failed
runtime_status คือสถานะการเชื่อมต่อสด โดยปรับเป็นค่ามาตรฐาน unknown, starting, running, stopping, stopped, reconnecting, disconnected และ error

การแยกนี้สำคัญมากสำหรับทีมไทยที่ดูแล LINE ผ่าน QR login หากบัญชียังเป็น authorized ให้ตรวจการเชื่อมต่อก่อนขอให้ผู้ใช้สแกน QR ใหม่ แต่ถ้า auth หมดอายุจริง การเรียก reconnect ซ้ำจะไม่ทำให้ขั้นตอนของผู้ใช้เสร็จสมบูรณ์

หากกำลังตรวจเหตุการณ์ระดับแพลตฟอร์มหรือสถานะการตรวจสอบบัญชี ให้ใช้เช็กลิสต์รับมือ WhatsApp Account Under Reviewเพื่อแยกปัญหาแพลตฟอร์ม นโยบาย runtime และตัวรับ Webhook

ตารางตัดสินใจ: refresh, reconnect, start หรือยืนยันตัวตนใหม่

สิ่งที่พบ	คำสั่งแรก	เหตุผล
`runtime_status: unknown`	Refresh	ซิงก์สถานะล่าสุดจากผู้ให้บริการก่อนเปลี่ยนการเชื่อมต่อ
`running` แต่ยืนยันแล้วว่าการเชื่อมต่อผิดปกติ	Reconnect	สร้างการเชื่อมต่อใหม่โดยรักษา auth เดิม
`disconnected` และ auth เป็น `authorized`	Reconnect แล้วตรวจซ้ำ	Auth ยังใช้ได้ แต่ runtime ออฟไลน์
`stopped` และบัญชีควรออนไลน์	Start	Runtime ที่หยุดไว้ต้องเริ่มอย่างชัดเจน
`starting`, `stopping` หรือ `reconnecting`	ตรวจซ้ำก่อน	มีคำสั่งกำลังทำงานอยู่แล้ว
Auth เป็น `pending_auth`, `awaiting_*` หรือ `failed`	ทำขั้นตอน auth ที่ตรงกัน	คำสั่ง runtime ไม่สามารถแทนการยืนยันตัวตนของผู้ใช้ได้
ได้รับ `account.auth.required`	ยืนยันตัวตนตาม `auth_payload`	เซสชันปัจจุบันต้องการการดำเนินการจากผู้ใช้
`runtime_status: error`	Refresh และตรวจบริบทข้อผิดพลาด	อย่าถือว่าทุกข้อผิดพลาดมีวิธีแก้เดียวกัน

Reconnect APIใช้เมื่อบัญชียังออนไลน์ในระดับบัญชี แต่การเชื่อมต่อ runtime ไม่สมบูรณ์ ส่วน Start APIควบคุม runtime ไม่ใช่การยืนยันตัวตน

ทำขั้นตอนกู้คืนตามลำดับ

1. อ่านทั้งบัญชีและสถานะ auth

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0 \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0/auth \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

ออบเจ็กต์บัญชีให้ runtime_status ส่วนทรัพยากร auth ให้ status ของตัวเอง และอาจมี auth_payload หรือ last_error อย่าอนุมานสถานะ auth จาก runtime เพียงอย่างเดียว

2. ถ้าเป็น unknown ให้ refresh ก่อน

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/refresh \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Refresh จะซิงก์และคืน runtime_status แบบมาตรฐาน ใช้ตรวจสอบสถานะหลัง start, reconnect หรือ auth ได้ด้วย แต่ไม่แทนตัวรับ Webhook หรือที่เก็บข้อความ

3. Reconnect เมื่อ auth ยังใช้ได้เท่านั้น

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/reconnect \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

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

4. Start เมื่อ runtime เป็น stopped

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/start \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

การยืนยันตัวตนสำเร็จมักเริ่ม runtime อัตโนมัติ จึงไม่ควรบังคับให้เข้าสู่ระบบใหม่ก่อนเรียก start ทุกครั้ง

5. ยืนยันตัวตนใหม่เมื่อมีหลักฐานจาก auth

account.auth.required อาจมี auth_status, runtime_status และ auth_payload เช่น QR, URL, PIN หรือรหัสยืนยันตามผู้ให้บริการและโหมด auth แสดงเฉพาะขั้นตอนที่จำเป็นให้เจ้าของบัญชี และอย่าบันทึกข้อมูลเซสชันลง log

ใช้ Webhook เป็นสัญญาณ และใช้ API เพื่อตรวจยืนยัน

สมัครรับ account.status.updated, account.started, account.auth.required, account.auth.succeeded และ account.auth.failed หรือใช้ subscribed_events: ["*"] ดู payload สาธารณะในรายการเหตุการณ์มาตรฐาน

account.status.updated รายงานการเปลี่ยนแปลงที่ผู้ให้บริการสังเกตเห็น แต่ไม่ได้รับประกันว่าจะเกิดขึ้นกับทุก transition ที่ร้องขอ หลัง reconnect, start หรือ auth ให้ตรวจด้วยการอ่านบัญชีหรือ refresh และตรวจลายเซ็นก่อนเชื่อถือเหตุการณ์เสมอ คู่มือ Webhook HMAC การป้องกัน replay และ retryอธิบายสัญญาการลงนามของ raw body

อ่านสถานะ auth และ runtime_status
ถ้า auth ต้องการผู้ใช้: ทำ auth flow ที่ตรงกัน
ถ้าเป็น unknown: refresh
ถ้าเป็น disconnected: reconnect
ถ้าเป็น stopped: start
ถ้าคำสั่งกำลังทำงาน: ตรวจยืนยัน
ถ้าเป็น running: ไม่เปลี่ยนแปลง
กรณีอื่น: refresh และส่งต่อพร้อมบริบทข้อผิดพลาด

ข้อจำกัด

การกู้คืน runtime ไม่ได้พิสูจน์ว่า Webhook endpoint, queue, ฐานข้อมูล หรือระบบปลายทางทำงานปกติ หากบัญชีเป็น running แต่แอปยังไม่ได้ข้อความ ให้ตรวจเส้นทางส่ง Webhook และ consumer แยกต่างหาก

Reconnect ไม่รับประกันการส่งประวัติย้อนหลัง UnifyPort ไม่มี REST API สำหรับอ่านประวัติข้อความและไม่รับประกันการส่งเหตุการณ์ที่พลาดไปใหม่ WhatsApp อาจส่งประวัติแบบจำกัดและ best-effort หลังเริ่มหรือเชื่อมต่อใหม่ แต่ไม่ใช่คลังข้อมูลที่สมบูรณ์ จึงควรเก็บเหตุการณ์ทันทีที่มาถึง

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

`runtime_status: disconnected` ต้องสแกน QR ใหม่หรือไม่?

ไม่เสมอไป ตรวจ auth ก่อน หากยังเป็น authorized ให้ reconnect และเริ่ม auth flow ใหม่เฉพาะเมื่อสถานะ auth หรือ account.auth.required ระบุว่าจำเป็น

refresh ต่างจาก reconnect อย่างไร?

Refresh อ่านและปรับสถานะล่าสุดให้เป็นมาตรฐาน ส่วน reconnect สร้างการเชื่อมต่อที่ผิดปกติขึ้นใหม่

ต้องเรียก start หลังยืนยันตัวตนสำเร็จทุกครั้งหรือไม่?

โดยทั่วไปไม่ต้อง เพราะ runtime มักเริ่มอัตโนมัติ ให้เรียก start เมื่อสถานะที่อ่านได้ระบุว่าจำเป็นเท่านั้น

runtime เป็น running แต่ไม่มีข้อความ ต้องตรวจอะไร?

ตรวจสถานะ Webhook, การตรวจลายเซ็น, HTTP acknowledgement, retry, queue และ storage การเชื่อมต่อปกติกับ consumer ปกติเป็นคนละเงื่อนไข

ขั้นตอนถัดไป

สร้าง decision table ตามคู่มือวงจรชีวิตบัญชีและเพิ่มเอกสาร Refresh runtime stateไว้ในคู่มือปฏิบัติการ

แหล่งข้อมูลทางการ

ตรวจเอกสารทางการของ UnifyPort ต่อไปนี้เมื่อ 12 สิงหาคม 2026: