← เอกสารอ้างอิง API
เริ่มต้นใช้งาน

วงจรชีวิตของบัญชี

บัญชีหนึ่งมีสถานะอิสระสามชุด: status (สวิตช์เชิงธุรกิจที่คุณตั้งเอง), สถานะการยืนยันตัวตนที่ได้จาก GET /v1/accounts/{id}/auth และ runtime_status (การเชื่อมต่อจริง) ส่วน payload ของ webhook เปิดเผยสองค่าหลังเป็น auth_status และ runtime_status — โปรดสังเกตว่าออบเจ็กต์บัญชีฝั่ง REST เองไม่มีฟิลด์ชื่อ auth_status

สเตตแมชชีนของการยืนยันตัวตน

  • pending_auth

    สถานะเริ่มต้นหลังสร้างบัญชี ยังไม่มีโฟลว์ใดเริ่มทำงาน

  • awaiting_qr_scan

    โฟลว์ QR กำลังทำงาน auth_payload มีเนื้อหา QR สำหรับนำไปเรนเดอร์

  • awaiting_code

    โฟลว์รหัสยืนยันกำลังทำงาน สำหรับ WhatsApp ให้กรอก verify_code จาก auth_payload ในโทรศัพท์

  • awaiting_password

    ผู้ให้บริการต้องการรหัสผ่าน 2FA หลังขั้นรหัสยืนยัน

  • authorized

    การยืนยันตัวตนเสร็จสมบูรณ์ รันไทม์จะถูกเริ่มอัตโนมัติ

  • failed

    โฟลว์ล้มเหลว last_error บอกสาเหตุ เริ่มโฟลว์ใหม่เพื่อลองอีกครั้ง

การเปลี่ยนสถานะ
1
pending_auth→awaiting_qr_scan

POST /auth/qr/start เริ่มโฟลว์ QR

2
pending_auth→awaiting_code

POST /auth/start เริ่มโฟลว์รหัสยืนยัน

3
awaiting_code→awaiting_password

ผู้ให้บริการเรียกขอรหัสผ่าน 2FA

4
awaiting_qr_scan→authorized

ผู้ให้บริการยืนยันการสแกน QR แล้ว

5
awaiting_code→authorized

รหัสยืนยัน (หรือการจับคู่ WhatsApp) ได้รับการยอมรับ

6
awaiting_password→authorized

รหัสผ่านได้รับการยอมรับ

7
authorized→pending_auth

ผู้ให้บริการทำให้ session ใช้ไม่ได้ — อีเวนต์ account.auth.required จะถูกส่งและต้องเริ่มโฟลว์ใหม่

8
awaiting_*→failed

ผู้ให้บริการรายงานความล้มเหลวที่ขั้นรอใดก็ได้ (อีเวนต์ account.auth.failed)

9
awaiting_*→pending_auth

POST /auth/cancel ยกเลิกโฟลว์ที่กำลังทำงาน

สเตตแมชชีนของรันไทม์

  • unknown

    สถานะเริ่มต้นหลังสร้างบัญชี และทุกครั้งที่แพลตฟอร์มไม่มีรายงานล่าสุดจากผู้ให้บริการ — เรียก /runtime/refresh เพื่อซิงก์ใหม่

  • starting

    กำลังเริ่มทำงาน ผู้ให้บริการกำลังนำ session ขึ้นออนไลน์

  • running

    เชื่อมต่อแล้วและพร้อมส่งและรับข้อความ

  • reconnecting

    การเชื่อมต่อหลุดและกำลังเชื่อมต่อใหม่ ไม่ว่าจะอัตโนมัติหรือสั่งเอง

  • disconnected

    ผู้ให้บริการรายงานว่า session ออฟไลน์ ใช้ reconnect หรือ start เพื่อกู้คืน

  • stopping

    กำลังหยุดทำงาน

  • stopped

    ไม่ได้เชื่อมต่อ เป็นสถานะหลังการหยุด

  • error

    รันไทม์พบข้อผิดพลาดที่กู้คืนไม่ได้ last_error บอกสาเหตุ

การเปลี่ยนสถานะ
1
unknown→starting

เริ่มอัตโนมัติหลังการให้สิทธิ์สำเร็จ

2
stopped→starting

การเรียก POST /runtime/start โดยตรง

3
starting→running

session ของผู้ให้บริการขึ้นออนไลน์ (อีเวนต์ account.started)

4
running→reconnecting

การเชื่อมต่อหลุด หรือมีการเรียก POST /runtime/reconnect

5
reconnecting→running

การเชื่อมต่อกลับมาเป็นปกติ

6
running→disconnected

ผู้ให้บริการรายงานว่า session ออฟไลน์ (อีเวนต์ account.status.updated)

7
disconnected→running

POST /runtime/reconnect หรือ /runtime/start นำกลับมาออนไลน์

8
running→stopping

POST /runtime/stop เริ่มการหยุดแบบ graceful

9
stopping→stopped

การหยุดเสร็จสมบูรณ์

10
*→error

ข้อผิดพลาดที่กู้คืนไม่ได้จากผู้ให้บริการ ณ จุดใดก็ได้

11
*→unknown

ไม่มีรายงานล่าสุดจากผู้ให้บริการ POST /runtime/refresh จะซิงก์ค่าใหม่

หมายเหตุ

  • Account.status เป็นของคุณ (สวิตช์เปิด/ปิดเชิงธุรกิจ ตั้งตอนสร้างหรือผ่าน PATCH) อีกสองสถานะเป็นของแพลตฟอร์มและอ่านได้อย่างเดียว: สถานะการยืนยันตัวตนผ่าน GET /v1/accounts/{id}/auth (ฟิลด์ status ของมัน) และ runtime_status บนออบเจ็กต์บัญชี
  • การให้สิทธิ์ที่สำเร็จจะเริ่มรันไทม์อัตโนมัติ — การเรียก POST /runtime/start ตามหลังเป็น no-op ที่ไม่มีผลเสีย
  • ระหว่างอยู่ในสถานะ authorized การเรียก POST /auth/start, /auth/qr/start และ /auth/session จะถูกปฏิเสธด้วย 409 account_already_authorized หากต้องการเริ่มโฟลว์ใหม่จริง ๆ ให้เรียก POST /auth/cancel ก่อน
  • อีเวนต์ account.auth.required หมายความว่าผู้ให้บริการทำให้ session ใช้ไม่ได้: สถานะ auth หลุดจาก authorized และ auth_payload จะมีข้อมูล (เช่น QR ใหม่) สำหรับยืนยันตัวตนอีกครั้ง
  • ทุกการเปลี่ยนแปลงของรันไทม์จะถูกส่งเป็นอีเวนต์ account.status.updated ที่มีทั้ง auth_status และ runtime_status — อัปเดตสำเนาในระบบของคุณจาก webhook แทนการ polling