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:

  1. configuring a simple Node.js bot using the Bot Builder SDK samples and deploying the bot to your localhost server
  2. using ngrok to expose your bot to the public internet
  3. registering the bot on the Microsoft Bot Framework
  4. 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:

  1. In a Node.js console navigate to the hello-ChatConnector found at \botbuilder\Node\examples\hello-ChatConnector
  2. Run the command node app.js
  3. Make a note of the port, if you have not changed any of the app.js code the port should be 3978
  4. Open the emulator and change the Bot Url to http://localhost:3978/api/messages
  5. 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

Has your customer asked you, “Which build of Office do I need in order to get that cool API or requirement set?”

Here is some great guidance that addresses that question. Check out these topics:

Ever wanted to develop for Skype for Business? Then here is a great set of resources to get you started: 

Skype Web & App SDK documentation: https://msdn.microsoft.com/en-us/skype/skypedeveloperplatform

Skype Preview program: https://skypepreview.com

Office development: https://dev.office.com/Skype

Web SDK Overview: https://msdn.microsoft.com/en-us/skype/websdk/skypewebsdk

Web SDK API keys & feature grid: https://msdn.microsoft.com/en-us/skype/websdk/apiproductkeys

Web SDK API reference: https://ucwa.skype.com/reference/WebSDK/modules/_s4b_sdk_d_.jcafe.html

UCWA 2.0 General reference: https://msdn.microsoft.com/en-us/skype/ucwa/ucwa2_0generalreference

UCWA 2.0 API reference: https://msdn.microsoft.com/en-us/skype/ucwa/ucwa2_0apireference

Skype App SDK: https://msdn.microsoft.com/en-us/skype/appsdk/skypeappsdk

Skype App iOS API reference: https://ucwa.skype.com/reference/appSDK/IOS/

Skype App Android reference: https://ucwa.skype.com/reference/appSDK/Android/

Code Samples

If you haven’t read my Part 1 of this series then let me recap. Last week the Microsoft Office team announced the general availability of Excel REST APIs for the Microsoft Graph. With these new endpoints it is now possible to interact with your existing Excel Workbooks using REST from your mobile, desktop and web apps without the need to have to open the Excel app – pretty awesome eh?

In my previous post I demonstrated how you can call one of the 300+ built-in functions that Excel supports out-of-the-box. Sometimes though, the built-in functions that come with Excel are not enough. Sometimes we need to build our own Excel calculations to support our own LoB reports and visualisations. In this post I will demonstrate how you can re-use that functionality within your own modern day web and mobile apps.

For the purposes of this post I have created a simple Restaurant Bill Calculator within Excel:.

Excel Bill Calculator

This is a very simple example but it’s the concept of re-use of the calculation logic, in this case Bill+Tip and Amount per person, that I am trying to convey not it’s complexity.

I then created a visual representation of the Excel Workbook in an ASP.NET application – of course I didn’t need to create a web app, I could have created just a web API or a Console app,

Web App Calculator

So in this example we use the new Excel REST API to set the Excel Workbook named items, Bill Amount, Tip, and Number in Party. We then use the new Excel REST API to get the results by asking for the Excel Workbook named items Total Bill and Amount per Person..

In summary, complex business models no longer need to be rebuilt repeatedly; developers can leverage Excel to perform those calculations instantly and retrieve the results with simple API calls.

The full source-code for my sample can be found be here. Please refer to the readme file for pre-requisites and how to configure the app based on your Azure and O365 accounts. One important note, the sample relies on the fact that you have an Excel workbook called RestaurantBillCalculator.xlsx in the root of your tenant’s OneDrive – if the file does not exist the file is uploaded when you run the application for the first time. There are obvious changes that can be made to code to be more performant such as a namedItem that contains all of the fields rather than a nameditem per field, and not checking if the file exists each time.

If you want to start writing your own apps that use the Microsoft Graph then check out the following blog on how to get started with the Graph Excel REST API and as always, refer the Microsoft Graph API documentation for examples and syntax.

Its been awhile since my first post, but I have been waiting for the big announcement that I’m sure is going to change people’s mind-sets on how they interact with Excel today – introducing to you the general availability of the Microsoft Graph REST APIs for Excel.

In this post I am going to give you an example of how to use Excel as a Calculation Service, demonstrating how you can call one of the 300+ Excel functions from a ASP.NET MVC application using the Graph REST APIs for Excel.

The function I am going to call is the one highlighted in the GA blog post – PMT. The Excel PMT function calculates the constant periodic payment required to pay off (or partially pay off) a loan or investment, with a constant interest rate, over a specified period. The syntax of the function is:

PMT(rate, nper, pv, [fv], [type]]


rate = the interest rate per period as a percentage

nper = the number of periods over which the loan or investment is to be paid

pv = the present value of the loan / investment

[fv] = an optional argument that specifies the future value of the loan / investment, at the end of the nper payments

[type] = an optional argument that defines whether the payment is made at the start or the end of the period.

This function translates to the following REST API request:

POST …/workbook/functions/pmt { “rate”: 0.035, “nper”: 20, “pv”: -2000 }

Note, don’t fall into the same trap as I did when calling the function – as it is a calculation the values of the post request (body content) are numbers not strings!!

Check out the following blog on how to get started with the Graph Excel REST API and as always, refer the Microsoft Graph API documentation for examples and syntax.

The full source-code demonstrating how to call the PMT function using the Graph REST API can be found be here. Please refer to the readme file for pre-requisites and how to configure the app based on your Azure and O365 accounts. One important note, the sample relies on the fact that you have an Excel workbook called book.xlsx in the root of your tenant’s OneDrive. To make the solution more user friendly to a wider audience, why not try extending the code to automatically create a new workbook if Book.xlsx does not exist. [Hint, my next post includes the code to show you how this can be done]

In my next post I will demonstrate how to you can re-use your own existing Excel workbook functions in modern day web applications.  .

Managing Authentication flow within Office Add-ins has just got a whole lot easier with the introduction of the new Office UI Dialog API.

This post shows you how to create a simple Excel Add-in Command in Visual Studio 2015 that uses the new Dialog API to authenticate a user and then import their Outlook Contacts using the Microsoft Graph API.

If you are new to developing O365 Add-ins then I would highly recommend you check out the Getting Started page of dev.office.com. There are reams of examples and samples to help you get up to speed with links to the Office SDKs and a Yeoman Generator for Office if Visual Studio is not your thing.


The following is required to complete this module:

Step 1

In this step you’ll create a new Excel Office Add-in using Visual Studio. If you haven’t done so already, make sure you have downloaded and installed the Visual Studio Office Developer Tools.

With the latest Office developer tools installed open Visual Studio and choose File-New-Project. In the dialog prompt choose Office/SharePoint under Installed Templates-Visual C#.

VS Template

Choose Excel Add-in and enter a project name.

You will then be prompted to choose the type of add-in:

Addin type

Accept the default and press Finish.

Visual Studio will create 2 projects: an Office Project which contains the add-in manifest; a web project that contains the content for the add-in. If you want more detail about the anatomy of an office add-in please refer to the following resource.

Full source code can be found here but I just want to highlight some of the key areas:

  • (Contacts.js) Following the Dialog API guidance, create a displayDialog with the appropriate parameters:

dialog code

  • (Contacts.js) Specify how to handle the Dialog event type DialogMessageReceived. Note how the result message is parsed to extract the AAD access token:

message received code

  • (Auth.js) This solution uses the ADAL JavaScript library to simplify the Authentication process. For more information about these libraries please refer to the following resource. The key point here is the simplicity on how to authenticate with O365 credentials. The solution does not contain any login pages or credential stores – all of that is managed by ADAL based on the parameters that is provided.

auth code

  • (Manifest.xml) The Office manifest defines the requirements and the capabilities of the office add-in. As this Excel add-in will use Add-in Commands to deliver its functionality, the manifest needs to be structured accordingly: Note the manifest contains only one control which exexcutes a JavaScript function rather than launching an add-in Task-pane.


  • Based on the definition of the manifest this add-in has a single entry point which is a button on the Home Ribbon

ribbon button

Step 2

In this step you’ll go through the steps of registering an app in Azure AD using the Office 365 App Registration Tool. You can also register apps in the Azure Management Portal but the Office 365 App Registration Tool allows you to register applications without having access to the Azure Management Portal. Azure AD is the identity provider for Office 365, so any service/application that wants to use Office 365 data must be registered with it..

Once you have signed in you will be asked for some details about the app:


Feel free to give the app a name of your choice but the redirect URI must match what is shown above.

Once you hit register you will be shown a second dialog which will; hopefully say “Registration Successful” and show you your Client ID. Copy this value as you will need it to complete the Office add-in solution.

Step 3

Back in Visual Studio open the file App.js which can be found in the App folder.:

app details

The tenant is the O365 tenant you either created as part of the app registration or your existing O365 tenant name.


Build the solution.

Ensure the Office Project properties add-in start action is set to Office Desktop Client:

office properties

Press F5.

When you click the Get Contacts button in the Office Ribbon you should be prompted with the following dialog:

Authentication screen

Enter your O365 credentials (a user belonging to the tenant you specified in App.js) and if the user has contacts associated with the account then they should see them automatically added once the dialog is closed.

I hope you have enjoyed this post…feel free to send me any comments.