Create messages in the v3 C# SDK

APPLIES TO: SDK v3

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.

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:

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

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:

The GeoCoordinates object contains these properties:

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

• Activities overview
• Send and receive activities
• Add media attachments to messages
• Add rich cards to messages
• Add speech to messages
• Add suggested actions to messages
• Implement channel-specific functionality
• Activity class
• IMessageActivity interface