Ủy quyền WhatsApp

Ghép cặp QR của WhatsApp: gọi /auth/qr/start để bắt đầu phiên thiết bị. QR token đến qua account.auth.required và cũng có thể poll qua /auth/qr/check.

1. 1. POST /v1/accounts với provider=whatsapp, auth_mode=qrcode. device_os / device_platform nằm trong provider_data; định tuyến bền vững dùng proxy cấp tài khoản.
2. 2. POST /v1/accounts/{account_id}/auth/qr/start để khởi động thiết bị. Trả về status=awaiting_qr_scan, nhưng chuỗi QR đến bất đồng bộ.
3. 3. Nghe sự kiện account.auth.required trên webhook — auth_payload.qr_code là chuỗi để UI render thành mã QR. Cũng có thể polling /auth/qr/check.
4. 4. Sau khi quét, account.auth.succeeded chứa provider_account_ref và thường được theo sau bởi account.started. Hãy kiểm tra runtime_status trước khi quyết định có cần POST /v1/accounts/{account_id}/runtime/start hay không.

• provider_data.device_os — Nhãn thiết bị tùy chọn hiển thị trong quá trình ghép cặp. Có thể để trống nếu không cần tên hiển thị riêng.
• provider_data.device_platform — Mã số platform thiết bị (1=CHROME, 2=FIREFOX, 5=SAFARI, 14=IOS_PHONE, 16=ANDROID_PHONE, ...). Phải đi kèm device_os mới có hiệu lực.
• proxy — Cấu hình proxy bền vững ở cấp tài khoản, không phải provider_data.proxy_config.

Ghép cặp WhatsApp theo số điện thoại: lưu số điện thoại trên tài khoản ngay khi tạo, sau đó nhập verify_code 8 ký tự trên điện thoại (Liên kết thiết bị → Liên kết bằng số điện thoại).

1. 1. POST /v1/accounts với provider=whatsapp, auth_mode=code, và provider_data.phone đặt thành số E.164 (chỉ số). Số điện thoại được lưu trên tài khoản và tự động tái sử dụng cho các thao tác xác thực sau.
2. 2. POST /v1/accounts/{account_id}/auth/start với body rỗng. Số điện thoại đã lưu được dùng lại; response mang verify_code 8 ký tự dưới auth_payload.
3. 3. Hiển thị verify_code cho người dùng. Điện thoại chấp nhận trong khoảng 3 phút — quá thời gian phải khởi động lại luồng.
4. 4. Sau khi ghép cặp xong, events.PairSuccess và events.Connected đến qua webhook giống luồng QR.

• provider_data.phone — Số điện thoại E.164 chỉ số (ví dụ 15551234567 không kèm +). Đặt giá trị này dưới provider_data.phone khi tạo tài khoản; các thao tác xác thực sau sẽ tự động tái sử dụng.

Nhánh Passkey bổ sung của WhatsApp: sau khi bắt đầu luồng QR, trạng thái có thể yêu cầu credential WebAuthn và xác nhận rõ ràng khi cần.

1. 1. Bắt đầu luồng QR WhatsApp chuẩn. Khi GET /v1/accounts/{account_id}/auth trả status=passkey_required, tạo POST /v1/accounts/{account_id}/auth-sessions.
2. 2. Hoàn tất authorize_url được lưu trữ hoặc dùng auth_payload.public_key với WebAuthn API rồi gửi credential đã serialize qua POST /auth/passkey-response.
3. 3. Nếu trạng thái thành passkey_confirmation, gọi POST /v1/accounts/{account_id}/auth/passkey-confirm mà không có JSON body.
4. 4. Poll GET /v1/accounts/{account_id}/auth sau mỗi action. passkey_pending và passkey_confirmation_sent là trạng thái trung gian.
5. 5. Kết thúc khi status=authorized hoặc xử lý last_error khi status=failed. Bắt đầu luồng QR mới nếu cần thử lại.

• auth_payload.public_key — Tham số WebAuthn challenge công khai từ auth_payload.public_key. Chỉ truyền cho WebAuthn API trong origin tin cậy.
• authorize_url — Trang ủy quyền tạm thời được lưu trữ để hoàn tất Passkey mà không cần tự xây WebAuthn UI.
• webauthn_response — Credential WebAuthn đã serialize. Truyền nguyên chuỗi; không ghi log hoặc công khai giá trị.