← Tham chiếu API
Bắt đầu

Vòng đời tài khoản

Một tài khoản mang ba trạng thái độc lập: status (công tắc nghiệp vụ do bạn đặt), trạng thái xác thực trả về bởi GET /v1/accounts/{id}/auth, và runtime_status (kết nối trực tiếp). Payload webhook lộ hai trạng thái sau dưới tên auth_status và runtime_status — lưu ý bản thân đối tượng tài khoản REST không có trường tên auth_status.

Máy trạng thái xác thực

  • pending_auth

    Trạng thái ban đầu sau khi tạo tài khoản; chưa có luồng nào được bắt đầu.

  • awaiting_qr_scan

    Một luồng QR đang hoạt động; auth_payload mang nội dung QR để hiển thị.

  • awaiting_code

    Một luồng mã xác nhận đang hoạt động; với WhatsApp, verify_code trong auth_payload được nhập trên điện thoại.

  • awaiting_password

    Provider yêu cầu mật khẩu hai yếu tố sau bước nhập mã.

  • authorized

    Xác thực hoàn tất. Runtime được khởi động tự động.

  • failed

    Luồng thất bại; last_error mang lý do. Bắt đầu một luồng mới để thử lại.

Chuyển trạng thái
1
pending_auth→awaiting_qr_scan

POST /auth/qr/start bắt đầu một luồng QR.

2
pending_auth→awaiting_code

POST /auth/start bắt đầu một luồng mã xác nhận.

3
awaiting_code→awaiting_password

Provider yêu cầu mật khẩu hai yếu tố.

4
awaiting_qr_scan→authorized

Provider xác nhận thao tác quét QR.

5
awaiting_code→authorized

Mã (hoặc ghép cặp WhatsApp) được chấp nhận.

6
awaiting_password→authorized

Mật khẩu được chấp nhận.

7
authorized→pending_auth

Provider vô hiệu hóa phiên — sự kiện account.auth.required được phát và cần bắt đầu một luồng mới.

8
awaiting_*→failed

Provider báo thất bại ở bất kỳ bước chờ nào (sự kiện account.auth.failed).

9
awaiting_*→pending_auth

POST /auth/cancel hủy luồng đang hoạt động.

Máy trạng thái runtime

  • unknown

    Trạng thái ban đầu sau khi tạo tài khoản, và bất cứ khi nào nền tảng không có báo cáo mới từ provider — gọi /runtime/refresh để đồng bộ lại.

  • starting

    Đang khởi động; provider đang đưa phiên online.

  • running

    Đã kết nối, có thể gửi và nhận.

  • reconnecting

    Kết nối bị rớt và việc kết nối lại (tự động hoặc thủ công) đang diễn ra.

  • disconnected

    Provider báo phiên đã offline; kết nối lại hoặc khởi động để khôi phục.

  • stopping

    Đang dừng.

  • stopped

    Không kết nối. Trạng thái sau khi dừng.

  • error

    Runtime gặp lỗi không thể khôi phục; last_error mang lý do.

Chuyển trạng thái
1
unknown→starting

Tự khởi động sau khi ủy quyền thành công.

2
stopped→starting

Gọi POST /runtime/start một cách tường minh.

3
starting→running

Phiên của provider lên online (sự kiện account.started).

4
running→reconnecting

Kết nối bị rớt, hoặc POST /runtime/reconnect được gọi.

5
reconnecting→running

Kết nối được thiết lập lại.

6
running→disconnected

Provider báo phiên offline (sự kiện account.status.updated).

7
disconnected→running

POST /runtime/reconnect hoặc /runtime/start đưa nó trở lại.

8
running→stopping

POST /runtime/stop bắt đầu dừng êm.

9
stopping→stopped

Việc dừng hoàn tất.

10
*→error

Lỗi provider không thể khôi phục, tại bất kỳ thời điểm nào.

11
*→unknown

Không có báo cáo mới từ provider; POST /runtime/refresh đồng bộ lại giá trị.

Ghi chú

  • Account.status thuộc về bạn (công tắc bật/tắt nghiệp vụ, đặt khi tạo hoặc qua PATCH). Hai trạng thái còn lại do nền tảng sở hữu và chỉ đọc: trạng thái xác thực qua GET /v1/accounts/{id}/auth (trường status của nó), runtime_status trên đối tượng tài khoản.
  • Ủy quyền thành công sẽ tự khởi động runtime — gọi POST /runtime/start sau đó là một no-op vô hại.
  • Khi đang authorized, POST /auth/start, /auth/qr/start và /auth/session bị từ chối với 409 account_already_authorized. Hãy gọi POST /auth/cancel trước nếu bạn thật sự cần một luồng mới.
  • Sự kiện account.auth.required nghĩa là provider đã vô hiệu hóa phiên: trạng thái xác thực rời khỏi authorized và auth_payload mang dữ liệu (chẳng hạn QR mới) để xác thực lại.
  • Mọi thay đổi runtime đều được đẩy dưới dạng sự kiện account.status.updated mang cả auth_status lẫn runtime_status — hãy đồng bộ bản sao cục bộ từ webhook thay vì poll.