Microsoft Bot Framework

This node.js example connector allows you to make your Teneo bot available using the Microsoft Bot Framework, allowing you to target channels like Skype, Microsoft Teams and Cortana. The connector acts as middleware between the Microsoft Bot Framework and Teneo. This guide will take you through the steps of registering a new Microsoft bot app and deploying the connector and make it available via Skype.

You can find the source code of this connector on Github.



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.

Teneo Engine

Your bot needs to be published and you need to know the engine url.

Setup instructions

Create an app in Microsoft's Application Registration Portal

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 in Microsoft's Application Registration Portal.

  1. Go to and choose 'Add an app'
  2. Provide an 'Application Name' (for example, your bot's name) and click 'Create'
  3. Copy the 'Application Id' in the 'Properties' section, you will need it later.
  4. Under 'Application Secrets' click 'Generate new password'. Copy the password that is shown in the popup, you will need it later.

    Make sure you store the password securely. This is the only time it will be displayed.

Deploy the bot connector

Click the button below to deploy the connector to Heroku:


  1. Give the app a name (lowercase, no spaces)
  2. In the 'Config Vars' section, add the following:
    • MICROSOFT_APP_ID: The 'Application Id' you copied earlier.
    • MICROSOFT_APP_PASSWORD: The Application password you copied earlier.
    • TENEO_ENGINE_URL: The engine url.
  3. Click 'Deploy app'.

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.

Register a bot with the Azure Bot Service

To register your bot with the Azure Bot Service, you will need to create a new 'Bot Channels Registration'.

  1. Visit and click 'Create a resource' in the top left corner.
  2. A new window will appear, use its search function 'Search the Marketplace' and search for 'Bot Channels Registration'
  3. Click 'Create' in the new 'Bot Channels Registration' window
    • Depending on your Azure account, you may need to click 'Start free' and once your subscription is done, you can proceed with setting up the bot

Setting up the bot

  1. Give the bot a name, this name will be available on Skype etc.
  2. Provide the details for the Subscription, Resource Group (If you don't have one, create a new one), and Location
    • Depending on your Azure account you may need to specify a 'Pricing Tier'. You can choose the free tier 'F0 (10K Premium Messages)' during development.
  3. Enter the following URL in the Messaging Endpoint field: https://[yourherokuappname] (replace [yourherokuappname] with the name of your app on Heroku).
  4. Click on 'Auto create App ID and password' and in the 'blade' that appears click 'Create new' and in the next blade that appears enter your Application Id and Application Password and click 'Ok'.
  5. Click 'Create' in the first blade to create your bot. You will be notified when the bot is available.

That's it! You can now test your bot by opening your bot resource by clicking on 'All resources' on the left then select your bot. Under Bot management select 'Test in Web chat'.

Add a channel

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:

  1. Click on the featured 'Skype' channel. This will make your bot accessible from Skype.
  2. Go back to the 'Channels' list. Skype should now also be shown in the list of channels for your bot. Click on the link 'Skype'.
  3. A new page will open. Click the 'Add to Contacts' and follow the instructions to add your bot to your Skype contacts
    • Note: it may take up to 30 minutes for your bot to be fully deployed on Skype, even after you have added it as a contact in your Skype app.

Adding media to messages

To add media or cards, this connector looks for an output parameter msbotframework in the engine response. The value of that parameter is assumed to contain the media or card JSON as defined by Microsoft.

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": ""

This JSON should added to the output parameter in Teneo Studio. To make it easier to create the JSON for Hero cards and images, we've created a BotFrameworkHelper class (a .groovy file) that you can add to your solution in Teneo Studio. You can find more details here: BotFrameworkHelper.

For more details on how to populate output parameters in Teneo, please see: How to populate output parameters in the Build your bot section.

Running the connector locally

If you prefer to manually install this connector or run it locally so you can extend it, proceed as follows:

  1. Download the latest release of the connector.
  2. Install dependencies by running npm install in the folder where you unzipped the connector.
  3. Make sure your connector is available via https. When running locally you can for example use ngrok for this: The connector runs on port 3978 by default.
  4. Start the connector with the following command (replacing the environment variables with the appropriate values):
    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?