Share via


Entities and activity types

APPLIES TO: SDK v3

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.

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

Activity types

Activities can be of several different types past the most common message. Explanations and further details on different activity types can be found in the Bot Framework Activity schema.