Bot Framework General Frequently Asked Questions

This article answers commonly asked general questions.


Why doesn't the Typing activity do anything?

Some channels don't support transient typing updates in their client.

What is the difference between the Connector library and Builder library in the SDK?

The Connector library is the exposition of the REST API. The Builder library adds the conversational dialog programming model and other features such as prompts, waterfalls, chains, and guided form completion. The Builder library also provides access to Azure AI services such as natural language understanding.

How do user messages relate to HTTPS method calls?

When the user sends a message over a channel, the Bot Framework web service will issue an HTTPS POST to the bot's web service endpoint. The bot may send zero, one, or many messages back to the user on that channel, by issuing a separate HTTPS POST to the Bot Framework for each message that it sends.

What is the difference between "proactive" and "reactive"?

From the perspective of your bot, "reactive" means that the user initiates the conversation by sending a message to the bot, and the bot reacts by responding to that message. In contrast, "proactive" means that the bot initiates the conversation by sending the first message to the user. For example, a bot may send a proactive message to notify a user when a timer expires or an event occurs.

How can I send proactive messages to the user?

For examples that show how to send proactive messages, see the C# V4 samples and Node.js V4 samples within the BotBuilder-Samples repository on GitHub.

What is an ETag? How does it relate to bot data bag storage?

An ETag is a mechanism for optimistic concurrency control. The bot data bag storage uses ETags to prevent conflicting updates to the data. An ETag error with HTTP status code 412 "Precondition Failed" indicates that there were multiple messages received in parallel before the bot could finish its first operation. The dialog stack and state are stored in bot data bags. For example, you might see the "Precondition Failed" ETag error if your bot is still processing a previous message when it receives a new message for that conversation.

What is rate limiting?

The Bot Framework service must protect itself and its customers against abusive call patterns (for example, a denial of service attack), so that no single bot can adversely affect the performance of other bots. To achieve this kind of protection, we've added rate limits (also known as throttling) to our endpoints. By enforcing a rate limit, we can restrict the frequency with which a client or bot can make a specific call. For example: with rate limiting enabled, if a bot wanted to post a large number of activities, it would have to space them out over a time period. The purpose of rate-limiting isn't to cap the total volume for a bot. It's designed to prevent abuse of the conversational infrastructure that doesn't follow human conversation patterns. For example, flooding two conversations with more content than two humans could ever consume.

What are the rate limits?

We're continuously tuning the rate limits to make them as lenient as possible while at the same time protecting our service and our users. Because thresholds will occasionally change, we aren't publishing the numbers at this time. Finally, if you're hosting your bot on an App Service, the bot is bound to the limitations of the App Service. For more information, see SLA summary for Azure services If you're impacted by rate limiting, feel free to reach out to us at

What is the size limit of a file transferred using channels?

Some channels have limits on the size or type of files that can be sent. For example, both Direct Line and Facebook limit activity payloads to 262,144 bytes, while the Bot Framework Emulator has no limit. Such limits are imposed by the channel. If you send a message that exceeds this limit, you may get an error, such as: The request content length exceeded limit of 262,144 bytes. You can, however, provide a link to the resource as an internet attachment. For more information on sending attachments, see how to add media to messages.

How will I know if I'm impacted by rate limiting?

It's unlikely you'll experience rate limiting, even at high volume. Most rate limiting would only occur due to bulk sending of activities (from a bot or from a client), extreme load testing, or a bug. When a request is throttled, an HTTP 429 (Too Many Requests) response is returned along with a Retry-After header indicating the amount of time (in seconds) to wait before retrying the request would succeed. You can collect this information by enabling analytics for your bot via Azure Application Insights. Or, you can add code in your bot to log messages.

How does rate limiting occur?

Rate limiting is caused by any of the following conditions:

  • A bot sends messages too frequently
  • A client of a bot sends messages too frequently
  • Direct Line clients request a new Web Socket too frequently

How to implement human handoff?

At times, it's necessary to transfer (handoff) a conversation from a bot to a human being, such as when the bot doesn't understand the user or the request can't be automated. In these cases, the bot provides a transition to humans. The Bot Framework SDK supports handoff to a human. There a few event types for signaling handoff operations. These events are exchanged between a bot and an agent hub, also called engagement hub. This agent hub is defined as an application or a system that allows agents, typically humans, to receive and handle requests from users and escalation requests from bots. For detailed information, see the Transition conversations from bot to human article.