Microsoft Bot Framework Component

Manage conversational interactions across platforms using Microsoft Bot Framework

Component key: ms-bot-framework

Description

Microsoft 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 Credentials

The 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 Trigger

Trigger 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 Conversation

Create 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 Members

Get 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 Request

Issue 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 Message

Send 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 Message

Create 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"  }}

---