Microsoft Bot Framework Component

Manage conversational interactions across platforms using Microsoft Bot Framework
Component key: ms-bot-framework#
DescriptionMicrosoft Bot Framework is a comprehensive framework for building enterprise-grade conversational AI experiences. This component allows you to interact with the Bot Framework REST API to manage conversations and activities.
For additional context about the actions and the data they take please see the Bot Framework REST API Reference.
#
Microsoft Bot Framework Connections#
OAuth 2.0 Client CredentialsThe Microsoft Bot Framework component authenticates using OAuth 2.0 Client Credentials associated with your Azure Bot's App Registration.
To begin you will need to create a new Azure Bot or retrieve the app id and app password (client secret) for an existing bot. If creating a new bot you will likely want to set its type to "Multi Tenant" to allow using your bot across tenants.
Open the Azure Bot and ensure that appropriate Channels are enabled and configured for your intended use case. Each will require additional configuration - Microsoft Teams, for example, will require a Teams app containing a manifest file specifying your bot's configuration with Teams.
Next, navigate to the "Configuration" blade of the bot and click "Manage" next to "Microsoft App ID". This will take you to the Azure AD App Registration for the bot. From here you are able to create a new Client Secret from the "Certificates & Secrets" blade. This will be your "Client secret" (some Microsoft documentation also refers to this as the "app password").
The Client ID and Tenant ID (for Single Tenant bots) can be retrieved from the "Overview" blade.
Next supply the following values to the OAuth 2.0 Client Credentials connection in your integration within Prismatic:
- For Client ID enter the value for "Microsoft App ID" or the "Client ID" from the app registration.
- For Client Secret enter the value from "Certificates & Secrets" of the app registration.
- If your bot is configured as "Single Tenant" you will need to use the conventional Token URL for Azure: https://login.microsoftonline.com/tenantId/oauth2/v2.0/token and replace
tenantId
with the ID of your tenant.
Input | Default | Notes |
---|---|---|
Input Client ID string / Required | Default | Notes |
Input Client secret value password / Required | Default | Notes |
Input Scopes string / Required Hidden Field | Default https://api.botframework.com/.default | Notes Scopes for Microsoft Bot Framework. |
Input Token URL string / Required | Default https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token | Notes 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. |
#
Triggers#
Bot Framework TriggerTrigger that validates incoming requests as coming from Bot Framework | key: botTrigger
Input | Notes | Example |
---|---|---|
Input Microsoft App ID string / Required | Notes Microsoft App ID found in the Azure Bot's Configuration blade. | Example 467105c0-7417-53fb-a409-4bf400037d17 |
#
Actions#
Create ConversationCreate a new Conversation | key: createConversation
Input | Default | Notes | Example |
---|---|---|---|
Input API Version string / Required | Default 3 | Notes Version of the API to call | Example 3 |
Input Bot ID string / Required | Default | Notes Identifier of the Bot receiving requests | Example 29:467105c0-7417-53fb-a409-4bf400037d17 |
Input Channel Account ID string / Required | Default | Notes Identifier of the Channel Account to use (refers to conversation members; bots and users) | Example 27:2iLsjhoGUI4x7idscaXgy4DVI2-NzYvXkz6izkpBtdZT7Ew3CCut_kgYaJMZnHdON_BmKfio3HwhFAPhPZS_83Q |
Input Connection connection / Required | Default | Notes | Example |
Input Service URL string / Required | Default | Notes The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. | Example https://smba.trafficmanager.net/teams/ |
Input Tenant ID string / Required | Default | Notes Tenant ID of the Channel Account ID | Example 133e1a5c-01bb-4b41-b635-e11224d13d45 |
#
Output Example Payload{ "data": { "id": "a:2-m3-i_J1YxM0_MmDD1Dw1h7R75WvLG9eHDFQCJMTWrKbtdBFSL29pEV8H3pMIsQidZSZQCFUT93CL53nbu0BObsfVtd6sCLA6xKIzlFUzxbseRMQ3_hzZJ-Eya_3HQg1" }}
#
Get Conversation MembersGet list of members of the conversation | key: getConversationMembers
Input | Default | Notes | Example |
---|---|---|---|
Input API Version string / Required | Default 3 | Notes Version of the API to call | Example 3 |
Input Connection connection / Required | Default | Notes | Example |
Input Conversation ID string / Required | Default | Notes Identifier of the Conversation to use (refers to a channel, team, direct message) | Example 20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2 |
Input Service URL string / Required | Default | Notes The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. | Example https://smba.trafficmanager.net/teams/ |
#
Output Example Payload{ "data": [ { "id": "27:2iLsjhoGUI4x7idscaXgy4DVI2-NzYvXkz6izkpBtdZT7Ew3CCut_kgYaJMZnHdON_BmKfio3HwhFAPhPZS_83Q", "objectId": "c8906b22-f59a-46b5-8552-21695374389a", "name": "Example Name", "givenName": "Example", "surname": "Name", "email": "example@example.onmicrosoft.com", "userPrincipalName": "example@example.onmicrosoft.com", "tenantId": "133e1a5c-01bb-4b41-b635-e11224d13d45", "userRole": "user" } ]}
#
Raw RequestIssue a raw HTTP request | key: rawRequest
Input | Default | Notes | Example |
---|---|---|---|
Input Connection connection / Required | Default | Notes | Example |
Input Data string | Default | Notes The HTTP body payload to send to the URL. | Example {"exampleKey": "Example Data"} |
Input Debug Request boolean | Default false | Notes Enabling this flag will log out the current request. | Example |
Input File Data string Key Value List | Default | Notes File Data to be sent as a multipart form upload. | Example [{key: "example.txt", value: "My File Contents"}] |
Input Form Data string Key Value List | Default | Notes The Form Data to be sent as a multipart form upload. | Example [{"key": "Example Key", "value": new Buffer("Hello World")}] |
Input Header string Key Value List | Default | Notes A list of headers to send with the request. | Example User-Agent: curl/7.64.1 |
Input Max Retry Count string | Default 0 | Notes The maximum number of retries to attempt. | Example |
Input Method string / Required | Default | Notes The HTTP method to use. | Example |
Input Query Parameter string Key Value List | Default | Notes 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. | Example |
Input Response Type string / Required | Default json | Notes The type of data you expect in the response. You can request json, text, or binary data. | Example |
Input Retry On All Errors boolean | Default false | Notes If true, retries on all erroneous responses regardless of type. | Example |
Input Retry Delay (ms) string | Default 0 | Notes The delay in milliseconds between retries. | Example |
Input Timeout string | Default | Notes The maximum time that a client will await a response to its request | Example 2000 |
Input URL string / Required | Default | Notes This is the URL to call. | Example /sobjects/Account |
Input Use Exponential Backoff boolean | Default false | Notes Specifies whether to use a pre-defined exponential backoff strategy for retries. | Example |
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 MessageSend an adaptive card message | key: sendAdaptiveCardMessage
Input | Default | Notes | Example |
---|---|---|---|
Input API Version string / Required | Default 3 | Notes Version of the API to call | Example 3 |
Input Card Payload data / Required | Default | Notes Adaptive Card payload to send | Example |
Input Connection connection / Required | Default | Notes | Example |
Input Conversation ID string / Required | Default | Notes Identifier of the Conversation to use (refers to a channel, team, direct message) | Example 20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2 |
Input Service URL string / Required | Default | Notes The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. | Example https://smba.trafficmanager.net/teams/ |
See adaptivecards.io for documentation on constructing card payloads.
#
Output Example Payload{ "data": { "id": "2579109807472" }}
#
Send MessageCreate a message to a Conversation | key: sendMessage
Input | Default | Notes | Example |
---|---|---|---|
Input API Version string / Required | Default 3 | Notes Version of the API to call | Example 3 |
Input Connection connection / Required | Default | Notes | Example |
Input Conversation ID string / Required | Default | Notes Identifier of the Conversation to use (refers to a channel, team, direct message) | Example 20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2 |
Input Service URL string / Required | Default | Notes The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region. | Example https://smba.trafficmanager.net/teams/ |
Input Text string / Required | Default | Notes Text of the message to send | Example |
Input Text Format string / Required | Default markdown | Notes Text Format of the message to send | Example markdown |
#
Output Example Payload{ "data": { "id": "2779007726424" }}