Edit

Quickstart: Add a bot to your chat app

  • Article

Learn how to build conversational AI experiences in a chat application by using the Azure Communication Services Chat messaging channel that's available in Azure Bot Service. In this quickstart, you create a bot by using the BotFramework SDK. Then, you integrate the bot into a chat application you create by using the Communication Services Chat SDK.

In this quickstart, you learn how to:

Prerequisites

  • An Azure account and an active subscription. Create an account for free.
  • Visual Studio 2019 or later.
  • The latest version of .NET Core. In this quickstart, we use .NET Core 3.1. Be sure to install the version that corresponds with your instance of Visual Studio, 32-bit or 64-bit.
  • Bot framework SDK

Create and deploy a bot in Azure

To use Azure Communication Services chat as a channel in Azure Bot Service, first deploy a bot. To deploy a bot, you complete these steps:

  • Create an Azure Bot Service resource
  • Get the bot's app ID and password
  • Create a web app to hold the bot logic
  • Create a messaging endpoint for the bot

Create an Azure Bot Service resource

First, use the Azure portal to create an Azure Bot Service resource. Communication Services Chat channel supports single-tenant bots, managed identity bots, and multi-tenant bots. For the purposes of this quickstart we will use a multi-tenant bot.

To set up a single-tenant or managed identity bot, review Bot identity information.

For a managed identity bot, you might have to update the bot service identity.

Get the bot's app ID and app password

Next, get the Microsoft app ID and password that are assigned to your bot when it's deployed. You use these values for later configurations.

Create a web app to hold the bot logic

To create a web app for your bot, you can revise Bot Builder samples for your scenario or use the Bot Builder SDK to create a web app. One of the simplest samples is Echo Bot.

Azure Bot Service typically expects the Bot Application Web App Controller to expose an endpoint in the form /api/messages. The endpoint handles all messages that are sent to the bot.

To create the bot app, either use the Azure CLI to create an Azure App Service resource or create the app in the Azure portal.

To create a bot web app by using the Azure portal:

  1. In the portal, select Create a resource. In the search box, enter web app. Select the Web App tile.

    Screenshot that shows creating a web app resource in the Azure portal.

  2. In Create Web App, select or enter details for the app, including the region where you want to deploy the app.

    Screenshot that shows details to set to create a web app deployment.

  3. Select Review + Create to validate the deployment and review the deployment details. Then, select Create.

  4. When the web app resource is created, copy the hostname URL that's shown in the resource details. The URL is part of the endpoint you create for the web app.

    Screenshot that shows how to copy the web app endpoint URL.

Create a messaging endpoint for the bot

Next, in the bot resource, create a web app messaging endpoint:

  1. In the Azure portal, go to your Azure Bot resource. In the resource menu, select Configuration.

  2. In Configuration, for Messaging endpoint, paste the hostname URL of the web app you copied in the preceding section. Append the URL with /api/messages.

  3. Select Save.

Screenshot that shows how to create a bot messaging endpoint by using the web app hostname.

Deploy the web app

The final step to create a bot is to deploy the web app. For this quickstart, use the Echo Bot sample. The Echo Bot functionality is limited to echoing the user input. Here's how you deploy it to your web app in Azure:

  1. Use Git to clone this GitHub repository:

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

  2. In Visual Studio, open the Echo Bot project.

  3. In the Visual Studio project, open the Appsettings.json file. Paste the Microsoft app ID and app password you copied earlier:

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

    Next, use Visual Studio for C# bots to deploy the bot.

    You also can use a Command Prompt window to deploy an Azure bot.

  4. In Visual Studio, in Solution Explorer, right-click the EchoBot project and select Publish:

    Screenshot that shows publishing your web app from Visual Studio.

  5. Select New to create a new publishing profile. For Target, select Azure:

    Screenshot that shows how to select Azure as target in a new publishing profile.

    For the specific target, select Azure App Service:

    Screenshot that shows how to select Azure App Service as the specific target.

  6. In the deployment configuration, select the web app in the results that appear after you sign in to your Azure account. To complete the profile, select Finish, and then select Publish to start the deployment.

    Screenshot that shows setting the deployment configuration with the web app name.

Get a Communication Services resource

Now that your bot is created and deployed, create a Communication Services resource to use to set up a Communication Services channel:

  1. Complete the steps to create a Communication Services resource.

  2. Create a Communication Services user and issue a user access token. Be sure to set the scope to chat. Copy the token string and the user ID string.

Enable the Communication Services Chat channel

When you have a Communication Services resource, you can set up a Communication Services channel in the bot resource. In this process, a user ID is generated for the bot.

  1. In the Azure portal, go to your Azure Bot resource. In the resource menu, select Channels. In the list of available channels, select Azure Communications Services - Chat.

    Screenshot that shows opening the Communication Services Chat channel.

  2. Select Connect to see a list of Communication Services resources that are available in your subscription.

    Screenshot that shows how to connect a Communication Service resource to the bot.

  3. In the New Connection pane, select the Communication Services chat resource, and then select Apply.

    Screenshot that shows how to save the selected Communication Service resource to create a new Communication Services user ID.

  4. When the resource details are verified, a bot ID is shown in the Bot Azure Communication Services Id column. You can use the bot ID to represent the bot in a chat thread by using the Communication Services Chat AddParticipant API. After you add the bot to a chat as participant, the bot starts to receive chat-related activities, and it can respond in the chat thread.

    Screenshot that shows the new Communication Services user ID assigned to the bot.

Create a chat app and add the bot as a participant

Now that you have the bot's Communication Services ID, you can create a chat thread with the bot as a participant.

Create a new C# application

  1. Run the following command to create a C# application:

    dotnet new console -o ChatQuickstart

  2. Change your directory to the new app folder and use the dotnet build command to compile your application:

    cd ChatQuickstart
dotnet build

Install the package

Install the Communication Services Chat SDK for .NET:

dotnet add package Azure.Communication.Chat

Create a chat client

To create a chat client, use your Communication Services endpoint and the user access token you generated earlier. Use the CommunicationIdentityClient class from the Identity SDK to create a user and issue a token to pass to your chat client. Access tokens can be generated in the portal using the following instructions.

Copy the following code and paste it in the Program.cs source file:

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

Start a chat thread with the bot

Use the createChatThread method on chatClient to create a chat thread. Replace the ID with the bot's 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;

Get a chat thread client

The GetChatThreadClient method returns a thread client for a thread that already exists:

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

Send a message to a chat thread

To use SendMessage to send a message to a thread:

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

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Receive chat messages from a chat thread

You can get chat messages by polling the GetMessages method on the chat thread client at set intervals:

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

Check the list of messages for the bot's echo reply to "Hello World".

You can use JavaScript or the Azure mobile SDKs to subscribe to incoming message notifications:

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

Clean up the chat thread

When you're finished using the chat thread, delete the thread:

chatClient.DeleteChatThread(threadId);

Deploy the C# chat application

To deploy the chat application:

  1. In Visual Studio, open the chat project.

  2. Right-click the ChatQuickstart project and select Publish:

    Screenshot that shows deploying the chat application to Azure from Visual Studio.

  3. Once you publish the solution, run it and check if Echobot echoes the user message on the command prompt. Now that you have the solution you can proceed to play with the various activities that are needed for the business scenarios that you need to solve for.

More things you can do with a bot

A bot can receive more than a plain-text message from a user in a Communications Services Chat channel. Some of the activities a bot can receive from a user include:

  • Conversation update
  • Message update
  • Message delete
  • Typing indicator
  • Event activity
  • Various attachments, including adaptive cards
  • Bot channel data

The next sections show some samples to illustrate these features.

Send a welcome message when a new user is added to the thread

The current Echo Bot logic accepts input from the user and echoes it back. If you want to add more logic, such as responding to a participant-added Communication Services event, copy the following code and paste it in the EchoBot.cs source file:

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

Send an adaptive card

Note

Adaptive cards are only supported within Azure Communication Services use cases where all chat participants are Azure Communication Services users, and not for Teams interoprability use cases.

You can send an adaptive card to the chat thread to increase engagement and efficiency. An adaptive card also helps you communicate with users in various ways. You can send an adaptive card from a bot by adding the card as a bot activity attachment.

Here's an example of how to send an adaptive card:

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

Get sample payloads for adaptive cards at Samples and templates.

For a chat user, the Communication Services Chat channel adds a field to the message metadata that indicates the message has an attachment. In the metadata, the microsoft.azure.communication.chat.bot.contenttype property is set to azurebotservice.adaptivecard.

Here's an example of a chat message that has an adaptive card attached:

{
    "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"
}

Send a message from user to bot

You can send a basic text message from a user to the bot the same way you send a text message to another user.

However, when you send a message that has an attachment from a user to a bot, add this flag to the Communication Services Chat metadata:

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

To send an event activity from a user to a bot, add this flag to the Communication Services Chat metadata:

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

The following sections show sample formats for chat messages from a user to a bot.

Simple text message

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

Message with an attachment

{
    "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"
}

Message with an event activity

An event payload includes all JSON fields in the message content except Name. The Name field contains the name of the event.

In the following example, the event name endOfConversation with the payload "{field1":"value1", "field2": { "nestedField":"nestedValue" }} is sent to the bot:

{
    "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"
}

The metadata field microsoft.azure.communication.chat.bot.contenttype is required only in a message that's sent from a user to a bot.

Supported bot activity fields

The following sections describe supported bot activity fields for bot-to-user flows and user-to-bot flows.

Bot-to-user flow

The following bot activity fields are supported for bot-to-user flows.

Activities

  • Message
  • Typing

Message activity fields

  • Text
  • Attachments
  • AttachmentLayout
  • SuggestedActions
  • From.Name (Converted to Communication Services SenderDisplayName.)
  • ChannelData (Converted to Communication Services Chat Metadata. If any ChannelData mapping values are objects, they're serialized in JSON format and sent as a string.)

User-to-bot flow

These bot activity fields are supported for user-to-bot flows.

Activities and fields

  • Message

    • Id (Communication Services Chat message ID)
    • TimeStamp
    • Text
    • Attachments

  • Conversation update

    • MembersAdded
    • MembersRemoved
    • TopicName

  • Message update

    • Id (Updated Communication Services Chat message ID)
    • Text
    • Attachments

  • Message delete

    • Id (Deleted Communication Services Chat message ID)

  • Event

    • Name
    • Value

  • Typing

Other common fields

  • Recipient.Id and Recipient.Name (Communication Services Chat user ID and display name)
  • From.Id and From.Name (Communication Services Chat user ID and display name)
  • Conversation.Id (Communication Services Chat thread ID)
  • ChannelId (Communication Services Chat if empty)
  • ChannelData (Communication Services Chat message metadata)

Bot handoff patterns

Sometimes, a bot doesn't understand a question, or it can't answer a question. A customer might ask in the chat to be connected to a human agent. In these scenarios, the chat thread must be handed off from the bot to a human agent. You can design your application to transition a conversation from a bot to a human.

Handling bot-to-bot communication

In some use cases, two bots need to be added to the same chat thread to provide different services. In this scenario, you might need to ensure that a bot doesn't send automated replies to another bot's messages. If not handled properly, the bots' automated interaction between themselves might result in an infinite loop of messages.

You can verify the Communication Services user identity of a message sender in the activity's From.Id property. Check to see whether it belongs to another bot. Then, take the required action to prevent a bot-to-bot communication flow. If this type of scenario results in high call volumes, the Communication Services Chat channel throttles the requests and a bot can't send and receive messages.

Learn more about throttle limits.

Troubleshoot

The following sections describe ways to troubleshoot common scenarios.

Chat channel can't be added

In the Microsoft Bot Framework developer portal, go to Configuration > Bot Messaging to verify that the endpoint has been set correctly.

Bot gets a forbidden exception while replying to a message

Verify that the bot's Microsoft app ID and password are saved correctly in the bot configuration file you upload to the web app.

Bot can't be added as a participant

Verify that the bot's Communication Services ID is used correctly when a request is sent to add a bot to a chat thread.

Next steps

Try the chat bot demo app for a 1:1 chat between a chat user and a bot via the BotFramework WebChat UI component.