When using the Microsoft Bot Framework, to configure the bot to be available to a particular channel (e.g. Skype. Slack, Facebook, Teams, etc.) you need to host the Bot service on a public URL endpoint. The channel won’t be able to access your bot service if it is on a local server port hidden behind a NAT or firewall.
When designing / building / testing your code you don’t always want to have to keep redeploying and more importantly paying hosting costs – introducing ngrok,
ngrok allows you to create secure tunnels to localhost and thereby exposes your local server to the internet.
So what I thought I would do is walk you through:
configuring a simple Node.js bot using the Bot Builder SDK samples and deploying the bot to your localhost server
using ngrok to expose your bot to the public internet
registering the bot on the Microsoft Bot Framework
adding the bot to your Skype channel
1. Create a simple Hello, World! Bot
The easiest way to do this is to use one of the sample bots found here. Follow the instructions to clone the repository and then navigate to one of the samples. If you are getting started with bots then my advice is to start with one of the Hello World samples. For the purpose of this walkthrough I used the hello-ChatConnector.
If you want to make sure your bot is working without having to register it first, try using the Bot Framework Emulator following these steps:
- In a Node.js console navigate to the hello-ChatConnector found at \botbuilder\Node\examples\hello-ChatConnector
- Run the command node app.js
- Make a note of the port, if you have not changed any of the app.js code the port should be 3978
- Open the emulator and change the Bot Url to http://localhost:3978/api/messages
- Try the emulator by posting a message to the chat window. You should see something like this:
2. Using ngrok
Given the bot is being hosted on localhost:3978 now use ngrok to expose this port to the public internet. To do this simply type at a command prompt ngrok http 3978. You should the following UI:
Copy the forwarding Url – this is the public endpoint for the Bot service.
For the purpose of trying this out in the emulator, copy this Url to the Bot Url as per #1 – remember to include /api/messages.
You should notice that the emulator Url now shows as error ! to solve this open another command prompt and type ngrok http –host-header rewrite=9000
Doing so should now enable you to run the emulator but using public endpoints:
3. Register the bot on the Microsoft Bot Framework
If you haven’t already signed up to the Microsoft Bot Framework then you need to that first. Once signed up and signed in choose the Register a Bot tab.
The form will guide you through the steps required to register the bot. Ensure you copy the Microsoft App ID and Password somewhere safe, you will need to add these to your Bot service code. For the Messaging Endpoint use the forwarding Url captured in #2 that you used as the Bot Url.
4. Adding the bot to the Skype channel
Go back to the bot sample configured in step #1. You need to amend the app.js code file to include the Microsoft App ID and Password copied in step #3.
Once you have saved the changes follow the steps in #1 and #2 to deploy your bot to your local server and then use ngrok to make it public to the internet.
To ensure the changes you have made still work, use the emulator to test – you will need to update the Microsoft App ID and Microsoft App Password with the values captured in step #3. If you don’t you will get a 401 Unauthorized.
Finally, go back to the Microsoft Bot Framework portal and add your bot to the Skype Channel.
And that is it…you have your first bot running locally being served to the public internet using ngrok and available to chat with using the Skype channel.
As a next step, you can debug your bot service within Visual Code using the steps described in here