WhatsApp 接入授權

WhatsApp QR 配對：叫 /auth/qr/start 起裝置會話。QR 字串透過 account.auth.required 事件推到你個 webhook，同時亦會 cache 喺 /auth/qr/check 畀同步輪詢。

1. 1. POST /v1/accounts，provider=whatsapp、auth_mode=qrcode。provider_data.device_os / device_platform 控制設備指紋；持久路由用帳號頂層 proxy。
2. 2. POST /v1/accounts/{account_id}/auth/qr/start 啟動裝置。返 status=awaiting_qr_scan，但 QR 字串係非同步到達。
3. 3. 監聽 webhook 嘅 account.auth.required 事件 —— auth_payload.qr_code 係要前端 render 做二維碼圖嘅原始字串。亦可以 poll /auth/qr/check。
4. 4. 掃碼成功之後，account.auth.succeeded 事件會帶埋 provider_account_ref 到達你個 webhook，通常跟住收到 account.started。請先確認 runtime_status，再決定係咪需要呼叫 POST /v1/accounts/{account_id}/runtime/start。

• provider_data.device_os — 配對過程中顯示嘅可選裝置標籤。除非要自訂顯示名，否則可以留空。
• provider_data.device_platform — 裝置平台數字編碼（1=CHROME，2=FIREFOX，5=SAFARI，14=IOS_PHONE，16=ANDROID_PHONE，...）。必須同 device_os 同時傳入先生效。
• proxy — 帳號頂層可選嘅持久代理設定，唔係 provider_data.proxy_config。

使用帳號已儲存的手機號碼，向 POST /auth/start 傳送 {}。將 data.verify_code 顯示給用戶在手機 WhatsApp 輸入，毋須提交至 /auth/code。傳送訊息前繼續檢查授權狀態及執行狀態。

1. 1. POST /v1/accounts，provider=whatsapp、auth_mode=code，provider_data.phone 填 E.164 純數字。手機號會持久化喺帳號上，後續嘅認證動作會自動複用。
2. 2. 使用帳號已儲存的手機號碼，向 POST /auth/start 傳送 {}。將 data.verify_code 顯示給用戶在手機 WhatsApp 輸入，毋須提交至 /auth/code。傳送訊息前繼續檢查授權狀態及執行狀態。
3. 3. 將 data.verify_code 顯示給用戶。回應不保證提供到期時間；配對碼失效時重新發起配對。
4. 4. 透過 GET /auth 查詢，直到 status=authorized；傳送訊息前再確認帳號 runtime_status=running。

• provider_data.phone — E.164 電話號碼（純數字，例如 15551234567）。建立帳號嗰陣填喺 provider_data.phone 入面；後續嘅認證動作會自動複用呢個號碼。

WhatsApp QR 授權可能要求 Passkey。可以繼續用託管授權頁，亦可以經公開 Account Auth 介面直接處理 WebAuthn。

1. 1. 啟動並輪詢一般 WhatsApp QR 流程，直到 GET /auth 或 /auth/qr/check 回傳 status=passkey_required 同 auth_payload.public_key。
2. 2. 託管路徑：call POST /v1/accounts/{account_id}/auth-sessions，再喺用戶瀏覽器開短期有效嘅 authorize_url，由託管頁面完成瀏覽器互動。
3. 3. 直接路徑：用 auth_payload.public_key call 瀏覽器 WebAuthn API，將完整憑證回應序列化後作為 webauthn_response 提交去 /auth/passkey-response。
4. 4. 如果狀態變成 passkey_confirmation，攞到用戶確認後 call POST /auth/passkey-confirm；否則喺 passkey_pending 期間繼續輪詢。
5. 5. 輪詢 GET /auth，直到 status 變成 authorized 或 failed。授權成功通常會自動啟動運行環境。

• auth_payload.public_key — 目前 Passkey 挑戰回傳嘅 WebAuthn 請求參數。
• authorize_url — 短期有效嘅託管授權 URL，請將完整 URL 當成敏感憑證。
• webauthn_response — 瀏覽器產生嘅完整 WebAuthn 憑證回應，序列化成 JSON 字串。