> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget WebView 統合

> Lovi チャットウィジェットを注入するための埋め込み可能な Web ラッパー

## はじめに

Widget WebView エンドポイントは、Web ページやモバイルアプリに Lovi チャットウィジェットを安全に埋め込むためのインタラクティブな HTML ラッパーです。標準の JSON レスポンスを返す代わりに、このエンドポイントはチャットインターフェースを指す `iframe` を含む完全な HTML ドキュメントを提供します。

このラッパーはセキュアなブリッジとして機能し、サーバー側で必要な統合メタデータ（エージェントのウェルカムメッセージや言語設定など）を取得し、標準の `postMessage` 通信を使用して Web ビューに安全に注入します。

***

## 🌐 Widget WebView の取得

> **メソッド**: GET **フォーマット**: HTML

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/widgetWebView
```

*代替パス形式:* `GET https://cloud.lovi.ai/functions/v1/widgetWebView/{customer_id}/{widget_id}`

### クエリパラメータ

上記のパス構造を使用しない場合、クエリ文字列で必須パラメータを渡す必要があります。

| パラメータ         | 必須  | 説明                                                                    |
| ------------- | --- | --------------------------------------------------------------------- |
| `customer_id` | はい  | 権限を検証するために使用する会社の Access Key。                                         |
| `widget_id`   | はい  | ロードしたいチャネルアカウント/ウィジェットの特定の `uuid`。                                    |
| `lang`        | いいえ | ターゲット言語コード（例: `es`、`en`、`pt`）。指定するとウェルカムメッセージが翻訳されます。                 |
| `showClose`   | いいえ | 文字列としての Boolean（`true` または `false`）。デフォルト `true`。ウィジェットを閉じられるかを決定します。 |

### 仕組み

1. **認証**: サーバーは `customer_id` (Access Key) を検証し、`widget_id` の所有権を確認します。
2. **メタデータ取得**: ウィジェット設定を取得し、必要に応じて Lovi 翻訳バックエンドにクエリして、エージェントのウェルカムメッセージを要求された `lang` に翻訳します。
3. **HTML 配信**: サーバーは `<iframe src="https://widget.lovi.ai/?cw_id=...">` を含む HTML ページを返します。
4. **PostMessage ブリッジ**: ロードされた HTML には、iframe からトリガーされる `get_widget` および `get_customer` イベントをリッスンする JavaScript が含まれています。ウィジェット設定 (`widgetData`) で安全に応答し、ローカルストレージ（一意のユーザー ID の生成など）を処理します。

### 一般的なエラー

ウィジェットのロードに失敗した場合、HTML ペイロードの代わりに次の HTTP ステータスコードのいずれかを受け取る可能性があります:

* **400 Bad Request**: `customer_id` または `widget_id` が欠落している、または `widget_id` が有効な UUID でない。
* **403 Forbidden**: 無効な `customer_id` (Access Key 検証失敗)。
* **404 Not Found**: 会社または指定されたウィジェットが見つからなかった。
* **500 Internal Server Error**: ラッパーの生成中に予期しないエラーが発生した。

> 🧭 **重要**: ウィジェットが「Loading Widget...」画面でスタックしている場合、ブラウザのコンソールを確認してください。環境がクロスオリジン iframe を許可し、WebView と `widget.lovi.ai` 間の `postMessage` 通信をブロックしていないことを確認してください。