The Microsoft Bot Framework example connector enables you to make your Teneo bot available using the Microsoft Bot Framework, allowing you to target channels like Skype, Microsoft Teams and Cortana. The node.js connector acts as middleware between the Microsoft Bot Framework and Teneo. This guide will take you through the steps of registering your bot on the Microsoft Azure portal, deploying the connector and making it available via Skype or Teams.
You can find the source code of this example connector on Github, allowing you to extend or modify it to your needs.
The Microsoft Bot Framework requires that the connector is available via https. On this page we will be using Heroku to host this connector, for which a (free) Heroku account is needed. You can however also manually install the connector on a location of your choice, see Running the connector locally.
Your bot needs to be published and you need to know the engine url.
Before we can deploy our connector, we need an 'Application Id' and 'Application password' from Microsoft. To obtain those, we need to create an 'App Registration' in Microsoft's Azure Portal.
Click the button below to deploy the connector to Heroku:
When Heroku has finished deploying, click 'View app' and copy the url of your Heroku app, you will need it in the next step.
If you prefer to run your bot locally, see Running the connector locally.
To register your bot with the Azure Bot Service, you will need to create a new 'Bot Channels Registration'.
That's it! You can now test your bot by opening your bot resource in the Azure portal and choosing 'Test in Web Chat'.
You can make your bot available on various channels by opening your bot resource in the Azure portal and choosing 'Channels'. As you can see, your bot is already available via the web channel. From here you can choose to make your bot available on other channels like Microsoft Teams or Skype.
For example, to make your bot available on Skype, follow these steps:
To add media or cards to a message, this connector looks for an output parameter msbotframework in the engine response. The value of that parameter is assumed to contain the JSON of the media or card as defined by Microsoft.
You can find more information about the JSON required for the various attachments on the following pages on the Microsoft Azure Bot Service website:
If we look at Microsoft's specification of an image attachment, the value of the msbotframework output parameter to attach an image would need to look like this:
{
"name": "image.png",
"contentType": "image/png",
"contentUrl": "https://url.to/an/image.png"
}
This JSON should added to the output parameter in Teneo Studio. For more details on how to populate output parameters in Teneo, please see: How to populate output parameters in the Build your bot section.
To make it easier to create the JSON for common attachments and cards, we've created a helper class (a .groovy file) that you can add to your solution in Teneo Studio. You can find more details here: BotFrameworkHelper.
Sometimes you may wish to provide an answer using multiple text bubbles. This can be achieved by including an output parameter called outputTextSegmentIndexes
. This output parameter should contain a list of index pairs, to indicate where the output text can be split into separate bubbles. The value of the outputTextSegmentIndexes
should be structured like this (linebreaks are added for readability):
[
[startIndexOfFirstBubble,endIndexOfFirstBubble],
[startIndexOfSecondBubble,endIndexOfSecondBubble],
...
]
For example:
Output Text | outputTextSegmentIndexes | Bubbles |
---|---|---|
This should appear in the first bubble. This appears in the middle. And this in the last bubble. | [[0, 41], [41, 72], [72, 100]] | This should appear in the first bubble. |
This appears in the middle. | ||
And this in the last bubble. |
There are different ways to generate the value of outputTextSegmentIndexes
. The Groovy script below, is a global post-processing script that looks for two consecutive pipe symbols ||
in an output text, uses those to generate the value for outputTextSegmentIndexes, removes the pipe symbols from the answer text and adds the outputTextSegmentIndexes output parameter.
def outputTextSegmentIndexes = []
def outputTextSegments = _.getOutputText().split(/\|\|/)
if (outputTextSegments.size() > 1) {
def startIndex = 0
def cleanedOutputText = ""
outputTextSegments.each { textSegment ->
def endIndex = startIndex + textSegment.size()
if (textSegment) {
outputTextSegmentIndexes << [startIndex, endIndex]
}
startIndex = endIndex
cleanedOutputText += textSegment
}
_.setOutputText(cleanedOutputText)
}
if (outputTextSegmentIndexes) {
_.putOutputParameter("outputTextSegmentIndexes", "${outputTextSegmentIndexes}")
}
To use the script, proceed as follows:
Once added, whenever you add ||
to an answer text in Teneo Studio, the script will add the output parameter 'outputTextSegmentIndexes' with the proper index values and the connector will divide the text into multiple bubbles.
Note that this script works for both Microsoft Bot Framework and Teneo Web Chat. If this script was already added to post processing, you don't need to add it again.
The following input parameters can be included in requests to the Teneo Engine:
The input parameter channel
is included in each request and allows you to add channel specfic optimisations to your bot. The value start with botframework-
and the botframework channel is appended. For example, the value for requests from users that use Teams is botframework-msteams
.
Users can send attachment to the bot (for example GIF's from Teams). When that happens, the attachment details are included in an input parameter botframeworkAttachements
. The value is a string that looks something like this:
[
{
"contentType": "image/*",
"contentUrl": "https://media3.giphy.com/media/B0vFTrb0ZGDf2/giphy.gif"
},
{
"contentType": "text/html",
"content": "<div><div>\n<div><img alt=\"happy toddlers and tiaras GIF (GIF Image)\" height=\"242\" src=\"https://media3.giphy.com/media/B0vFTrb0ZGDf2/giphy.gif\" width=\"460\" style=\"max-height:250px; width:460px; height:242px\"></div>\n\n\n</div>\n</div>"
}
]
If you prefer to manually install this connector or run it locally so you can extend it, proceed as follows:
git clone https://github.com/artificialsolutions/tie-api-example-ms-bot-framework.git && cd tie-api-example-ms-bot-framework
npm install
ngrok http 3978
.env
file in the folder where you stored the source and the following parameters:
MICROSOFT_APP_ID=<your_microsoft_app_id>
MICROSOFT_APP_PASSWORD=<your_microsoft_app_password>
TENEO_ENGINE_URL=<your_engine_url>
node server.js
Was this page helpful?