Skip to main content

Microsoft Bot Framework Component

Manage conversations, messages, and activities in Microsoft Bot Framework.

Component key: ms-bot-framework

Changelog ↓

Description​

Microsoft Bot Framework is a comprehensive framework for building enterprise-grade conversational AI experiences. This component allows you to send messages, manage conversations, and interact with bot activities across multiple channels including Microsoft Teams, Slack, and web chat.

API Documentation​

This component was built using the following API References currently utilizing Bot Connector API v3.0:

For additional context about the actions and the data they take please see the Bot Framework REST API Reference.

Connections​

OAuth 2.0 Client Credentials​

The Microsoft Bot Framework component authenticates using OAuth 2.0 Client Credentials associated with an Azure Bot's App Registration.

Prerequisites​

  • An Azure account with permissions to create and manage Azure Bots
  • An Azure Bot resource (or ability to create one)
  • Appropriate channels enabled and configured for the intended use case

Setup Steps​

  1. Create a new Azure Bot or retrieve the app ID and app password (client secret) for an existing bot. When creating a new bot, set its type to Multi Tenant to allow using the bot across tenants.

  2. Open the Azure Bot and ensure that appropriate channels are enabled and configured for the intended use case. Each channel requires additional configuration - Microsoft Teams, for example, requires a Teams app containing a manifest file specifying the bot's configuration with Teams.

  3. Navigate to the Configuration blade of the bot and click Manage next to Microsoft App ID. This will navigate to the Azure AD App Registration for the bot.

  4. From the App Registration, navigate to the Certificates & secrets blade and create a new Client Secret. Copy the secret value immediately - this is the Client Secret (also referred to as the "app password" in some Microsoft documentation).

  5. Navigate to the Overview blade to retrieve:

    • Application (client) ID - This is the Client ID
    • Directory (tenant) ID - Required for Single Tenant bots

Configure the Connection​

  • For Client ID, enter the value for Microsoft App ID or the Client ID from the app registration.
  • For Client Secret, enter the secret value from the Certificates & secrets blade of the app registration.
  • If the bot is configured as Single Tenant, update the Token URL to: https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token and replace TENANT_ID with the tenant ID from the Overview blade.
Multi-Tenant vs Single-Tenant Bots

The default Token URL (https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token) is configured for Multi-Tenant bots. For Single-Tenant bots, the Token URL must be updated to use the specific tenant ID.

InputNotesExample
Client ID

The Client ID (Application ID) from your Azure Bot registration.

a1b2c3d4-e5f6-7890-abcd-ef1234567890
Client Secret Value

The Client Secret value from your Azure Bot registration under 'Certificates & Secrets'.

a1B~2cD3eF4gH5iJ6kL7mN8oP9qR0sT1uV2wX
Scopes

Scopes for Microsoft Bot Framework and Microsoft Graph.

https://api.botframework.com/.default
Token URL

The OAuth 2.0 Token URL for Microsoft Bot Framework. Use the default for Multi-Tenant bots and https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token for Single-Tenant.

https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token

Direct Line​

The Microsoft Bot Framework component supports Direct Line connectivity for direct communication with an Azure Bot.

Direct Line is a channel that allows integrating a bot directly into a client application. It provides a simple REST API for exchanging messages with the bot.

Prerequisites​

  • An Azure Bot resource configured in the Azure Portal
  • Permissions to manage channels for the Azure Bot

Setup Steps​

  1. Navigate to the Azure Bot resource in the Azure Portal.

  2. Select the Channels blade from the left-hand menu.

  3. Click on Direct Line from the available channels list to enable it.

  4. Once enabled, two secret keys will be presented. These keys are used to authenticate the application with the Direct Line service.

  5. Copy one of the secret keys - this is the Direct Line Secret.

Configure the Connection​

  • For Direct Line Secret, enter the secret key copied from the Direct Line channel configuration in the Azure Bot.
InputNotesExample
Direct Line Secret

The Direct Line secret value for your bot.

Triggers​

Bot Framework Trigger​

Trigger that validates incoming requests as coming from Bot Framework | key: botTrigger

InputNotesExample
Microsoft App ID

Microsoft App ID found in the Azure Bot's Configuration blade.

467105c0-7417-53fb-a409-4bf400037d17

Actions​

Create Conversation​

Create a new Conversation | key: createConversation

InputNotesExample
API Version

The version of the Bot Framework API to call.

3
Bot ID

The unique identifier of the bot receiving requests.

29:467105c0-7417-53fb-a409-4bf400037d17
Channel Account ID

The unique identifier of the channel account (refers to conversation members such as bots and users).

27:2iLsjhoGUI4x7idscaXgy4DVI2-NzYvXkz6izkpBtdZT7Ew3CCut_kgYaJMZnHdON_BmKfio3HwhFAPhPZS_83Q
Connection

The connection to use for authenticating requests to Microsoft Bot Framework.

Service URL

The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. Use https://directline.botframework.com/ for Direct Line connections.

https://smba.trafficmanager.net/teams/
Tenant ID

The tenant ID associated with the channel account.

133e1a5c-01bb-4b41-b635-e11224d13d45

{
  "data": {
    "id": "a:1bT8Gx4kJ2mN5pQ7rS9tU0vW1xY2zA3bC4dE5fG6hH7iJ8kL9mN0oP1qR2sT3uV4wX5yZ6aB7cD8eF9gH0iJ1kL",
    "activityId": "1649887612801|0000002",
    "serviceUrl": "https://smba.trafficmanager.net/teams/"
  }
}

Get Conversation Members​

Get list of members of the conversation | key: getConversationMembers

InputNotesExample
API Version

The version of the Bot Framework API to call.

3
Connection

The connection to use for authenticating requests to Microsoft Bot Framework.

Conversation ID

The unique identifier of the conversation (refers to a channel, team, or direct message).

20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2
Service URL

The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. Use https://directline.botframework.com/ for Direct Line connections.

https://smba.trafficmanager.net/teams/

{
  "data": [
    {
      "id": "29:1bT8Gx4kJ2mN5pQ7rS9tU0vW1xY2zA3bC4dE5fG6hH7iJ8kL9mN0oP1qR2sT3uV4wX5yZ6aB7cD8eF9gH0iJ1kL",
      "objectId": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
      "name": "John Doe",
      "givenName": "John",
      "surname": "Doe",
      "email": "john.doe@example.com",
      "userPrincipalName": "john.doe@example.com",
      "tenantId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "userRole": "user"
    },
    {
      "id": "29:2cU9Hy5lK3nO6qR8sT0uV1wX2yZ3aB4cD5eF6gH7iJ8kL9mN0oP1qR2sT3uV4wX5yZ6aB7cD8eF9gH0iJ1kL2m",
      "objectId": "b2c3d4e5-f6g7-8901-bc23-de45fg678901",
      "name": "Jane Smith",
      "givenName": "Jane",
      "surname": "Smith",
      "email": "jane.smith@example.com",
      "userPrincipalName": "jane.smith@example.com",
      "tenantId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "userRole": "user"
    },
    {
      "id": "28:3dV0Iz6mL4oP7rS9tU1vW2xY3zA4bC5dE6fG7hH8iJ9kL0mN1oP2qR3sT4uV5wX6yZ7aB8cD9eF0gH1iJ2kL3m",
      "name": "Support Bot",
      "userRole": "bot"
    }
  ]
}

Raw Request​

Issue a raw HTTP request | key: rawRequest

InputNotesExample
Connection
Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
Debug Request

Enabling this flag will log out the current request.

false
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

This is the URL to call.

/sobjects/Account
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

Note that you will need to construct a full URL using the Base URI (sometimes referred to as "Service URL") and a version path (example: https://smba.trafficmanager.net/apis/v3/conversations/abcd1234/activities/bf3cc9a2f5de... where https://smba.trafficmanager.net/apis/ is the Base URI, v3 is the version, and the remainder is the REST API action to perform).

Please refer to the Bot Framework REST API Reference for details on their API surface.

Send Adaptive Card Message​

Send an adaptive card message | key: sendAdaptiveCardMessage

InputNotesExample
API Version

The version of the Bot Framework API to call.

3
Card Payload

Adaptive Card payload to send

Connection

The connection to use for authenticating requests to Microsoft Bot Framework.

Conversation ID

The unique identifier of the conversation (refers to a channel, team, or direct message).

20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2
From ID

The unique identifier of the user sending the message.

user1
From Name

The name of the user sending the message.

Local Tester
Service URL

The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. Use https://directline.botframework.com/ for Direct Line connections.

https://smba.trafficmanager.net/teams/

See adaptivecards.io for documentation on constructing card payloads.

{
  "data": {
    "id": "1649887498472|0000001"
  }
}

Send Message​

Create a message to a Conversation | key: sendMessage

InputNotesExample
API Version

The version of the Bot Framework API to call.

3
Connection

The connection to use for authenticating requests to Microsoft Bot Framework.

Conversation ID

The unique identifier of the conversation (refers to a channel, team, or direct message).

20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2
From ID

The unique identifier of the user sending the message.

user1
From Name

The name of the user sending the message.

Local Tester
Service URL

The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. Use https://directline.botframework.com/ for Direct Line connections.

https://smba.trafficmanager.net/teams/
Text

The text content of the message to send.

Hello, this is a message from the bot.
Text Format

Text Format of the message to send

markdown

{
  "data": {
    "id": "1649887364395|0000000"
  }
}

Changelog​

2025-11-19​

Enhanced webhook triggers to support simulated test executions

2025-11-04​

  • Added Direct Line connection type for direct communication with Azure Bots
  • Enhanced Send Message and Send Adaptive Card Message actions with sender identity support (from ID and name fields)