Connect to a remote skill

The Bot Framework supports skills, which are bots that encapsulate bits of conversational logic that can then be used to extend other bots. The bot that contains the skill is a skill bot and the bot that accesses the skill is a skill consumer, also referred to as a root bot, if it's the initial bot the user interacts with. You can build a user-facing bot and extend it by consuming your own or third-party skills, without the need to access the skill's source code.

To develop and test a root bot that accesses a deployed skill, the root bot needs an endpoint that the skill can send replies to. The root bot will forward the skill's replies to the user.

This article describes how to connect a root bot running locally to an already deployed skill. The local root bot uses an Azure Bot Channels Registration and ngrok to provide an endpoint in the cloud that forwards to a local endpoint on your machine.

If you don't have a skill yet or you're looking for how to create a remote skill with Composer, read the Export a skill article.


Connecting to a skill in Composer is a technical process that involves many steps such as setting up Composer and configuring Azure resources. A high level of technical proficiency will be necessary to execute this process.


Create a Bot Channels Registration

If you don't already have a Bot Channels Registration resource you want to use for your root bot, create one:

  1. Open the Azure portal and select + Create a resource on top of the menu.
  2. Enter Bot Channels Registration in the search box and select Enter.
  3. Select Create from the pop-up window and then fill in the creation form to create your Bot Channels Registration. The registration used in this article has a bot handle of "LocalRootBot".

Get the App ID and password

If you don't already have a record of the Bot Channels Registration resource app ID and secret, record both values. If you don't have a copy of your secret, you will need to create a new secret.

  1. In the Azure portal, go to the Bot Channels Registration for your root bot.

  2. Select Configuration in the Settings group from the left pane.

  3. The App ID is displayed in the Microsoft App ID (Manage) section.

    Get the app ID from the Configuration pane.

  4. To create a new secret, select Manage from Microsoft App ID (Manage). The portal will open a Certificates & secrets pane.

  5. Select New client secret. Enter some description in the Description field (this is optional) and select an expiration time from the Expires list. Select Add.

    Create a new client secret from the Certificates & secrets pane.

  6. Copy the value from the Value field of the displayed table. This is the generated password of your Bot Channels Registration.

    Get the new client secret from the Certificates & secrets pane.

For more information about creating a Bot Channels Registration, refer to the Register a bot with Azure Bot Service article.

Create a root bot in Composer

You can create a new bot or use an existing one to use as a root bot with which to call the skill. After adding the remote skill to your project, you can add an action to your root bot to call the skill. The root bot in this article is named "LocalRootBot".

  1. Add the remote skill to your project:
    1. At the top of the navigation pane, select Add (+), then Connect a remote skill.

      Add menu for adding a skill.

    2. Enter the URL for the remote skill manifest. Composer will validate the URL and populate the Skill Endpoint list.

    3. Select the skill endpoint the root bot should use to call the remote skill, and then select Confirm. A skill must advertise at least one end point; however, it can expose more. The manifest should describe which features are available for each endpoint.

      Dialog for adding a remote skill using its manifest URL.

      You will then see the remote skill added in the Navigation pane.

      Local root bot project with the remote skill added.

Now the remote skill has been added to your bot project!

Forward replies from the remote skill to your local bot

Use ngrok to create a public URL to use as base URL for the skill endpoint.

The local root bot needs to provide the remote skill with a skill endpoint that the skill can send replies to. This skill endpoint needs to be in the cloud, since the remote skill is.

  1. Select Start bot from the toolbar. Once the bot's runtime has started, the Local bot runtime manager opens.

    1. In Local bot runtime manager, hover over Test in Emulator to see the local messaging endpoint for your root bot.

    2. Note the port number that your root bot is using. For example, if the messaging endpoint is http://localhost:3980/api/messages, then the port number is 3980.

      The copy button for the messaging endpoint.

  2. Use ngrok to create a public URL.

    1. Open a terminal and navigate to the folder that contains your ngrok executable file.


      If you do not have ngrok installed, follow instructions to install ngrok.

    2. Run ngrok with the following command to create a new tunnel, the port specified is the same port your consumer bot is running on:


      ./ngrok http 3984 --host-header=localhost


      "ngrok.exe" http 3984 --host-header=localhost
    3. Save the httpsentry generated by ngrok. You will use this when you update the root bot configuration settings in Azure. (The public URL expires after a set amount of time, so you may need to regenerate the public URL if you need it for more than an hour.)

      Output from a call to ngrok.

Connect to the skill from your bot

  1. From the Navigation pane, select the trigger in the root bot that you will use to call the remote skill.

  2. Add the Access external resources > Connect to a skill action to the trigger.

    Add the Connect to a skill action to a trigger.

  3. In the Properties pane on the right side, set the following properties:

    1. For Skill Dialog Name, select the remote skill you want to connect to.

    2. For Skill Endpoint, select the endpoint to call.

      The Connect to a skill action and its properties.

    3. Set Activity processed to false; this will cause the root bot to forward the user activity for the turn to the skill.

    4. If the skill might return a value, you can provide a memory path to save the value in in the action's Property field. For example, you could set Property to dialog.result.


    To send a different activity to the skill, set Activity processed to true, and use the Activity field to provide the activity to send to the skill.

Update the root bot configuration

  1. From the Composer menu, select Project Settings. In the Navigation pane, select the consumer bot.

  2. In the consumer bot's configuration:

    1. In the Skill Host Endpoint field, update and enter the public URL generated by ngrok and add /api/skills to the URL. (See Forward replies from the remote skill to your local bot section for how to use ngrok.) The skill host endpoint should look similar to https://<identifier>, where <identifier> is a unique identifier.


      Without /api/skills as part of your skill host endpoint, your consumer bot will generate HTTP 500 status codes when trying to connect to your remote skill.

    2. Update the App Id / Password fields with the values from the Bot Channels Registration resource you created in the Get the App ID and password section.

      Project settings for the root bot.

  3. Still on the Project Settings page, toggle Advanced Settings View (json). Update the allowedCallers property of the skillConfiguration settings.

     "skillConfiguration": {
       "isSkill": true,
       "allowedCallers": []
    Property Description Type Example value
    allowedCallers The msAppIds of all the bots it connects to. Set to "*" to allow all callers. array "123-34-456", "234-45-567"

Your consumer bot is now configured to connect to the remote skill!

Test in the Emulator

You can now test your local root bot's ability to connect to the remote skill.

  1. Select Start bot in the upper right hand corner of the screen. This launches the bot's runtime.

    Animation of starting the bot.

    Once the bot's runtime has started, the Local bot runtime manager will open.

  2. In the Local bot runtime manager window, select Test in Emulator to test the bot-to-bot connection.

  3. Enter text in the Emulator and see the response.

    Example interaction with the local root bot accessing the remote skill.

Further reading