クイックスタート: ボットをチャットアプリに追加する

[アーティクル]
11/08/2024

Azure Bot Service で使用できる Azure Communication Services チャットメッセージングチャネルを使って、チャットアプリケーションで対話型 AI エクスペリエンスを構築する方法について説明します。このクイックスタートでは、BotFramework SDK を使用してボットを作成します。次に、Communication Services Chat SDK を使用して作成したチャットアプリケーションにボットを統合します。

このクイックスタートでは、次の方法について説明します。

ボットを作成して Azure にデプロイする
Communication Services リソースを取得する
ボットに対して Communication Services のチャットチャネルを有効にする
チャットアプリを作成し、参加者としてボットを追加する
ボットの他の機能を確認する

前提条件

Azure アカウントとアクティブなサブスクリプション。無料でアカウントを作成します。
Visual Studio 2019 以降。
.NET Core の最新バージョン。 (https://dotnet.microsoft.com/download/dotnet/)。
ボットフレームワーク SDK

ボットを作成して Azure にデプロイする

Azure Bot Service のチャネルとして Azure Communication Services のチャットを使うために、まずボットをデプロイします。ボットをデプロイするには、次の手順を実行します。

Azure Bot Service リソースを作成する
ボットのアプリ ID とパスワードを取得する
ボットアプリを保持する Web アプリを作成する
ボットのメッセージングエンドポイントを作成する

Azure で Azure Bot Service のリソースを作成する

まず、Azure portal を使用して Azure Bot Service リソースを作成します。 Communication Services のチャットチャネルでは、シングルテナントボット、マネージド ID ボット、マルチテナントボットがサポートされます。

このクイックスタートの目的では、multitenant ボットを使います。
single-tenant または managed identity ボットの設定については、ボットの ID 情報に関する記事をご覧ください。
managed identity ボットの場合、ボットサービス ID の更新が必要になる場合があります。

ボットのアプリ ID とアプリパスワードを取得する

次に、デプロイ時にボットに割り当てられる Microsoft アプリ ID とパスワードを取得します。これらの値は、後の構成に使用します。

ボットアプリを作成して Web アプリに発行する

ボットは、次のいずれかの方法で作成できます。

Bot Builder のサンプルをご自分のシナリオに合わせて修正し、Web アプリを作成してから、それにボットサンプルをデプロイします。
Bot Builder SDK を使って、ボットを作成し、Web アプリに発行します。

このクイックスタートでは、Bot Builder サンプルの Echo Bot サンプルを使います。

ボットアプリを保持する Web アプリを作成する

Web アプリを作成するには、Azure CLI を使って Azure App Service リソースを作成するか、Azure portal でアプリを作成します。

Azure portal を使用してボット Web アプリを作成するには、次を行います。

ポータルで [リソースの作成] を選択します。検索ボックスに「Web アプリ」と入力します。 [Web アプリ] タイルを選択します。
[Web アプリの作成] で、アプリをデプロイするリージョンなど、アプリの詳細を選択または入力します。
[確認と作成] を選択してデプロイを検証し、デプロイの詳細を確認します。そのうえで [Create](作成) を選択します。
Web アプリリソースが作成されたら、リソースの詳細に表示されているホスト名 URL をコピーします。 URL は Web アプリに作成するエンドポイントの一部になります。

ボットのメッセージングエンドポイントを作成する

通常、Azure Bot Service では、ボットアプリケーションの Web アプリコントローラーによってエンドポイントが /api/messages 形式で公開されることを想定しています。エンドポイントは、ボットに送信されるすべてのメッセージを処理します。

次に、ボットリソースで、Web アプリメッセージングエンドポイントを作成します。

Azure portal で Azure Bot リソースに移動します。 [リソース] メニューで [構成] を選択します。
[構成] の [メッセージングエンドポイント] に、前のセクションでコピーした Web アプリのホスト名 URL を貼り付けます。 URL に /api/messages を追加します。
[保存] を選択します。

Web アプリのデプロイ

ボットを作成する最後の手順は、Web アプリをデプロイすることです。このクイックスタートでは、Echo Bot サンプルを使います。エコーボットの機能は、ユーザー入力のエコーに限定されます。 Azure の Web アプリにデプロイする方法を次に示します。

Git を使用して、この GitHub リポジトリを複製します。

git clone https://github.com/Microsoft/BotBuilder-Samples.git
cd BotBuilder-Samples

Visual Studio で、エコーボットプロジェクトを開きます。
Visual Studio プロジェクトで、Appsettings.json ファイルを開きます。前にコピーした Microsoft アプリ ID とアプリパスワードを貼り付けます。
```
   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "<App-registration-ID>",
     "MicrosoftAppPassword": "<App-password>",
       "MicrosoftAppTenantId": ""
   }
```
次に、C# ボットの場合は Visual Studio または VS Code を使ってボットをデプロイします。

また、コマンドプロンプトウィンドウを使用して Azure ボットをデプロイすることもできます。
Visual Studio のソリューションエクスプローラーで、[EchoBot] プロジェクトを右クリックし、[発行] を選択します。
[新規] を選択して、新しい発行プロファイルを作成します。 [ターゲット] に [Azure] を選択します。

特定のターゲットとして [Azure App Service] を選択します。
デプロイ構成で、Azure アカウントにサインインした後に表示される結果にある Web アプリを選択します。 [完了] を選んでプロファイルを完了し、[発行] を選んでデプロイを開始します。

Communication Services リソースを取得する

ボットが作成されてデプロイされたので、Communication Services チャネルの設定に使用する Communication Services リソースを作成します。

Communication Services リソースを作成する手順を実施します。
Communication Services ユーザーを作成し、ユーザーアクセストークンを発行します。スコープは必ずチャットに設定してください。 "トークン文字列とユーザー ID 文字列をコピーします"。

Communication Services のチャットチャネルを有効にする

Communication Services リソースがある場合は、ボットリソースに Communication Services チャネルを設定できます。このプロセスでは、ボットのユーザー ID が生成されます。

Azure portal で Azure Bot リソースに移動します。リソースメニューで [チャネル] を選択します。使用可能なチャネルの一覧で、[Azure Communications Services - チャット] を選択します。
[接続] を選択すると、サブスクリプションで使用可能な Communication Services リソースの一覧が表示されます。
[新しい接続] ウィンドウで、Communication Services チャットリソースを選択し、[適用] を選択します。
リソース詳細が検証されると、ボット ID が [Bot Azure Communication Services Id] 列に表示されます。 Communication Services Chat AddParticipant API を使用して、ボット ID を使用してチャットスレッド内のボットを表すことができます。ボットを参加者としてチャットに追加すると、ボットはチャット関連のアクティビティの受信を開始し、チャットスレッドで応答できます。

チャットアプリを作成し、参加者としてボットを追加する

ボットの Communication Services ID が取得できたので、ボットを参加者とするチャットスレッドを作成できます。

「チャットをアプリに追加する」クイックスタートに従う

「チャットをアプリに追加する」クイックスタートの手順に従って、チャットアプリを作成します。

<Resource_Endpoint> は、「Communication Services リソースを取得する」ステップの Communication Services エンドポイントに置き換えます。
<Access_Token> は、「Communication Services リソースを取得する」ステップのユーザーアクセストークンに置き換えます。
<Access_ID> は、「Communication Services のチャットチャネルを有効にする」ステップのボットの ACS_ID に置き換えます。

C# チャットアプリケーションをローカル環境で実行する

チャットアプリケーションをローカル環境で実行するには、dotnet run コマンドを使います。

dotnet run

"Hello World" というボットからのメッセージをコンソールで受け取るはずです。

出力例:

1730405535010:Hello World

ボットで実行できるその他の機能

ボットは、Communications Services チャットチャネルのユーザーからプレーンテキストメッセージ以外のものも受信できます。ボットがユーザーから受け取ることができるアクティビティには、次のようなものがあります。

会話の更新
メッセージの更新
メッセージの削除
入力インジケーター
イベントアクティビティ
アダプティブカードを含むさまざまな添付ファイル
ボットのチャネルデータ

次のセクションでは、これらの機能を示すサンプルをいくつか示します。

新しいユーザーがスレッドに追加されたときにウェルカムメッセージを送信する

現在の Echo Bot ロジックは、ユーザーからの入力を受け取り、それをエコーバックします。参加者が付け加えた Communication Services イベントに応答するなどのロジックを追加する場合は、次のコードをコピーして EchoBot.cs に貼り付けます。

using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples.Bots
{
    public class EchoBot : ActivityHandler
    {
        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken)
        {
            if (turnContext.Activity.Type == ActivityTypes.Message)
            {
                var replyText = $"Echo: {turnContext.Activity.Text}";
                await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
            }
            else if (ActivityTypes.ConversationUpdate.Equals(turnContext.Activity.Type))
            {
                if (turnContext.Activity.MembersAdded != null)
                {
                    foreach (var member in turnContext.Activity.MembersAdded)
                    {
                        if (member.Id != turnContext.Activity.Recipient.Id)
                        {
                            await turnContext.SendActivityAsync(MessageFactory.Text("Hello and welcome to chat with EchoBot!"), cancellationToken);
                        }
                    }
                }
            }
        }
    }
}

アダプティブカードを送信する

Note

アダプティブカードは、すべてのチャット参加者が Azure Communication Services ユーザーである Azure Communication Services のユースケース内でのみサポートされ、Teams 相互運用のユースケースではサポートされません。

アダプティブカードをチャットスレッドに送信して、エンゲージメントと効率を高めることができます。アダプティブカードは、さまざまな方法でユーザーと通信するのにも役立ちます。ボットアクティビティの添付ファイルとしてカードを追加することで、ボットからアダプティブカードを送信できます。

アダプティブカードを送信する方法の例を次に示します。

var reply = Activity.CreateMessageActivity();
var adaptiveCard = new Attachment()
{
    ContentType = "application/vnd.microsoft.card.adaptive",
    Content = {/* the adaptive card */}
};
reply.Attachments.Add(adaptiveCard);   
await turnContext.SendActivityAsync(reply, cancellationToken);

アダプティブカードのサンプルペイロードを取得するには、「サンプルとテンプレート」を参照してください。

チャットユーザーの場合、Communication Services チャットチャネルは、メッセージに添付ファイルがあることを示すフィールドをメッセージメタデータに追加します。メタデータでは、microsoft.azure.communication.chat.bot.contenttype プロパティは azurebotservice.adaptivecard に設定されます。

アダプティブカードが添付されたチャットメッセージの例を次に示します。

{
    "content": "{\"attachments\":[{\"contentType\":\"application/vnd.microsoft.card.adaptive\",\"content\":{/* the adaptive card */}}]}",
    "senderDisplayName": "BotDisplayName",
    "metadata": {
    "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"
    },
 "messageType": "Text"
}

ユーザーからボットへのメッセージの送信

テキストメッセージを別のユーザーに送信するのと同じ方法で、ユーザーからボットに基本的なテキストメッセージを送信できます。

ただし、ユーザーからボットに添付ファイルを含むメッセージを送信する場合、Communication Services チャットのメタデータにこのフラグを追加します。

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard"

ユーザーからボットにイベントアクティビティを送信するには、Communication Services チャットメタデータに次のフラグを追加します。

"microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event"

次のセクションでは、ユーザーからボットへのチャットメッセージのサンプル形式を示します。

単純なテキストメッセージ

{
    "content":"Simple text message",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{
        "text":"random text",
        "key1":"value1",
        "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n
        "}, 
    "messageType": "Text"
}

添付ファイルを含むメッセージ

{
    "content": "{
                        \"text\":\"sample text\", 
                        \"attachments\": [{
                            \"contentType\":\"application/vnd.microsoft.card.adaptive\",
                            \"content\": { \"*adaptive card payload*\" }
                        }]
        }",
    "senderDisplayName": "Acs-Dev-Bot",
    "metadata": {
        "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.adaptivecard",
        "text": "random text",
        "key1": "value1",
        "key2": "{\r\n  \"subkey1\": \"subValue1\"\r\n}"
    },
        "messageType": "Text"
}

イベントアクティビティを含むメッセージ

イベントペイロードには、Name を除くすべての JSON フィールドがメッセージコンテンツに含まれます。 Name フィールドには、イベントの名前が含まれています。

次の例では、ペイロード "{field1":"value1", "field2": { "nestedField":"nestedValue" }} を含むイベント名 endOfConversation がボットに送信されます。

{
    "content":"{
                   \"name\":\"endOfConversation\",
                   \"field1\":\"value1\",
                   \"field2\": {  
                       \"nestedField\":\"nestedValue\"
                    }
               }",
    "senderDisplayName":"Acs-Dev-Bot",
    "metadata":{  
                   "microsoft.azure.communication.chat.bot.contenttype": "azurebotservice.event",
                   "text":"random text",
                   "key1":"value1",
                   "key2":"{\r\n  \"subkey1\": \"subValue1\"\r\n}"
               },
    "messageType": "Text"
}

メタデータフィールド microsoft.azure.communication.chat.bot.contenttype は、ユーザーからボットに送信されるメッセージでのみ必要です。

サポートされているボットアクティビティフィールド

次のセクションでは、ボットからユーザーへのフローとユーザーからボットへのフローでサポートされているボットアクティビティフィールドについて説明します。

ボットからユーザーへのフロー

ボットからユーザーへのフローでは、次のボットアクティビティフィールドがサポートされています。

Activities

Message
Typing (入力)

メッセージアクティビティフィールド

Text
Attachments
AttachmentLayout
SuggestedActions
From.Name (Communication Services SenderDisplayName に変換されます)。
ChannelData (Communication Services Chat Metadata に変換されます。ChannelData のマッピング値がオブジェクトの場合、JSON 形式でシリアル化され、文字列として送信されます)。

ユーザーからボットへのフロー

これらのボットアクティビティフィールドは、ユーザーからボットへのフローでサポートされています。

アクティビティとフィールド

Message
- Id (Communication Services チャットメッセージ ID)
- TimeStamp
- Text
- Attachments
会話の更新
- MembersAdded
- MembersRemoved
- TopicName
メッセージの更新
- Id (更新された Communication Services チャットメッセージ ID)
- Text
- Attachments
メッセージの削除
- Id (削除された Communication Services チャットメッセージ ID)
イベント
- Name
- Value
Typing (入力)

その他の共通フィールド

Recipient.Id と Recipient.Name (Communication Services チャットユーザー ID と表示名)
From.Id と From.Name (Communication Services チャットユーザー ID と表示名)
Conversation.Id (Communication Services チャットスレッド ID)
ChannelId (空の場合、Communication Services チャット)
ChannelData (Communication Services チャットメッセージメタデータ)

ボットのハンドオフパターン

ボットが質問を理解していない場合や、質問に回答できない場合があります。顧客はチャットで人間のエージェントへの接続を求める場合があります。これらのシナリオでは、チャットスレッドをボットから人間のエージェントに渡す必要があります。ボットから人間へ会話を移行するようにアプリケーションを設計できます。

ボット間通信の処理

一部の場合、2 つのボットを同じチャットスレッドに追加して異なるサービスを提供するようなユースケースがあります。このシナリオでは、ボットが別のボットのメッセージに自動応答を送信しないようにする必要がある場合があります。適切に処理されないと、ボット同士の自動的な相互作用により、メッセージが無限ループに陥る可能性があります。

アクティビティの From.Id プロパティで、メッセージ送信者の Communication Services ユーザー ID を確認できます。別のボットに属しているかどうかを確認します。次に、ボット間の通信フローを防ぐために必要なアクションを実行します。この種のシナリオで通話量が多くなる場合、Communication Services チャットチャネルは要求を調整し、ボットはメッセージを送受信できません。

スロットル制限の詳細について参照してください。

トラブルシューティング

以下のセクションでは、一般的なシナリオのトラブルシューティング方法について説明します。

チャットチャネルを追加できない

Microsoft Bot Framework 開発者ポータルで、[構成]>[ボットメッセージング] に移動して、エンドポイントが正しく設定されていることを確認します。

ボットがメッセージに返信するときに、"許可されていません" の例外が発生する

ボットの Microsoft アプリ ID とパスワードが、Web アプリにアップロードしたボット構成ファイルに正しく保存されていることを確認します。

ボットを参加者として追加できない

チャットスレッドにボットを追加する要求が送信されたときに、ボットの Communication Services ID が正しく使われていることを確認します。

次の方法で共有

クイックスタート: ボットをチャットアプリに追加する

前提条件

ボットを作成して Azure にデプロイする

Azure で Azure Bot Service のリソースを作成する

ボットのアプリ ID とアプリパスワードを取得する

ボットアプリを作成して Web アプリに発行する

ボットアプリを保持する Web アプリを作成する

ボットのメッセージングエンドポイントを作成する

Web アプリのデプロイ

Communication Services リソースを取得する

Communication Services のチャットチャネルを有効にする

チャットアプリを作成し、参加者としてボットを追加する

「チャットをアプリに追加する」クイックスタートに従う

C# チャットアプリケーションをローカル環境で実行する

ボットで実行できるその他の機能

新しいユーザーがスレッドに追加されたときにウェルカムメッセージを送信する

アダプティブカードを送信する

ユーザーからボットへのメッセージの送信

単純なテキストメッセージ

添付ファイルを含むメッセージ

イベントアクティビティを含むメッセージ

サポートされているボットアクティビティフィールド

ボットからユーザーへのフロー

Activities

メッセージアクティビティフィールド

ユーザーからボットへのフロー

アクティビティとフィールド

その他の共通フィールド

ボットのハンドオフパターン

ボット間通信の処理

トラブルシューティング

チャットチャネルを追加できない

ボットがメッセージに返信するときに、"許可されていません" の例外が発生する

ボットを参加者として追加できない

フィードバック

その他のリソース

次の方法で共有

クイック スタート: ボットをチャット アプリに追加する

前提条件

ボットを作成して Azure にデプロイする

Azure で Azure Bot Service のリソースを作成する

ボットのアプリ ID とアプリ パスワードを取得する

ボット アプリを作成して Web アプリに発行する

ボット アプリを保持する Web アプリを作成する

ボットのメッセージング エンドポイントを作成する

Web アプリのデプロイ

Communication Services リソースを取得する

Communication Services のチャット チャネルを有効にする

チャット アプリを作成し、参加者としてボットを追加する

「チャットをアプリに追加する」クイックスタートに従う

C# チャット アプリケーションをローカル環境で実行する

ボットで実行できるその他の機能

新しいユーザーがスレッドに追加されたときにウェルカム メッセージを送信する

アダプティブ カードを送信する

ユーザーからボットへのメッセージの送信

単純なテキスト メッセージ

添付ファイルを含むメッセージ

イベント アクティビティを含むメッセージ

サポートされているボット アクティビティ フィールド

ボットからユーザーへのフロー

Activities

メッセージ アクティビティ フィールド

ユーザーからボットへのフロー

アクティビティとフィールド

その他の共通フィールド

ボットのハンドオフ パターン

ボット間通信の処理

トラブルシューティング

チャット チャネルを追加できない

ボットがメッセージに返信するときに、"許可されていません" の例外が発生する

ボットを参加者として追加できない

フィードバック

その他のリソース

クイックスタート: ボットをチャットアプリに追加する

ボットのアプリ ID とアプリパスワードを取得する

ボットアプリを作成して Web アプリに発行する

ボットアプリを保持する Web アプリを作成する

ボットのメッセージングエンドポイントを作成する

Communication Services のチャットチャネルを有効にする

チャットアプリを作成し、参加者としてボットを追加する

C# チャットアプリケーションをローカル環境で実行する

新しいユーザーがスレッドに追加されたときにウェルカムメッセージを送信する

アダプティブカードを送信する

単純なテキストメッセージ

イベントアクティビティを含むメッセージ

サポートされているボットアクティビティフィールド

メッセージアクティビティフィールド

ボットのハンドオフパターン

チャットチャネルを追加できない