エージェントのルックアンドフィールのカスタマイズ

[アーティクル]
03/05/2025

エージェントのキャンバスによって、そのルック&フィールが決まります。キャンバスは、必要な変更の複雑さに応じて、2 つの方法でカスタマイズできます:

エージェントを展開する Web サイト用の HTML コードで JavaScript のスタイルを使用して、既定のキャンバスをカスタマイズできます。
このアプローチは、コード開発に投資せずに小さなカスタマイズを実行する場合に役立ちます。
Bot Framework Web チャットキャンバスに基づいて、カスタムキャンバスを使用します。
このアプローチには、広範な開発者の知識が必要です。完全にカスタマイズされたエクスペリエンスが必要な組織に役立ちます。

重要

この記事に含まれているサンプルコードは、Copilot Studio でのみ使用するためにインストールして使用できます。サンプルコードは "現状のまま" ライセンスされており、任意のサービスレベル契約やサポートサービスから除外されています。お客様は、その使用に関するリスクを負うものとします。

Microsoft は、明示的な責任や保証責任または条件を一切負いません。また商品性、特定目的に対する適合性、非侵害性に関するいかなる黙示的保証も除外します。

Web アプリケーション
Teams

作成してエージェントを公開にした後、顧客はエージェントの Web チャットキャンバスを使用して操作できます。

会話を自動的に開始するようにエージェントを構成するを使用して、カスタマイズされたキャンバスを結合することもできます。

最後に、ポータルから直接エージェントの名前とアイコンを変更 (エージェントが Microsoft Teams で共有されている場合) できます。

エージェントの名前とアイコンを変更する

重要

エージェントが Customer Service 用オムニチャネルに接続している場合、その名前は Azure portal 登録の 表示名 プロパティによって定義されます。

エージェントの名前とアイコンを変更することができます。これは、エージェントを公開するすべてのチャネルのアイコンに影響します。

ナビゲーションメニューの設定で詳細を選択します。
エージェントの名前とアイコンを変更します。 Microsoft Teams アイコン形式に関するレコメンデーションを確認します。
保存を選択して変更をコミットします。

重要

エージェントのアイコンを更新した後、新しいアイコンがあらゆるところに表示されるまでは、最大 24 時間かかる場合があります。

トークンエンドポイントを取得する

キャンバスをカスタマイズするには、既定のキャンバスまたは接続するユーザー定義キャンバスでも、エージェントの詳細を取得する必要があります。

ナビゲーションメニューの設定で チャネル を選択します。
モバイルアプリを選択します。
トークンエンドポイントの隣で、コピーを選択します。

既定のキャンバスをカスタマイズする (簡易)

いくつかの簡易な CSS および JavaScript スタイルオプションを使用して、チャットキャンバスの外観を構成します。

最初に、エージェントキャンバスを展開する場所を構成する必要があります。

エージェントを作成して公開します。

次の HTML コードをコピーして貼り付け、index.html と名前を付けて保存します。
次のコードもコピーして、w3schools.com HTML 試用版エディターに貼り付けることができます。トークンエンドポイントをまだ追加する必要があります。

 <!doctype html>
 <html lang="en">
   <head>
     <title>Contoso Sample Web Chat</title>
     <!--
       This styling is for the Web Chat demonstration purposes.
       It is recommended that style is moved to a separate file for organization in larger projects.

       Please visit https://github.com/microsoft/BotFramework-WebChat for details about Web Chat.
     -->
     <style>
       html,
       body {
         height: 100%;
       }

       body {
         margin: 0;
       }

       h1 {
         color: whitesmoke;
         font-family: Segoe UI;
         font-size: 16px;
         line-height: 20px;
         margin: 0;
         padding: 0 20px;
       }

       #banner {
         align-items: center;
         background-color: black;
         display: flex;
         height: 50px;
       }

       #webchat {
         height: calc(100% - 50px);
         overflow: hidden;
         position: fixed;
         top: 50px;
         width: 100%;
       }
     </style>
   </head>
   <body>
     <div>
       <div id="banner">
         <h1>Contoso agent name</h1>
       </div>
       <div id="webchat" role="main"></div>
     </div>

     <!--
       In this sample, the latest version of Web Chat is being used.
       In production environment, the version number should be pinned and version bump should be done frequently.

       Please visit https://github.com/microsoft/BotFramework-WebChat/tree/main/CHANGELOG.md for changelog.
     -->
     <script crossorigin="anonymous" src="https://cdn.botframework.com/botframework-webchat/latest/webchat.js"></script>

     <script>
       (async function () {
         // Specifies style options to customize the Web Chat canvas.
         // Please visit https://microsoft.github.io/BotFramework-WebChat for customization samples.
         const styleOptions = {
           // Hide upload button.
           hideUploadButton: true
         };

         // Specifies the token endpoint URL.
         // To get this value, visit Copilot Studio > Settings > Channels > Mobile app page.
         const tokenEndpointURL = new URL('<AGENT TOKEN ENDPOINT>');

         // Specifies the language the agent and Web Chat should display in:
         // - (Recommended) To match the page language, set it to document.documentElement.lang
         // - To use current user language, set it to navigator.language with a fallback language
         // - To use another language, set it to supported Unicode locale

         // Setting page language is highly recommended.
         // When page language is set, browsers will use native font for the respective language.

         const locale = document.documentElement.lang || 'en'; // Uses language specified in <html> element and fallback to English (United States).
         // const locale = navigator.language || 'ja-JP'; // Uses user preferred language and fallback to Japanese.
         // const locale = 'zh-HAnt'; // Always use Chinese (Traditional).

         const apiVersion = tokenEndpointURL.searchParams.get('api-version');

         const [directLineURL, token] = await Promise.all([
           fetch(new URL(`/powervirtualagents/regionalchannelsettings?api-version=${apiVersion}`, tokenEndpointURL))
             .then(response => {
               if (!response.ok) {
                 throw new Error('Failed to retrieve regional channel settings.');
               }

               return response.json();
             })
             .then(({ channelUrlsById: { directline } }) => directline),
           fetch(tokenEndpointURL)
             .then(response => {
               if (!response.ok) {
                 throw new Error('Failed to retrieve Direct Line token.');
               }

               return response.json();
             })
             .then(({ token }) => token)
         ]);

         // The "token" variable is the credentials for accessing the current conversation.
         // To maintain conversation across page navigation, save and reuse the token.

         // The token could have access to sensitive information about the user.
         // It must be treated like user password.

         const directLine = WebChat.createDirectLine({ domain: new URL('v3/directline', directLineURL), token });

         // Sends "startConversation" event when the connection is established.

         const subscription = directLine.connectionStatus$.subscribe({
           next(value) {
             if (value === 2) {
               directLine
                 .postActivity({
                   localTimezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
                   locale,
                   name: 'startConversation',
                   type: 'event'
                 })
                 .subscribe();

               // Only send the event once, unsubscribe after the event is sent.
               subscription.unsubscribe();
             }
           }
         });

         WebChat.renderWebChat({ directLine, locale, styleOptions }, document.getElementById('webchat'));
       })();
     </script>
   </body>
 </html>

作成した index.html ファイルで、const tokenEndpointURL = "<YOUR TOKEN ENDPOINT>"; の行にトークンエンドポイントを入力します。
最新のブラウザー (たとえば、Microsoft Edge) を使用して index.html を開き、カスタムキャンバスでエージェントを開きます。
エージェントをテストして、エージェントから応答を受信していることと、エージェントが正常に機能していることを確認します。

問題が発生した場合は、エージェントを公開したこと、およびトークンエンドポイントが適切な場所に挿入されていることを確認してください。ボット ID は const tokenEndpointURL = "<YOUR TOKEN ENDPOINT>" の行の等号 (=) の後にあり、二重引用符 (") で囲む必要があります。

エージェントのアイコン、背景色、名前をカスタマイズする

カスタマイズされたキャンバスをエージェントで操作できるようになったら、それを変更できます。

JavaScript styleOptions オプションを使用して、いくつかの事前定義されたスタイルを設定できます。

defaultStyleOptions.js ファイルへのリンク、およびカスタマイズできるものとそれがどのように表示されるかの詳細については、Web チャットのカスタマイズをご覧ください。

エージェントアイコンを変更する

次のサンプルコードを使用して index.html ファイルを更新します。

const styleOptions = {
  accent: '#00809d',
  botAvatarBackgroundColor: '#FFFFFF',
  botAvatarImage: 'https://learn.microsoft.com/azure/bot-service/v4sdk/media/logo_bot.svg',
  botAvatarInitials: 'BT',
  userAvatarImage: 'https://avatars.githubusercontent.com/u/661465'
};

エージェントとユーザーのアバター画像を会社の画像に置き換えます。
画像 URL がない場合は、代わりに Base64 エンコードされた画像文字列を使用できます。

背景の色の変更

次のサンプルコードを使用して index.html ファイルを更新します。
```
const styleOptions = {
  backgroundColor: 'lightgray'
};  
```
backgroundColor を好きな色に変更します。標準の CSS の色の名前、RGB 値、または HEX を使用できます。

エージェント名を変更する

次のものを使用して index.html ファイルで <h1> テキストを更新します。

<body>
  <div id="banner">
    <h1><img src="contosocopilot-teams.png"> Contoso agent name</h1>
  </div>

テキストをエージェントを呼び出すものに変更します。画像を挿入することもできますが、見出しセクション内に収まるようにスタイル設定する必要があります。

チャットキャンバスをカスタマイズおよびホストする (詳細)

スタンドアロン Web アプリとしてホストされるユーザー定義キャンバスを使用して、Copilot Studio エージェントを接続できます。このオプションは、複数の Web ページにわたりカスタマイズした iFrame を埋め込む必要がある場合に最適です。

注意

ユーザー定義キャンバスをホストするには、ソフトウェア開発が必要です。ここに示すガイダンスは、開発者ツール、ユーティリティ、および IDE を十分に理解している IT 管理者または開発者などの経験豊富な IT プロフェッショナルを対象としています。

カスタマイズするサンプルを選択する

Copilot Studio で動作するようカスタムビルドされたこれらのサンプルの 1 つから始めることをお勧めします:

完全なバンドルは、Copilot Studio からのすべてのリッチコンテンツを表示できるユーザー定義キャンバスです。例:
場所とファイルのアップロードは、ユーザーの位置を取得し、Copilot Studio エージェントに送信できるカスタムキャンバスです。例:

または、Bot Framework により提供されたその他のサンプル Web チャットキャンバスから選ぶことができます。

`styleSetOptions` を使用してキャンバスをカスタマイズする

既定のキャンバスのカスタマイズと同様に、styleSetOptions を使用してユーザー定義キャンバスをカスタマイズできます。カスタマイズ可能なすべてのプロパティは、defaultStyleOptions.js に一覧表示されます。カスタマイズできるものとその外観の詳細については、Web チャットのカスタマイズを参照してください。

カスタマイズされたキャンバスを展開する

ユーザー定義キャンバスをホストするには、すべてのファイルを Web アプリに展開します。

次の方法で共有

エージェントのルックアンドフィールのカスタマイズ

エージェントの名前とアイコンを変更する

トークンエンドポイントを取得する

既定のキャンバスをカスタマイズする (簡易)

エージェントのアイコン、背景色、名前をカスタマイズする

エージェントアイコンを変更する

背景の色の変更

エージェント名を変更する

チャットキャンバスをカスタマイズおよびホストする (詳細)

カスタマイズするサンプルを選択する

`styleSetOptions` を使用してキャンバスをカスタマイズする

カスタマイズされたキャンバスを展開する

エージェントのアバターアイコンと名前を変更する

エージェントの色、説明を変更する

フィードバック

その他のリソース

次の方法で共有

エージェントのルック アンド フィールのカスタマイズ

エージェントの名前とアイコンを変更する

トークン エンドポイントを取得する

既定のキャンバスをカスタマイズする (簡易)

エージェントのアイコン、背景色、名前をカスタマイズする

エージェント アイコンを変更する

背景の色の変更

エージェント名を変更する

チャット キャンバスをカスタマイズおよびホストする (詳細)

カスタマイズするサンプルを選択する

styleSetOptions を使用してキャンバスをカスタマイズする

カスタマイズされたキャンバスを展開する

関連するコンテンツ

フィードバック

その他のリソース

エージェントのルックアンドフィールのカスタマイズ

トークンエンドポイントを取得する

エージェントアイコンを変更する

チャットキャンバスをカスタマイズおよびホストする (詳細)

`styleSetOptions` を使用してキャンバスをカスタマイズする