Skip to main content

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.
InputDefaultNotes
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

InputNotesExample
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

InputDefaultNotesExample
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

InputDefaultNotesExample
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

InputDefaultNotesExample
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

InputDefaultNotesExample
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

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