Debug a bot from any channel using ngrok

APPLIES TO: SDK v4

While your bot is in development, you can use an IDE and the Bot Framework Emulator to chat with your bot locally and inspect the messages your bot sends and receives. If your bot is in production, you can debug your bot from any channel using ngrok. The seamless connection of your bot to multiple channels is a key feature available in the Bot Framework.

This article describes how to debug your bot locally using ngrok and a C# EchoBot in a channel connected to your bot. This article uses Microsoft Teams as an example channel.

Note

The Bot Framework Emulator and ngrok don't support user-assigned managed identity or single-tenant bots.

Prerequisites

Run ngrok

ngrok is a cross-platform application that can create a tunneling or forwarding URL, so that internet requests reach your local machine. Use ngrok to forward messages from external channels on the web directly to your local machine to allow debugging, as opposed to the standard messaging endpoint configured in the Azure portal.

  1. Open a terminal and go to the folder with the ngrok executable.

  2. Run ngrok with the following command to create a new tunnel.

    ngrok http 3978 --host-header rewrite
    

    Note

    The port specified is the port your bot is running on. You may use any localhost port you'd like.

  3. When ngrok starts, copy and save the public forwarding URL for later.

    ngrok forwarding URL

Configure in Azure portal

While ngrok is running, sign in to your Azure portal and view your bot settings to do some configuration.

  1. Select your bot resource connected to your local bot.

  2. Scroll down to Configuration. Copy and paste the ngrok forwarding URL in the Messaging endpoint field. Ensure that you maintain "/api/messages" at the end of the URL.

    Messaging endpoint

  3. Scroll up and select Save.

Test

At this point, incoming messages from to your bot from external channels will now be sent to your local bot. The sample bot we'll use to demonstrate this is already configured live for Microsoft Teams. Read Connect a bot to Microsoft Teams about connecting a local bot with Microsoft Teams channel.

Teams channel

Locally, you can set breakpoints in Visual Studio. Expanding the text property from the incoming activity object, you'll see that the message you sent the bot from teams is being intercepted locally for you to debug.

Set breakpoints

From here, you can debug normally, and run your code step by step. Use this to debug your bot from any channel.

Additional information