WhatsApp 接入授權

WhatsApp QR 配對：呼叫 /auth/qr/start 啟動裝置會話。QR 字串透過 account.auth.required 事件推送到你的 webhook，同時也快取在 /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 是要前端渲染成二維碼圖片的原始字串。也可以輪詢 /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. 託管路徑：呼叫 POST /v1/accounts/{account_id}/auth-sessions，再於使用者瀏覽器開啟短期有效的 authorize_url，由託管頁面完成瀏覽器互動。
3. 3. 直接路徑：以 auth_payload.public_key 呼叫瀏覽器 WebAuthn API，將完整憑證回應序列化後作為 webauthn_response 提交至 /auth/passkey-response。
4. 4. 若狀態變為 passkey_confirmation，取得使用者確認後呼叫 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 字串。