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 ではありません。

保存済みの電話番号を使い、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 までポーリングします。認証成功後は通常 runtime が自動起動します。

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