Send and receive activities

The Bot Framework Connector provides a single REST API that enables a bot to communicate across multiple channels such as Skype, Email, Slack, and more. It facilitates communication between bot and user, by relaying messages from bot to channel and from channel to bot.

This article describes how to use the Connector via the Bot Builder SDK for .NET to exchange information between bot and user on a channel.

Note

While it is possible to construct a bot by exclusively using the techniques that are described in this article, the Bot Builder SDK provides additional features like dialogs and FormFlow that can streamline the process of managing conversation flow and state and make it simpler to incorporate cognitive services such as language understanding.

Create a connector client

The ConnectorClient class contains the methods that a bot uses to communicate with a user on a channel. When your bot receives an Activity object from the Connector, it should use the ServiceUrl specified for that activity to create the connector client that it'll subsequently use to generate a response.

public async Task<HttpResponseMessage> Post([FromBody]Activity activity)
{
    var connector = new ConnectorClient(new Uri(activity.ServiceUrl));
    . . .
}
Tip

Because a channel's endpoint may not be stable, your bot should direct communications to the endpoint that the Connector specifies in the Activity object, whenever possible (rather than relying upon a cached endpoint).

If your bot needs to initiate the conversation, it can use a cached endpoint for the specified channel (since there will be no incoming Activity object in that scenario), but it should refresh cached endpoints often.

Create a reply

The Connector uses an Activity object to pass information back and forth between bot and channel (user). Every activity contains information used for routing the message to the appropriate destination along with information about who created the message (From property), the context of the message, and the recipient of the message (Recipient property).

When your bot receives an activity from the Connector, the incoming activity's Recipient property specifies the bot's identity in that conversation. Because some channels (e.g., Slack) assign the bot a new identity when it's added to a conversation, the bot should always use the value of the incoming activity's Recipient property as the value of the From property in its response.

Although you can create and initialize the outgoing Activity object yourself from scratch, the Bot Builder SDK provides an easier way of creating a reply. By using the incoming activity's CreateReply method, you simply specify the message text for the response, and the outgoing activity is created with the Recipient, From, and Conversation properties automatically populated.

Activity reply = activity.CreateReply($"You sent {activity.Text} which was {length} characters");

Send a reply

Once you've created a reply, you can send it by calling the connector client's ReplyToActivity method. The Connector will deliver the reply using the appropriate channel semantics.

await connector.Conversations.ReplyToActivityAsync(reply);
Tip

If your bot is replying to a user's message, always use the ReplyToActivity method.

Send a (non-reply) message

If your bot is part of a conversation, it can send a message that is not a direct reply to any message from the user by calling the SendToConversation method.

await connector.Conversations.SendToConversationAsync((Activity)newMessage);

You may use the CreateReply method to initialize the new message (which would automatically set the Recipient, From, and Conversation properties for the message). Alternatively, you could use the CreateMessageActivity method to create the new message and set all property values yourself.

Note

The Bot Framework does not impose any restrictions on the number of messages that a bot may send. However, most channels enforce throttling limits to restrict bots from sending a large number of messages in a short period of time. Additionally, if the bot sends multiple messages in quick succession, the channel may not always render the messages in the proper sequence.

Start a conversation

There may be times when your bot needs to initiate a conversation with one or more users. You can start a conversation by calling either the CreateDirectConversation method (for a private conversation with a single user) or the CreateConversation method (for a group conversation with multiple users) to retrieve a ConversationAccount object. Then, create the message and send it by calling the SendToConversation method. To use either the CreateDirectConversation method or the CreateConversation method, you must first create the connector client by using the target channel's service URL (which you may retrieve from cache, if you've persisted it from previous messages).

Note

Not all channels support group conversations. To determine whether a channel supports group conversations, consult the channel's documentation.

This code example uses the CreateDirectConversation method to create a private conversation with a single user.

var userAccount = new ChannelAccount(name: "Larry", id: "@UV357341");
var connector = new ConnectorClient(new Uri(actvity.ServiceUrl));
var conversationId = await connector.Conversations.CreateDirectConversationAsync(botAccount, userAccount);

IMessageActivity message =  Activity.CreateMessageActivity();
message.From = botAccount;
message.Recipient = userAccount;
message.Conversation = new ConversationAccount(id: conversationId.Id);
message.Text = "Hello, Larry!";
message.Locale = "en-Us";
await connector.Conversations.SendToConversationAsync((Activity)message); 

This code example uses the CreateConversation method to create a group conversation with multiple users.

var connector = new ConnectorClient(new Uri(incomingMessage.ServiceUrl));

List<ChannelAccount> participants = new List<ChannelAccount>();
participants.Add(new ChannelAccount("joe@contoso.com", "Joe the Engineer"));
participants.Add(new ChannelAccount("sara@contoso.com", "Sara in Finance"));

ConversationParameters cpMessage = new ConversationParameters(message.Recipient, true, participants, "Quarter End Discussion");
var conversationId = await connector.Conversations.CreateConversationAsync(cpMessage);

IMessageActivity message = Activity.CreateMessageActivity();
message.From = botAccount;
message.Recipient = new ChannelAccount("lydia@contoso.com", "Lydia the CFO"));
message.Conversation = new ConversationAccount(id: conversationId.Id);
message.ChannelId = incomingMessage.ChannelId;
message.Text = "Hello, everyone!";
message.Locale = "en-Us";

await connector.Conversations.SendToConversationAsync((Activity)message); 

Additional resources