> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/ja/build/conversation-settings/platform-settings/basic-settings.md).

# 基本設定

Web チャットプラットフォームの基本設定：プラットフォーム名、連携する Agent、戻り先 URL、カスタムドメイン、埋め込みを許可するドメイン、公開アクセス URL と 3 種類の埋め込み方法、および API プラットフォームの Web Chat ID の確認場所を説明します。

<mark style="color:blue;">基本設定</mark>は、チャットプラットフォーム設定ページの「一般」グループの最初のカテゴリで、このプラットフォームの「名前」「連携する Agent」「サービスを提供する URL」を決定します。このページでは Web プラットフォームのすべての項目を説明します。LINE や Microsoft Teams などのメッセージングプラットフォームの基本設定は、そのプラットフォームの認証情報の入力項目です。該当する「チャットプラットフォームの連携」ページをご覧ください。設定ページ全体の構成と開き方については、[チャットプラットフォーム設定の概要](/maiagent-user-guide/ja/build/conversation-settings/platform-settings.md)をご覧ください。

{% hint style="info" %}
**ガイドのナビゲーション**：このページはチャットプラットフォーム設定の手順の 1 つです。テキストカスタマーサービスの公開までの全体の流れは [テキストカスタマーサービス：ゼロから公開まで](/maiagent-user-guide/ja/serve/text-service.md)、音声カスタマーサービスは [音声カスタマーサービス：ゼロから公開まで](/maiagent-user-guide/ja/serve/voice.md)をご覧ください。
{% endhint %}

## 一、利用する場面 <a href="#when-to-use" id="when-to-use"></a>

マーケティング担当者が、自社の AI カスタマーサービスを公式サイトに設置したいとします。担当者は Web プラットフォームの<mark style="color:blue;">基本設定</mark>を開き、名前を「サポートアシスタント」に変更し、連携している Agent が「製品相談アシスタント」であることを確認します。<mark style="color:blue;">戻り先 URL</mark> に公式サイトのトップページを入力し、<mark style="color:blue;">埋め込みを許可するドメイン</mark>に `*.my-company.com` を追加します。保存後に<mark style="color:blue;">埋め込み</mark>をクリックして JavaScript コードをコピーし、サイトのエンジニアに渡します。公開後は自社のサイトだけがこのカスタマーサービスを読み込めるため、他の人がコードをコピーしても利用できません。

## 二、項目の説明 <a href="#fields" id="fields"></a>

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-8b1e203abe16f045412157499f71caf17674cb29%2Fplatform-basic-settings.png?alt=media" alt="Web プラットフォームの基本設定：名前、Agent、戻り先 URL、カスタムドメイン、埋め込みを許可するドメイン、公開アクセス URL"><figcaption><p>Web プラットフォームの基本設定</p></figcaption></figure>

| 項目                   | 説明                                                                                                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **名前**               | チャットウィンドウのタイトルバーに表示される名前です（例：「サポートアシスタント」）。必須です                                                                                                                                                                                                  |
| **説明**               | この Agent が何をサポートできるかを簡単に紹介します（最大 100 文字）。[Agent マーケット](/maiagent-user-guide/ja/work/built-in-agents/management.md)の「組織作成」タブにある Agent カードと、共有リンクのプレビューに表示されます。空欄の場合、カードにはデフォルトの文言が表示されます。Web サイトと社内向けチャットプラットフォームにはこの項目がありますが、API プラットフォームにはありません |
| **AI アシスタント**        | このプラットフォームで回答する Agent です。同じ Agent を複数のプラットフォームに接続できます                                                                                                                                                                                            |
| **戻り先 URL**          | ユーザーがチャットウィンドウで戻るをクリックしたときに移動する URL です。通常は公式サイトのトップページを入力します                                                                                                                                                                                     |
| **カスタムドメイン (CNAME)** | 自社のドメインでチャットページを提供します。[第三節](#custom-domain)をご覧ください                                                                                                                                                                                               |
| **埋め込みを許可するドメイン**    | 埋め込みの許可リストです。[第四節](#allowed-embed-origins)をご覧ください                                                                                                                                                                                                |
| **公開アクセス URL**       | システムが自動生成するチャットページの URL です。そのまま共有または埋め込みができます。[第五節](#public-url-and-embed)をご覧ください                                                                                                                                                                |

### 名前と Agent <a href="#name-and-agent" id="name-and-agent"></a>

<mark style="color:blue;">名前</mark>にサイトに表示したい名前を入力し、<mark style="color:blue;">AI アシスタント</mark>のドロップダウンから質問に回答する Agent を選択します。Agent を切り替えるとすぐに反映され、チャットウィンドウを埋め込み直す必要はありません。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-b51d95e2e16cbd042aa3b0b1c86f72f8923b0439%2F%E5%90%8D%E7%A8%B1display.png?alt=media" alt="チャットウィンドウのタイトルバーにプラットフォーム名が表示される"><figcaption><p>プラットフォーム名はチャットウィンドウのタイトルバーに表示されます</p></figcaption></figure>

### 戻り先 URL <a href="#return-url" id="return-url"></a>

自社サイトの URL を入力すると、ユーザーが全画面のチャットページで戻るをクリックしたときにこの URL へ移動します。埋め込みプレビューでも、この URL が背景として使用されます。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-63ec964871ee05c4285511fbc4b922d35405803b%2F%E5%9F%BA%E6%9C%AC%E8%A8%AD%E5%AE%9A%20-%20%E5%B5%8C%E5%85%A5%E9%A0%90%E8%A6%BD%20%E8%BF%94%E5%9B%9E%E7%B6%B2%E5%9D%80%20(1)%20(1).png?alt=media" alt="埋め込みプレビューは戻り先 URL のサイトを背景にする"><figcaption><p>戻り先 URL を追加すると、埋め込みプレビューにそのサイトが背景として表示されます</p></figcaption></figure>

## 三、カスタムドメイン (CNAME) <a href="#custom-domain" id="custom-domain"></a>

デフォルトの公開アクセス URL は `chat.maiagent.ai` 配下です。チャットページに自社のドメイン（例：`chat.my-company.com`）を使いたい場合は、<mark style="color:blue;">カスタムドメイン (CNAME)</mark> にそのドメインを入力して保存してください。システムがそのドメインの証明書を申請し、振り分けを作成します。保存後、入力項目の横に<mark style="color:blue;">ドメインステータス</mark>が表示されます。

| ステータス        | 意味                                    | 対応                                   |
| ------------ | ------------------------------------- | ------------------------------------ |
| **確認中**      | システムが振り分けと証明書を作成しています                 | 数分待ってから再読み込みしてください                   |
| **DNS 未準備**  | お客様の DNS がまだそのドメインを MaiAgent に向けていません | DNS サービス事業者で CNAME レコードを追加してください     |
| **証明書未準備**   | DNS は向いていますが、証明書は発行中です                | 待機してください。通常は数分以内に完了します               |
| **DNS 設定異常** | 以前は有効でしたが、DNS レコードが変更または削除されました       | DNS サービス事業者の CNAME レコードを確認してください     |
| **有効**       | お客様のドメインでチャットページを開けます                 | 公開アクセス URL と埋め込みコードがお客様のドメインに切り替わります |

{% hint style="info" %}
CNAME レコードの向け先アドレスは環境によって異なりますので、[サポートセンター](https://helpdesk.maiagent.ai/)にお問い合わせください。入力項目を空にして保存すると、カスタムドメインを削除でき、チャットページはデフォルトの URL に戻ります。
{% endhint %}

## 四、埋め込みを許可するドメイン <a href="#allowed-embed-origins" id="allowed-embed-origins"></a>

### これは何ですか？ <a href="#embed-origins-overview" id="embed-origins-overview"></a>

<mark style="color:blue;">埋め込みを許可するドメイン</mark>は「埋め込みの許可リスト」です。入力すると、リストにあるサイトだけがこの Web チャットを埋め込めるようになり、それ以外のサイトに設置された埋め込みコードは無効になります。

有効にするのが適しているケース：

* **無断埋め込みの防止**：第三者のサイトが埋め込みコードをコピーし、お客様のカスタマーサービスボットを自社のページに埋め込んで、会話の利用枠を消費することが心配な場合
* **セキュリティコンプライアンス**：自社またはお客様のセキュリティポリシーで、「どのサイトがこのカスタマーサービスのウィジェットを読み込めるか」を管理することが求められている場合

{% hint style="info" %}
これは高度なセキュリティ設定です。**上記のような要件がない場合は、リストを空のままにしてください。** リストが空の場合、どのサイトでもこの Web チャットを埋め込めます。
{% endhint %}

### 動作の仕組み <a href="#embed-origins-behavior" id="embed-origins-behavior"></a>

| リストの状態   | 動作                                                          |
| -------- | ----------------------------------------------------------- |
| 空（デフォルト） | 制限なし。どのサイトでもこの Web チャットを埋め込めます                              |
| 空ではない    | 許可リストモード：ブラウザーが他のドメインからの埋め込みをブロックし、SDK もその setup 呼び出しを拒否します |

* **ブロックされたドメインが埋め込んだ場合**：そのページのチャットウィジェットは初期化を完了せず、訪問者は会話を開始できません
* **公開アクセス URL を直接開く訪問者**：この設定は「埋め込み」だけを制限するため、公開 URL からチャットページを直接開く訪問者には影響しません
* **セキュリティ機構は「検証できなければ拒否」を採用しています**：リストが空でない場合、オリジン検証を通過できない埋め込みはすべて拒否されます。ドメインの入力ミスや、オリジン検証に対応していない旧バージョンの埋め込みスクリプトを使用している埋め込みページも含まれます

### 設定手順 <a href="#embed-origins-setup" id="embed-origins-setup"></a>

{% stepper %}
{% step %}

### 項目を見つける <a href="#embed-origins-step-navigate" id="embed-origins-step-navigate"></a>

<mark style="color:blue;">基本設定</mark>で<mark style="color:blue;">埋め込みを許可するドメイン</mark>を見つけ、<mark style="color:blue;">＋ 追加</mark>をクリックします。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-2c6dc13d0e37a07d6f539d493f1e1493d018dcfb%2Fwebchat-basic-allowed-origins.png?alt=media" alt="基本設定の「埋め込みを許可するドメイン」項目"><figcaption><p>基本設定の「埋め込みを許可するドメイン」項目</p></figcaption></figure>
{% endstep %}

{% step %}

### ドメインを追加する <a href="#embed-origins-step-add" id="embed-origins-step-add"></a>

各エントリは、正確なオリジン（`https://example.com`）またはワイルドカードドメイン（`*.example.com`。example.com とそのすべてのサブドメインに一致します）のいずれかです。

| 書き方                         | 説明                                                             |
| --------------------------- | -------------------------------------------------------------- |
| ✅ `https://www.example.com` | 正確なオリジン：このアドレス（プロトコルを含む）のページだけが埋め込めます                          |
| ✅ `*.example.com`           | ワイルドカードドメイン：example.com とそのすべてのサブドメイン（www、shop、blog など）が埋め込めます |
| ❌ `example.com`             | 正確なオリジンにはプロトコルが必要です。`https://` がないと有効になりません                    |
| ❌ `*.com`                   | 範囲が広すぎます。すべての .com サイトに開放することになり、許可リストの意味がなくなります               |
| {% endstep %}               |                                                                |

{% step %}

### 保存して確認する <a href="#embed-origins-step-save" id="embed-origins-step-save"></a>

設定を保存したら約 1 分待ち、リストにあるサイトの埋め込みページを再読み込みして、チャットウィンドウで引き続き問題なく会話を開始できることを確認します。

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-856c495d2fb9896943ac455178eed55a38f15a0e%2Fembed-origins-01-filled-list.png?alt=media" alt="ドメインを入力済みの「埋め込みを許可するドメイン」項目"><figcaption><p>正確なオリジンとワイルドカードドメインを入力したリストの例</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 有効化前のチェックリスト <a href="#embed-origins-checklist" id="embed-origins-checklist"></a>

{% hint style="warning" %}
リストが空でなくなると、リストにないすべての埋め込みがブロックされます。「入力した途端にすべてブロックされる」事態を避けるため、有効にする前に次の点を順に確認してください。

1. **この Web チャットを埋め込むすべてのドメインを洗い出す**：本番サイト、テスト環境、プレビュー環境を含め、1 つも漏らさないでください
2. **最新の埋め込みコードを再取得する**：以前に取得した埋め込みスクリプトはオリジン検証に対応していない場合があり、リストを有効にすると一律で拒否されます。<mark style="color:blue;">埋め込み</mark>からコードをコピーし直し、サイトを更新することをおすすめします
3. **先に追加し、削除は後で**：初めて有効にするときは、すべてのドメインを追加しきってください。有効化しながら整理しないでください
4. **1 つずつ確認する**：保存後、各埋め込みページで実際に会話を開き、すべて正常であることを確認してください
5. **元に戻す手段を残す**：有効化後に埋め込み側で会話を作成できない場合は、リストを空にして保存してください。約 1 分後に制限なしの状態に戻ります
   {% endhint %}

### よくある質問 <a href="#embed-origins-faq" id="embed-origins-faq"></a>

**Q：設定はどのくらいで反映されますか？**

保存後、通常は約 1 分以内に反映されます。その後、すでに開いている埋め込みページを再読み込みすると新しい設定が適用されます。

**Q：サブドメインが多い場合、1 つずつ列挙する必要がありますか？**

必要ありません。`*.example.com` の 1 件で、example.com とそのすべてのサブドメインに一致します。

**Q：この設定で防げることと、防げないことは何ですか？**

これは「埋め込み層」の保護で、他のサイトがこの Web チャットを自分のページに埋め込むことを防げます。ユーザー認証ではないため、公開アクセス URL を知っている人は、チャットページを直接開いて会話できます。「誰が会話できるか」を管理したい場合は、[ログイン設定](/maiagent-user-guide/ja/build/choose-channel/web-chat/website.md#login-settings)と組み合わせてご利用ください。

**Q：設定を間違えて、すべての埋め込み側で会話できなくなった場合はどうすればよいですか？**

<mark style="color:blue;">埋め込みを許可するドメイン</mark>のリストを空にして保存してください。約 1 分後に制限なしの状態に戻りますので、その後ドメインの書き方を再確認してください。

## 五、公開アクセス URL と埋め込み <a href="#public-url-and-embed" id="public-url-and-embed"></a>

ページ下部の<mark style="color:blue;">公開アクセス URL</mark>は、システムが自動生成するチャットページの URL です。横にあるアクションボタンは次のとおりです。

| アクション         | 用途                                                                                                                                                                                             |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **コピー**       | URL をコピーします。ユーザーに直接共有したり、QR コードに使用したりできます                                                                                                                                                      |
| **アクセス**      | 新しいタブでチャットページを開き、設定の効果をテストします                                                                                                                                                                  |
| **音声モード**     | 新しいタブで音声チャットページを開きます。連携している Agent で[音声アシスタント](/maiagent-user-guide/ja/build/agent/voice-agent.md)が有効な場合のみ表示されます。公開までの流れは [音声カスタマーサービス：ゼロから公開まで](/maiagent-user-guide/ja/serve/voice.md)をご覧ください |
| **埋め込み**      | 埋め込みコードを取得します。下記の 3 種類の埋め込み方法をご覧ください                                                                                                                                                           |
| **埋め込みプレビュー** | 戻り先 URL のサイトを背景にして、埋め込み後の見え方をプレビューします                                                                                                                                                          |

### 3 種類の埋め込み方法 <a href="#embed-methods" id="embed-methods"></a>

<mark style="color:blue;">埋め込み</mark>をクリックすると、ウィンドウ上部で次の方法を切り替えられます。

* **JavaScript**：`<script>` で読み込みます。最もよく使われる方法で、読み込みと互換性の処理が自動で行われます
* **Iframe**：`<iframe>` で直接埋め込みます。スクリプトを挿入できない環境に適しています
* **MaiGPT**：ChatGPT スタイルの完全なチャットインターフェース（左側に会話履歴、右側にメインのチャットエリア）です。埋め込みページに常駐させることも、右下のフローティングボタンをクリックして全画面に展開することもできます

<mark style="color:blue;">MaiGPT</mark> を選択すると、左側で<mark style="color:blue;">埋め込みコンテナ（targetElement）</mark>、<mark style="color:blue;">言語設定（locale）</mark>、<mark style="color:blue;">タイトル（maigptTitle）</mark>を調整でき、右側の<mark style="color:blue;">コードプレビュー</mark>がリアルタイムで更新されます。<mark style="color:blue;">コピー</mark>をクリックすると、サイトに貼り付けられます。パラメーターの詳細は [MaiGPT ウィンドウモードの埋め込み](/maiagent-user-guide/ja/build/choose-channel/web-chat/maigpt-embed.md)をご覧ください。

### 埋め込みスクリプトの特長 <a href="#embed-script" id="embed-script"></a>

JavaScript の埋め込みで提供される embed.js スクリプトには、次の特長があります。

* **重複実行の防止**：スクリプトが複数回読み込まれても、初期化は 1 回だけです
* **分かりやすいエラーメッセージ**：読み込みに失敗した場合、デバッグしやすいようにエラーメッセージが表示されます
* **サイトの読み込み速度に影響しない**：スクリプトは最適化されています
* **さまざまなサイト環境やフレームワークに対応**

埋め込み時は、次の点をおすすめします。

1. 埋め込みスクリプトは `</body>` タグの直前に配置し、ページの主要なコンテンツが先に読み込まれるようにします
2. 重複を避けるため、埋め込みスクリプトはページに 1 回だけ追加します
3. SPA（Single Page Application）で使用する場合は、技術ドキュメントの詳細設定を参照してください

<figure><img src="https://2584873290-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTvHx8hgwYGDTLD3A7xoW%2Fuploads%2Fgit-blob-5c896d7bb75574c434d11ef560612d20a61eba48%2F%E5%9F%BA%E6%9C%AC%E8%A8%AD%E5%AE%9A%20-%20%E9%81%B7%E5%85%A5%E8%A8%AD%E5%AE%9A%E9%A0%90%E8%A6%BD.png?alt=media" alt="埋め込みプレビュー画面"><figcaption><p>埋め込みプレビュー</p></figcaption></figure>

## 六、API プラットフォームの Web Chat ID <a href="#web-chat-id" id="web-chat-id"></a>

エンジニアが API で会話を作成する際、必須項目の `webChat` には **API プラットフォームの Web Chat ID** を指定します。これは Agent の詳細ページではなく、API プラットフォームの設定ページにあります。

1. <mark style="color:blue;">カスタマーサービス会話</mark> → <mark style="color:blue;">チャットプラットフォーム</mark>に移動し、該当 Agent の <mark style="color:blue;">API</mark> プラットフォーム（Agent の作成時に自動で生成されます）を見つけて、<mark style="color:blue;">編集</mark>をクリックします。
2. 左側のカテゴリナビゲーションの「連携とログイン」グループで、<mark style="color:blue;">Webhook 設定</mark>をクリックします。
3. ページ下部の <mark style="color:blue;">API 情報</mark>カードに <mark style="color:blue;">Web Chat ID</mark>（読み取り専用）が表示されます。右側のコピーボタンをクリックするとコピーできます。

このカードは API プラットフォームにのみあり、Web プラットフォームや社内向けプラットフォームには Web Chat ID の項目はありません。組織全体の Web Chat の一覧と ID を確認するには、エンジニアが `GET /api/v1/web-chats/` を呼び出すこともできます。詳細は技術マニュアルの [会話とメッセージの作成](https://docs.maiagent.ai/tech/api-integration/conversations-and-messages)をご覧ください。

## 七、よくある質問 <a href="#faq" id="faq"></a>

### Q：名前や Agent を変更したら、埋め込み直す必要がありますか？ <a href="#faq-resave" id="faq-resave"></a>

必要ありません。<mark style="color:blue;">保存</mark>を押すとすぐに反映され、埋め込みコードは変わりません。

### Q：同じ Agent を複数の Web プラットフォームに接続できますか？ <a href="#faq-multi-platform" id="faq-multi-platform"></a>

できます。各プラットフォームには、それぞれ名前、外観、機能のオン／オフがあるため、同じ Agent を異なるサイトで異なる見た目で表示したい場合に適しています。<mark style="color:blue;">カスタマーサービス会話</mark> → <mark style="color:blue;">チャットプラットフォーム</mark>で<mark style="color:blue;">チャットプラットフォームを連携</mark>をクリックして追加してください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/ja/build/conversation-settings/platform-settings/basic-settings.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.