Debug any Channel locally using ngrok

One of the key features available when you use the Bot Framework is the ability to seamlessly connect your bot to multiple channels, all from the same bot.

Click here  to learn more about currently supported channels, and how to connect to them.

While your bot is in development, you can debug and test your bot locally using the debugger for Visual Studio and Visual Studio Code for the .NET and Node.js SDK’s respectively. You can also use the Bot Framework Emulator to chat with your bot locally and inspect the messages your bot sends and receives. But what about when your bot is already in production? The Bot Framework Emulator uses an instance of the Web Chat control, which is only used in DirectLine, or embedded into web sites using a standard or custom configuration. Popular third party channels such as Slack, Facebook Messenger, Kik, etc. all implement their own chat channel user interfaces. In this post, we’ll discuss how you can locally debug your bot from any channel your production bot is configured for, using ngrok.

From the ngrok documentation “ngrok allows you to expose a web server running on your local machine to the internet.” 

Essentially, what we’ll be doing is using ngrok to forward messages from external channels on the web directly to our local machine to allow debugging, as opposed to the standard messaging endpoint configured in the Bot Framework portal.

Click here to download ngrok.

From the command line, run the following command:

ngrok http 3980 -host-header="localhost:3980"

Note: You may use any localhost port you’d like

When ngrok starts, it will display the public forwarding URL you’ll need to copy and save for later, as highlighted below.

While ngrok is running, login to the Bot Framework portal and view your bot settings and scroll down to Configuration. At your bot’s messaging endpoint, copy and paste the ngrok forwarding link in place of your existing url, as shown below. Ensure that you maintain “/api/messages” at the end of the URL as shown below:

Scroll to the bottom of the settings page, and then click ‘Save changes.’

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 Facebook Messenger. 

Locally, in Visual Studio we set breakpoints in the MessagesController.cs class provided by the .NET SDK. Expanding the text property from the incoming activity object, we’ve verified that the message we sent the bot from messenger is being intercepted locally for us to debug.

From here you can debug normally, and run your code step by step.

You can use this to debug your bot from any channel, using either the  .NET or Node.js SDK.

Happy Making!

Eric Dahlvang and Matthew Shim from the Bot Framework Team