WhatsApp 認証

WhatsApp QR ペアリング: /auth/qr/start を呼び出してデバイスセッションを開始します。QR 文字列は account.auth.required イベントとして webhook に届き、/auth/qr/check でも同期取得できます。

1. 1. POST /v1/accounts で provider=whatsapp、auth_mode=qrcode。device_os / device_platform は provider_data、永続ルーティングはアカウント直下の 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 が UI で QR 画像にレンダリングすべき生コードです。あるいは /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 — 端末の「リンク済みデバイス」画面に表示される OS ラベル。既定値は MacOS。device_platform と組み合わせて指定する必要があります（有効な組み合わせは上流ドキュメントの platform 表を参照）。
• provider_data.device_platform — デバイス platform の数値コード（1=CHROME、2=FIREFOX、5=SAFARI、14=IOS_PHONE、16=ANDROID_PHONE、...）。device_os と同時に指定したときのみ反映されます。
• proxy — アカウント直下の永続プロキシ設定。provider_data.proxy_config ではありません。

WhatsApp 電話番号ペアリング：アカウント作成時に電話番号を保存しておき、端末の「リンク済みデバイス → 電話番号でリンク」で 8 桁の verify_code を入力します。

1. 1. POST /v1/accounts で provider=whatsapp、auth_mode=code を指定し、provider_data.phone に E.164 純数字（+ なし）の電話番号を設定します。電話番号はアカウントに永続化され、以降の認証アクションで自動的に再利用されます。
2. 2. POST /v1/accounts/{account_id}/auth/start を空のボディで呼び出します。保存済みの電話番号が再利用され、レスポンスの auth_payload に 8 桁の verify_code が含まれます。
3. 3. verify_code をエンドユーザに表示。端末側の受付時間は約 3 分で、超過した場合は再度フローを起こします。
4. 4. ペアリング成功後、account.auth.succeeded と account.started が webhook に届きます (QR フローと同様)。

• 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 までポーリングします。認証成功後は通常 runtime が自動起動します。

• auth_payload.public_key — 現在の Passkey チャレンジで返される WebAuthn リクエストオプション。
• authorize_url — 短期有効なホスト型認可 URL。完全な URL を機密資格情報として扱ってください。
• webauthn_response — ブラウザ生成の完全な WebAuthn 資格情報レスポンスを JSON 文字列にしたもの。