Skip to main content

Microsoft Bot Framework Component

Microsoft Bot Framework

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.

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
Client ID
string
/ Required
clientId
 
Client secret value
password
/ Required
clientSecret
 
Scopes
string
/ Required
Hidden Field
scopes
https://api.botframework.com/.default
Scopes for Microsoft Bot Framework.
Token URL
string
/ Required
tokenUrl
https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
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
Microsoft App ID
string
/ Required
botId
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

InputDefaultNotesExample
API Version
string
/ Required
apiVersion
3
Version of the API to call
3
Bot ID
string
/ Required
botId
Identifier of the Bot receiving requests
29:467105c0-7417-53fb-a409-4bf400037d17
Channel Account ID
string
/ Required
channelAccountId
Identifier of the Channel Account to use (refers to conversation members; bots and users)
27:2iLsjhoGUI4x7idscaXgy4DVI2-NzYvXkz6izkpBtdZT7Ew3CCut_kgYaJMZnHdON_BmKfio3HwhFAPhPZS_83Q
Connection
connection
/ Required
connection
 
 
 
Service URL
string
/ Required
serviceUrl
The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region.
https://smba.trafficmanager.net/teams/
Tenant ID
string
/ Required
tenantId
Tenant ID of the Channel Account ID
133e1a5c-01bb-4b41-b635-e11224d13d45

{
  "data": {
    "id": "a:2-m3-i_J1YxM0_MmDD1Dw1h7R75WvLG9eHDFQCJMTWrKbtdBFSL29pEV8H3pMIsQidZSZQCFUT93CL53nbu0BObsfVtd6sCLA6xKIzlFUzxbseRMQ3_hzZJ-Eya_3HQg1"
  }
}

Get Conversation Members​

Get list of members of the conversation | key: getConversationMembers

InputDefaultNotesExample
API Version
string
/ Required
apiVersion
3
Version of the API to call
3
Connection
connection
/ Required
connection
 
 
 
Conversation ID
string
/ Required
conversationId
Identifier of the Conversation to use (refers to a channel, team, direct message)
20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2
Service URL
string
/ Required
serviceUrl
The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region.
https://smba.trafficmanager.net/teams/

{
  "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
Connection
connection
/ Required
connection
 
 
 
Data
string
data
The HTTP body payload to send to the URL.
{"exampleKey": "Example Data"}
Debug Request
boolean
debugRequest
false
Enabling this flag will log out the current request.
 
File Data
string
Key Value List
fileData
File Data to be sent as a multipart form upload.
[{key: "example.txt", value: "My File Contents"}]
Form Data
string
Key Value List
formData
The Form Data to be sent as a multipart form upload.
[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header
string
Key Value List
headers
A list of headers to send with the request.
User-Agent: curl/7.64.1
Max Retry Count
string
maxRetries
0
The maximum number of retries to attempt.
 
Method
string
/ Required
method
The HTTP method to use.
 
Query Parameter
string
Key Value List
queryParams
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
string
/ Required
responseType
json
The type of data you expect in the response. You can request json, text, or binary data.
 
Retry On All Errors
boolean
retryAllErrors
false
If true, retries on all erroneous responses regardless of type.
 
Retry Delay (ms)
string
retryDelayMS
0
The delay in milliseconds between retries.
 
Timeout
string
timeout
The maximum time that a client will await a response to its request
2000
URL
string
/ Required
url
This is the URL to call.
/sobjects/Account
Use Exponential Backoff
boolean
useExponentialBackoff
false
Specifies whether to use a pre-defined exponential backoff strategy for retries.
 

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
API Version
string
/ Required
apiVersion
3
Version of the API to call
3
Card Payload
data
/ Required
cardPayload
Adaptive Card payload to send
 
Connection
connection
/ Required
connection
 
 
 
Conversation ID
string
/ Required
conversationId
Identifier of the Conversation to use (refers to a channel, team, direct message)
20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2
Service URL
string
/ Required
serviceUrl
The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region.
https://smba.trafficmanager.net/teams/

See adaptivecards.io for documentation on constructing card payloads.

{
  "data": {
    "id": "2579109807472"
  }
}

Send Message​

Create a message to a Conversation | key: sendMessage

InputDefaultNotesExample
API Version
string
/ Required
apiVersion
3
Version of the API to call
3
Connection
connection
/ Required
connection
 
 
 
Conversation ID
string
/ Required
conversationId
Identifier of the Conversation to use (refers to a channel, team, direct message)
20:Tc8kzfj3VF7CX9grVLyNeuH-kt2HkTldtNQm_U_dgSE3@thread.tacv2
Service URL
string
/ Required
serviceUrl
The Service URL (also referred to as Base URI) to send requests to the Bot Framework. Varies per bot channel and region.
https://smba.trafficmanager.net/teams/
Text
string
/ Required
text
Text of the message to send
 
Text Format
string
/ Required
textFormat
markdown
Text Format of the message to send
markdown

{
  "data": {
    "id": "2779007726424"
  }
}