Send and receive text messages

APPLIES TO: SDK v4

The primary way your bot will communicate with users, and likewise receive communication, is through message activities. Some messages may only contain plain text, while others may contain richer content such as cards or attachments. Your bot's turn handler receives messages from the user, and you can send responses to the user from there. The turn context object provides methods for sending messages back to the user. This article describes how to send plain text messages.

Markdown is supported for most text fields, but support may vary by channel.

For a running bot sending and receiving messages, follow the quickstarts at the top of the table of contents or check out the article on how bots work, which also links to samples available for you to run yourself.

Note

The Bot Framework JavaScript, C#, and Python SDKs will continue to be supported, however, the Java SDK is being retired with final long-term support ending in November 2023.

Existing bots built with the Java SDK will continue to function.

For new bot building, consider using Microsoft Copilot Studio and read about choosing the right copilot solution.

For more information, see The future of bot building.

Send a text message

To send a text message, specify the string you want to send as the activity:

C#

In the bot's activity handlers, use the turn context object's SendActivityAsync method to send a single message response. You can also use the object's SendActivitiesAsync method to send multiple responses at once.

await turnContext.SendActivityAsync($"Welcome!");

JavaScript

In the bot's activity handlers, use the turn context object's sendActivity method to send a single message response. You can also use the object's sendActivities method to send multiple responses at once.

await context.sendActivity("Welcome!");

Java

In the bot's activity handlers, use the turn context object's sendActivity method to send a single message response. You can also use the object's sendActivities method to send multiple responses at once.

turnContext.sendActivity("Welcome!");

Python

In the bot's activity handlers, use the turn context object's send_activity method to send a single message response.

await turn_context.send_activity("Welcome!")

LG

Language Generation (LG) provides templates that include one or more variations of text that are used for composition and expansion. One of the variations provided will be picked at random by the LG system.

The following example shows a bot response template that includes two variations.

# GreetingPrefix
- Hi
- Hello

Receive a text message

To handle a text message, use the text property of the activity object.

C#

In the bot's activity handlers, use the following code to receive a message.

var responseMessage = turnContext.Activity.Text;

JavaScript

In the bot's activity handlers, use the following code to receive a message.

let text = turnContext.activity.text;

Java

In the bot's activity handlers, use the following code to receive a message.

String responseMessage = turnContext.getActivity().getText();

Python

In the bot's activity handlers, use the following code to receive a message.

response = context.activity.text

LG

Add the following LG template to your .lg file to receive a message.

# EchoMessage
You said '${turn.activity.text}'

Send a typing indicator

Users expect a timely response to their messages. If your bot performs some long-running task like calling a server or executing a query without giving the user some indication that the bot heard them, the user could get impatient and send additional messages or just assume the bot is broken.

Web Chat and Direct Line channel bots can support the sending of a typing indication to show the user that the message was received and is being processed. However, your bot needs to let the turn end within 15 seconds or the Connector service will time out. For longer processes, read more about sending proactive messages.

The following example demonstrates how to send a typing indication.

C#

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (string.Equals(turnContext.Activity.Text, "wait", System.StringComparison.InvariantCultureIgnoreCase))
    {
        await turnContext.SendActivitiesAsync(
            new Activity[] {
                new Activity { Type = ActivityTypes.Typing },
                new Activity { Type = "delay", Value= 3000 },
                MessageFactory.Text("Finished typing", "Finished typing"),
            },
            cancellationToken);
    }
    else
    {
        var replyText = $"Echo: {turnContext.Activity.Text}. Say 'wait' to watch me type.";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }
}

JavaScript

this.onMessage(async (context, next) => {
    if (context.activity.text === 'wait') {
        await context.sendActivities([
            { type: ActivityTypes.Typing },
            { type: 'delay', value: 3000 },
            { type: ActivityTypes.Message, text: 'Finished typing' }
        ]);
    } else {
        await context.sendActivity(`You said '${ context.activity.text }'. Say "wait" to watch me type.`);
    }
    await next();
});

Java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    if (turnContext.getActivity().getText().toLowerCase().equals("wait")) {
        List<Activity> activities = new ArrayList<Activity>();
        activities.add(new Activity(ActivityTypes.TYPING));
        activities.add(new Activity(ActivityTypes.DELAY) {{setValue(3000);}});
        activities.add(MessageFactory.text("Finished typing", "Finished typing", null));
        return turnContext.sendActivities(activities).thenApply(result -> null);
    } else {

        return turnContext.sendActivity(MessageFactory.text("Echo: " + turnContext.getActivity().getText()))
            .thenApply(sendResult -> null);
    }
}

Python

async def on_message_activity(self, turn_context: TurnContext):
    if turn_context.activity.text == "wait":
        return await turn_context.send_activities([
            Activity(
                type=ActivityTypes.typing
            ),
            Activity(
                type="delay",
                value=3000
            ),
            Activity(
                type=ActivityTypes.message,
                text="Finished Typing"
            )
        ])
    else:
        return await turn_context.send_activity(
            f"You said {turn_context.activity.text}.  Say 'wait' to watch me type."
        )

LG

# TypingIndicator
[Activity
    Type = typing
]

Additional resources

• Activity processing
• Message activity section
• Language Generation

Next steps

Add media to messages