Create messages

Your bot will send message activities to communicate information to users, and likewise, will also receive message activities from users. Some messages may simply consist of plain text, while others may contain richer content such as text to be spoken, suggested actions, media attachments, rich cards, and channel-specific data.

This article describes some of the commonly-used message properties.

Customizing a message

To have more control over the text formatting of your messages, you can create a custom message using the Activity object and set the properties necessary before sending it to the user.

This sample shows how to create a custom message object and set the Text, TextFormat, and Local properties.

IMessageActivity message =  Activity.CreateMessageActivity();
message.Text = "Hello!";
message.TextFormat = "plain";
message.Locale = "en-Us";

The TextFormat property of a message can be used to specify the format of the text. The TextFormat property can be set to plain, markdown, or xml. The default value for TextFormat is markdown.

For a list of commonly supported text formatting, see Text formatting. To ensure that the feature(s) you want to use is supported by the target channel, preview the feature(s) using the Channel Inspector.

Attachments

The Attachments property of a message activity can be used to send and receive simple media attachments (image, audio, video, file) and rich cards. For details, see Add media attachments to messages and Add rich cards to messages.

Entities

The Entities property of a message is an array of open-ended schema.org objects which allows the exchange of common contextual metadata between the channel and bot.

Mention entities

Many channels support the ability for a bot or user to "mention" someone within the context of a conversation. To mention a user in a message, populate the message's Entities property with a Mention object. The Mention object contains these properties:

Property Description
Type type of the entity ("mention")
Mentioned ChannelAccount object that indicates which user was mentioned
Text text within the Activity.Text property that represents the mention itself (may be empty or null)

This code example shows how to add a Mention entity to the Entities collection.

var entity = new Entity();
entity.SetAs(new Mention()
{
    Text = "@johndoe",
    Mentioned = new ChannelAccount()
    {
        Name = "John Doe",
        Id = "UV341235"
    }
});
entities.Add(entity);
Tip

When attempting to determine user intent, the bot may want to ignore that portion of the message where it is mentioned. Call the GetMentions method and evaluate the Mention objects returned in the response.

Place objects

Location-related information can be conveyed within a message by populating the message's Entities property with either a Place object or a GeoCoordinates object.

The Place object contains these properties:

Property Description
Type type of the entity ("Place")
Address description or PostalAddress object (future)
Geo GeoCoordinates
HasMap URL to a map or Map object (future)
Name name of the place

The GeoCoordinates object contains these properties:

Property Description
Type type of the entity ("GeoCoordinates")
Name name of the place
Longitude longitude of the location (WGS 84)
Longitude latitude of the location (WGS 84)
Elevation elevation of the location (WGS 84)

This code example shows how to add a Place entity to the Entities collection:

var entity = new Entity();
entity.SetAs(new Place()
{
    Geo = new GeoCoordinates()
    {
        Latitude = 32.4141,
        Longitude = 43.1123123,
    }
});
entities.Add(entity);

Consume entities

To consume entities, use either the dynamic keyword or strongly-typed classes.

This code example shows how to use the dynamic keyword to process an entity within the Entities property of a message:

if (entity.Type == "Place")
{
    dynamic place = entity.Properties;
    if (place.geo.latitude > 34)
        // do something
}

This code example shows how to use a strongly-typed class to process an entity within the Entities property of a message:

if (entity.Type == "Place")
{
    Place place = entity.GetAs<Place>();
    GeoCoordinates geo = place.Geo.ToObject<GeoCoordinates>();
    if (geo.Latitude > 34)
        // do something
}

Channel data

The ChannelData property of a message activity can be used to implement channel-specific functionality. For details, see Implement channel-specific functionality.

Text to speech

The Speak property of a message activity can be used to specify the text to be spoken by your bot on a speech-enabled channel. The InputHint property of a message activity can be used to control the state of the client's microphone and input box (if any). For details, see Add speech to messages.

Suggested actions

The SuggestedActions property of a message activity can be used to present buttons that the user can tap to provide input. Unlike buttons that appear within rich cards (which remain visible and accessible to the user even after being tapped), buttons that appear within the suggested actions pane will disappear after the user makes a selection. For details, see Add suggested actions to messages.

Next steps

A bot and a user can send messages to each other. When the message is more complex, your bot can send a rich card in a message to the user. Rich cards cover many presentation and interaction scenarios commonly needed in most bots.

Additional resources