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

[アーティクル]
03/25/2023

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

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

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

前提条件

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

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

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

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

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

Web アプリのデプロイ

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

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

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

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

また、コマンドプロンプトウィンドウを使用して 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 が取得できたので、ボットを参加者とするチャットスレッドを作成できます。

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

次のコマンドを実行して C# アプリケーションを作成します。
```
dotnet new console -o ChatQuickstart
```
ディレクトリを、新しいアプリフォルダーに変更し、dotnet build コマンドを使用して自分のアプリケーションをコンパイルします。
```
cd ChatQuickstart
dotnet build
```

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

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

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);
        }
    }
}

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

チャットスレッドは、chatClient に createChatThread メソッドを使用して作成します。 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# チャットアプリケーションをデプロイする

チャットアプリケーションをデプロイするには、次を行います。

Visual Studio でチャットプロジェクトを開きます。
ChatQuickstart プロジェクトを右クリックして、[発行] を選択します
ソリューションを公開したら、それを実行し、コマンドプロンプトでユーザーメッセージが Echobot から返されるか確認します。これでソリューションが与えられたので、解決を必要とするビジネスシナリオに必要なさまざまなアクティビティで試すことができます。

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

ボットは、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 が正しく使われていることを確認します。

次の手順

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

Share via

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

前提条件

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

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

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

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

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

Web アプリのデプロイ

Communication Services リソースを取得する

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

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

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

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

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

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

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

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

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

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

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