← 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.

Trạng thái con của ủy quyền WhatsApp Passkey

  • passkey_required

    Luồng QR yêu cầu thêm credential Passkey. Hãy tạo phiên ủy quyền công khai.

  • passkey_pending

    Passkey challenge đã được phát hành; đang chờ hoàn tất authorize_url hoặc gửi phản hồi WebAuthn.

  • passkey_confirmation

    Provider yêu cầu xác nhận rõ ràng sau khi kiểm tra credential.

  • passkey_confirmation_sent

    Yêu cầu xác nhận đã được gửi; tiếp tục poll trạng thái xác thực.

  • 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
passkey_required→passkey_pending

Gửi credential WebAuthn đã serialize qua trang được lưu trữ hoặc POST /auth/passkey-response.

2
passkey_pending→passkey_confirmation

Provider yêu cầu người dùng xác nhận thao tác Passkey.

3
passkey_confirmation→passkey_confirmation_sent

POST /auth/passkey-confirm gửi xác nhận của người dùng.

4
passkey_pending→authorized

Provider chấp nhận credential mà không cần bước xác nhận bổ sung.

5
passkey_confirmation_sent→authorized

Provider chấp nhận credential đã được xác nhận.

6
passkey_*→failed

Provider từ chối hoặc không thể hoàn tất luồng Passkey.

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 thường tự khởi động runtime. POST /runtime/start là yêu cầu khởi động rõ ràng; chỉ gọi khi runtime_status thực tế vẫn cần và xử lý operation_status trả về.
  • 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.
  • account.status.updated báo cáo thay đổi xác thực hoặc runtime mà provider quan sát được, nhưng không được bảo đảm cho mọi chuyển trạng thái đã yêu cầu. Sau action hoặc reconnect, hãy đối chiếu trạng thái webhook bằng GET /v1/accounts/{account_id} hoặc POST /runtime/refresh.