次の方法で共有


チャット アプリにボットを追加する

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

この記事では、次の方法について説明します。

前提条件

  • Azure アカウントとアクティブなサブスクリプション。 無料でアカウントを作成します。
  • Visual Studio 2019 以降
  • .NET Core の最新バージョン。 このクイック スタートでは、 .NET Core 3.1 を使用します。 必ず、Visual Studio、32 ビット、または 64 ビットのインスタンスに対応するバージョンをインストールしてください。
  • ボット フレームワーク SDK

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

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

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

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

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

シングルテナントまたはマネージド ID ボットを設定するには、 ボット ID 情報を確認します。

マネージド ID ボットの場合は、 ボット サービス ID の更新が必要になる場合があります。

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

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

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

ボット用の Web アプリを作成するには、シナリオに合わせて Bot Builder サンプル を修正するか、 Bot Builder SDK を使用して Web アプリを作成します。 最も簡単なサンプルの 1 つは Echo Bot です

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

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

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

  1. ポータルで [リソースの作成] を選択します。 検索ボックスに「Web アプリ」と入力します。 [Web アプリ] タイルを選択します。

    Azure portal での Web アプリ リソースの作成を示すスクリーンショット。

  2. [Web アプリの作成] で、アプリをデプロイするリージョンなど、アプリの詳細を選択または入力します。

    Web アプリのデプロイを作成するために設定する詳細を示すスクリーンショット。

  3. [確認と作成] を選択してデプロイを検証し、デプロイの詳細を確認します。 そのうえで [Create](作成) を選択します。

  4. Web アプリ リソースが作成されたら、リソースの詳細に表示されているホスト名 URL をコピーします。 URL は Web アプリに作成するエンドポイントの一部になります。

    Web アプリエンドポイントの URL をコピーする方法を示すスクリーンショット。

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

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

  1. Azure portal で Azure Bot リソースに移動します。 [リソース] メニューで [構成] を選択します。

  2. [構成][メッセージング エンドポイント] に、前のセクションでコピーした Web アプリのホスト名 URL を貼り付けます。 URL に /api/messages を追加します。

  3. [保存] を選択します。

Web アプリのホスト名を使用してボット メッセージング エンドポイントを作成する方法を示すスクリーンショット。

Web アプリのデプロイ

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

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

    git clone https://github.com/Microsoft/BotBuilder-Samples.git
    cd BotBuilder-Samples
    
  2. Visual Studio で、エコー ボット プロジェクトを開きます。

  3. Visual Studio プロジェクトで、Appsettings.json ファイルを開きます。 前にコピーした Microsoft アプリ ID とアプリ パスワードを貼り付けます。

       {
         "MicrosoftAppId": "<App-registration-ID>",
         "MicrosoftAppPassword": "<App-password>"
       }
    

    次に、Visual Studio for C# ボットを使用してボットをデプロイします。

    また、コマンド プロンプト ウィンドウを使用して Azure ボットをデプロイすることもできます。

  4. Visual Studio のソリューション エクスプローラーで、[EchoBot] プロジェクトを右クリックし、[発行] を選択します。

    Visual Studio からの Web アプリの発行示すスクリーンショット。

  5. [新規] を選択して、新しい発行プロファイルを作成します。 [ターゲット][Azure] を選択します。

    新しい発行プロファイルでターゲットとして Azure を選択する方法を示すスクリーンショット。

    特定のターゲットとして [Azure App Service] を選択します。

    特定のターゲットとして Azure App Service を選択する方法を示すスクリーンショット。

  6. デプロイ構成で、Azure アカウントにサインインした後に表示される結果にある Web アプリを選択します。 [完了] を選んでプロファイルを完了し、[発行] を選んでデプロイを開始します。

    Web アプリ名を使用したデプロイ構成の設定を示すスクリーンショット。

Communication Services リソースを取得する

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

  1. Communication Services リソースを作成する手順を実施します。

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

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

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

  1. Azure portal で Azure Bot リソースに移動します。 リソース メニューで [チャネル] を選択します。 使用可能なチャネルの一覧で、[Azure Communications Services - チャット] を選択します。

    Communication Services チャット チャネルを開く方法を示すスクリーンショット。

  2. [接続] を選択すると、サブスクリプションで使用可能な Communication Services リソースの一覧が表示されます。

    Communication Service リソースをこのボットに接続する方法を示すスクリーンショット。

  3. [新しい接続] ウィンドウで、Communication Services チャット リソースを選択し、[適用] を選択します。

    選んだ Communication Service リソースを保存して、新しい Communication Services ユーザー ID を作成する方法を示すスクリーンショット。

  4. リソース詳細が検証されると、ボット ID が [Bot Azure Communication Services Id] 列に表示されます。 Communication Services Chat AddParticipant API を使用して、ボット ID を使用してチャット スレッド内のボットを表すことができます。 ボットを参加者としてチャットに追加すると、ボットはチャット関連のアクティビティの受信を開始し、チャット スレッドで応答できます。

    ボットに割り当てられた新しい Azure Communication Services ユーザー ID を示すスクリーンショット。

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

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

新しい C# アプリケーションを作成する

  1. 次のコマンドを実行して、C# アプリケーションを作成します。

    dotnet new console -o ChatQuickstart
    
  2. ディレクトリを新しいアプリ フォルダーに変更し、 dotnet build コマンドを使用してアプリケーションをコンパイルします。

    cd ChatQuickstart
    dotnet build
    

パッケージをインストールする

Communication Services Chat SDK for .NET をインストールします。

dotnet add package Azure.Communication.Chat

チャット クライアントを作成する

チャット クライアントを作成するには、Communication Services エンドポイントと、前に生成したユーザー アクセス トークンを使用します。 Identity SDK の CommunicationIdentityClient クラスを使用してユーザーを作成し、チャット クライアントに渡すトークンを発行します。 アクセス トークンは、次の 手順を使用してポータルで生成できます。

次のコードをコピーし、 Program.cs ソース ファイルに貼り付けます。

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Communication Services endpoint
            Uri endpoint = new Uri("https://<RESOURCE_NAME>.communication.azure.com");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

ボットでチャット スレッドを開始する

チャット スレッドを作成するには、createChatThreadchatClient メソッドを使用します。 ID をボットの Communication Services ID に置き換えます。

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<BOT_ID>"))
{
    DisplayName = "BotDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello Bot!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

チャット スレッド クライアントを取得する

GetChatThreadClient メソッドは、既に存在するスレッドのスレッド クライアントを返します。

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

チャット スレッドにメッセージを送信する

SendMessageを使用してスレッドにメッセージを送信するには:

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Hello World",
    MessageType = ChatMessageType.Text
};

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

チャット スレッドからチャット メッセージを受信する

チャット メッセージを取得するには、チャット スレッド クライアントの GetMessages メソッドを一定の間隔でポーリングします。

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

ボットの Hello Worldへのエコー応答のメッセージの一覧を確認します。

JavaScript または Azure モバイル SDK を使用して、受信メッセージ通知をサブスクライブできます。

// Open notifications channel
await chatClient.startRealtimeNotifications();
// Subscribe to new notifications
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Your code here
});

チャット スレッドをクリーンアップする

チャット スレッドの使用が完了したら、スレッドを削除します。

chatClient.DeleteChatThread(threadId);

C# チャット アプリケーションをデプロイする

チャット アプリケーションを展開するには:

  1. Visual Studio で、チャット プロジェクトを開きます。

  2. ChatQuickstart プロジェクトを右クリックし、[発行] を選択します。

    Visual Studio から Azure にチャット アプリケーションをデプロイする方法を示すスクリーンショット。

  3. ソリューションを発行したら、それを実行し、Echo ボットがコマンド プロンプトでユーザー メッセージをエコーするかどうかを確認します。 ソリューションが用意されたので、解決する必要がある可能性のあるビジネス シナリオに必要なさまざまなアクティビティを操作できます。

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

ボットは、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);
                        }
                    }
                }
            }
        }
    }
}

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

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

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

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

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 フィールドには、イベントの名前が含まれています。

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

{
    "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 は、ユーザーからボットに送信されたメッセージでのみ必要です。

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

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

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

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

アクティビティ

  • メッセージ
  • Typing (入力)

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

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

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

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

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

  • メッセージ

    • Id (Communication Services チャット メッセージ ID)
    • TimeStamp
    • Text
    • Attachments
  • 会話の更新

    • MembersAdded
    • MembersRemoved
    • TopicName
  • メッセージの更新

    • Id (更新された Communication Services チャット メッセージ ID)
    • Text
    • Attachments
  • メッセージの削除

    • Id (削除された Communication Services チャット メッセージ ID)
  • イベント

    • Name
    • Value
  • Typing (入力)

その他の共通フィールド

  • Recipient.IdRecipient.Name (Communication Services チャット ユーザー ID と表示名)
  • From.IdFrom.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 開発者ポータルで、Configuration>Bot Messaging に移動して、エンドポイントが正しく設定されていることを確認します。

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

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

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

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

次のステップ

BotFramework WebChat UI コンポーネントを使用して、チャット ユーザーとボットの間の 1 対 1 のチャット用のチャット ボット デモ アプリ を試してください。

OpenAI ボットの追加の詳細については、「 OpenAI ボットとチャットの統合」を参照してください。