Entities and activity types

Entities are a part of an activity, and provide additional information about the activity or conversation.

Note

Different parts of the SDK define separate Entity classes or elements.

Note

Different parts of the SDK define separate Entity classes or elements.

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 channel account 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 postal address 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
}

Activity types

This code example show how to process an activity of type message:

if (context.Activity.Type == ActivityTypes.Message){
    // do something
}

Activities can be of several different types past the most common message. There are several activity types:

Activity.Type Interface Description
message IMessageActivity (C#)
Activity (JS)
Represents a communication between bot and user.
contactRelationUpdate IContactRelationUpdateActivity (C#)
Activity (JS)
Indicates that the bot was added or removed from a user's contact list.
conversationUpdate IConversationUpdateActivity (C#)
Activity (JS)
Indicates that the bot was added to a conversation, other members were added to or removed from the conversation, or conversation metadata has changed.
deleteUserData n/a Indicates to a bot that a user has requested that the bot delete any user data it may have stored.
endOfConversation IEndOfConversationActivity (C#)
Activity (JS)
Indicates the end of a conversation.
event IEventActivity (C#)
Activity (JS)
Represents a communication sent to a bot that is not visible to the user.
installationUpdate IInstallationUpdateActivity (C#)
Activity (JS)
Represents an installation or uninstallation of a bot within an organizational unit (such as a customer tenant or "team") of a channel.
invoke IInvokeActivity (C#)
Activity (JS)
Represents a communication sent to a bot to request that it perform a specific operation. This activity type is reserved for internal use by the Microsoft Bot Framework.
messageReaction IMessageReactionActivity (C#)
Activity (JS)
Indicates that a user has reacted to an existing activity. For example, a user clicks the "Like" button on a message.
typing ITypingActivity (C#)
Activity (JS)
Indicates that the user or bot on the other end of the conversation is compiling a response.
messageUpdate IMessageUpdateActivity (C#)
Activity (JS)
Indicates a request to update a previous message activity in a conversation.
messageDelete IMessageDeleteActivity (C#)
Activity (JS)
Indicates a request to delete a previous message activity in a conversation.
suggestion ISuggestionActivity (C#)
Activity (JS)
Indicates a private suggestion to the recipient about another specific activity.
trace ITraceActivity (C#)
Activity (JS)
An activity by which a bot can log internal information into a logged conversation transcript.
handoff IHandoffActivity (C#)
Activity (JS)
Control of the conversation has been transferred, or a request to transfer control of the conversation.

message

Your bot will send message activities to communicate information to and 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.

Your bot will send message activities to communicate information to and 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.

contactRelationUpdate

A bot receives a contact relation update activity whenever it is added to or removed from a user's contact list. The value of the activity's action property (add | remove) indicates whether the bot has been added or removed from the user's contact list.

conversationUpdate

A bot receives a conversation update activity whenever it has been added to a conversation, other members have been added to or removed from a conversation, or conversation metadata has changed.

If members have been added to the conversation, the activity's members added property will contain an array of channel account objects to identify the new members.

To determine whether your bot has been added to the conversation (i.e., is one of the new members), evaluate whether the recipient Id value for the activity (i.e., your bot's ID) matches the Id property for any of the accounts in the members added array.

If members have been removed from the conversation, the members removed property will contain an array of channel account objects to identify the removed members.

Tip

If your bot receives a conversation update activity indicating that a user has joined the conversation, you may choose to have it respond by sending a welcome message to that user.

deleteUserData

A bot receives a delete user data activity when a user requests deletion of any data that the bot has previously persisted for him or her. If your bot receives this type of activity, it should delete any personally identifiable information (PII) that it has previously stored for the user that made the request.

endOfConversation

A bot receives an end of conversation activity to indicate that the user has ended the conversation. A bot may send an end of Conversation activity to indicate to the user that the conversation is ending.

event

Your bot may receive an event activity from an external process or service that wants to communicate information to your bot without that information being visible to users. The sender of an event activity typically does not expect the bot to acknowledge receipt in any way.

installationUpdate

Installation update activities represent an installation or uninstallation of a bot within an organizational unit (such as a customer tenant or "team") of a channel. Installation update activities generally do not represent adding or removing a channel. Channels may send installation activities when a bot is added to or removed from a tenant, team, or other organization unit within the channel. Channels should not send installation activities when the bot is installed into or removed from a channel.

invoke

Your bot may receive an invoke activity that represents a request for it to perform a specific operation. The sender of an invoke activity typically expects the bot to acknowledge receipt via HTTP response. This activity type is reserved for internal use by the Microsoft Bot Framework.

messageReaction

Some channels will send message reaction activities to your bot when a user reacted to an existing activity. For example, a user clicks the "Like" button on a message. The replyToId property will indicate which activity the user reacted to.

The message reaction activity may correspond to any number of message reaction types that the channel defined. For example, "Like" or "PlusOne" as reaction types that a channel may send.

typing

A bot receives a typing activity to indicate that the user is typing a response. A bot may send a typing activity to indicate to the user that it is working to fulfill a request or compile a response.

Additional resources