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:
| 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) |
| Latitude | 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.