santas helper

Santa’s Nexmo Helper – C# Advent Series

Published December 19, 2019 by Steve Lorello
Categories:

‘Tis the season of Advent, such a busy time for so many, but none more than Ol’ St. Nick, whose feast day the Eastern Rite celebrates today. In honor of the season of C# Advent that’s upon us, we’re going to help Santa out by automating some of his correspondence and providing him more modern means of fielding questions than the postal service.

To crystallize our goal here, we are going to create an FAQ bot for Santa that can be reached over, and respond via, Facebook Messenger, WhatsApp, and SMS.

We’re going to build this with the help of QnAMaker and of course the Nexmo Messages API

Prerequisites

  • Visual Studio 2019 version 16.3 or higher
  • A Nexmo account. If you don’t have one, you can sign up here
  • An Azure Account
  • Optional: Ngrok for test deployment
  • Optional: For Facebook Messenger, we will need to link a Facebook Page to our Nexmo account—you can see step by step instructions on Nexmo Developer. Completing part 2 of the guide will create a Nexmo App with a linked Facebook Page; be sure to save the private key file that is generated for this application.

Note: The code in this demo will work with WhatsApp Messages once WhatsApp Business is configured. That said, WhatsApp is more meant for a business case—to see more details about getting an app configured for WhatsApp you can look at the guide on Nexmo Developer

Building Our Bot

Setup

To build out our bot we are going to head over to QnAMaker and sign in using an Azure account.

Click “Create a Knowledge Base”.

Follow the instructions in step 1 for creating a QnA service in Azure.

For Step 2, set the following:

  • Microsoft Azure Directory ID
  • The Subscription’s name from the Azure account
  • The QnA service we’re going to use (this will match the Service Name we just created in the Azure Portal)
  • The language of our bot

Build QnAMaker gif

For Step 3 we’re going to name our knowledge base “Santa’s Nexmo Helper.”

Step 4 is where QnA Maker gets cool—populating this bot’s knowledge base is as easy as linking it to an FAQ page or uploading an FAQ file. Of course for this demo, we’re going to use the official Santa Claus website’s FAQ page.

We’re also going to add some chitchat to our bot—since our bot is going to be an honorary elf, we’re going to use the witty chitchat selection

With all this set, click Create Knowledge Base.

This will ingest the FAQ’s that we pointed QnA Maker at and will bring us to a page that looks like this:

QnA Maker Knowledgebase edit screen

Editing, Publishing, and Testing Our Knowledgebase

This is our Knowledgebase edit screen. From here we can see what our knowledge base looks like. We can also freely edit it if we want to change some answers; e.g. maybe let’s shorten the “Who Is Santa Claus?” answer.

After editing the Knowledge Base sufficiently, clicking Save and Train will save and train the Bot.

To test, click the Test button in the upper right-hand corner. This will open the testing dialog, you can send id a question e.g. how do reindeer fly? and the bot will respond!

Test Question

It’s even possible to inspect how the bot made its determination. Click the inspect link and the inspection dialog will pop out. This will show the bot’s confidence in its answer and some alternatives it came up with.

Inspect Drill down

When the bot’s ready to go, click publish on the top of the page, then click publish inside the dialog that shows up. When this completes there will be a screen that pops up with some helpful request structures that can be used to generate an answer from the bot. It’ll look something like:

Save this string—it’s going to be used to create the WebService that will drive our bot over the Messages API.

Building Our App

Start by opening Visual Studio and selecting “Create a New Project.” In the dialog that opens, select an ASP.NET Core Web Application. Name it something like “QnAMakerMessagesDemo.” Select ASP.NET Core 3.0, “Web Application (Model-View-Control)” as the type and click create.

Install NuGet Packages

In Visual Studio go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution.

Install the following NuGet packages:

  • Newtonsoft.Json
  • Nexmo.Csharp.Client
  • BouncyCastle
  • jose-jwt

Building Our Token Generator

Create a class called TokenGenerator and add the following code to it:

This will generate the JWT that’s needed to authenticate against the Messages App created as part of the prerequisites.

Add appId and the Private Key Path to the Configuration

The JWT generator calls on an appId and path to the private key saved earlier to be in the appsettings.json file.

Open this file and add the following to the configuration object:

Build Data Structures to Receive and Send Data

A couple of POCO’s are needed for this demo; they’re a tad verbose, and don’t do anything except define the messages objects per the spec, so the full structure is omitted from this post. Simply add the following classes to the project:

InboundMessage.cs
MessageRequest.cs

Send Messages

With the structures sorted the next step is to send messages across the Nexmo messages API. Create a class called MessageSender, this will have a single static method SendMessage which will simply create a Message Request, create a JWT, create a request, and send the request to the Messages API—it should look something like this:

Ask the Bot a Question and Send a Response

Now it’s time to talk to the FAQ bot from the app. This is where the sample REST calls that QnAMaker presented earlier will come into play. Recall this string from earlier.

Use that string to create some useful constants/readonly’s for the Questioner—fill in with appropriate values from the string above:

Next, create a task to ask the question:

This simply formats the question from the messages API and sends the request off as a generateAnswer post request to the QnAMaker bot.

Finally, create a method to drive the request and reply with an answer.

Build Controller to Receive Incoming Messages

The final piece of the puzzle is the controller that will handle the influx of messages from the Messages API. Create an empty MVC controller called MessagesController.

Dependency Injection and Configuration

Add an IConfiguration field called _config to this and set up Dependency injection of configuration by creating a controller constructor taking an IConfiguration object:

Status Request

Next create a Status Post request that simply returns no content:

Inbound Messages

Next, add a Post Request for inbound messages from the Messages API.

This method will extract the inbound message from the body, then forward on the Questioner tasks from the content of the request body.

Inbound SMS

Finally, add an HttpGet request to manage the inbound SMS messages. This will similarly extract the needed information from the inbound message and ask the question of the questioner.

With this sorted, the service is ready for deployment.

Testing

The last thing needed is to fire up the service, expose it to the internet, and wire up the Nexmo Messages App to send webhooks to the service.

IIS Express Configuration

For simplicity this demo uses IIS. To make setting up ngrok easier disable SSL for IIS Express by going into the project Debug properties and unchecking the “Enable SSL” setting:

Debug settings

Take note of the port number in the app URL field, it will be used in the next step.

Setting up Ngrok

The next step is to expose this endpoint to the internet. For this demo, something like ngrok can be used to create a tunnel back to the IIS Express port. After installing ngrok use a command like:

To set up the tunnel, replace ‘PORT_NUMBER’ with the IIS Express port number noted earlier. This will create an output that looks something like this:

ngrok output

Take note of the http base url here—in the image above the base url is http://dc0feb1d.ngrok.io.

Configuring webhooks

The final step before turning the service on is to configure the webhooks to callback into the service.

Inbound SMS

Go do the Nexmo Dashboard and go to Settings. Set the Inbound Messages URL for SMS to the ngrok_baseurl/messages/InboundSms, given the example above.

Other Inbound Messages

In the Nexmo Dashboard open Messages and Dispatch -> Your Applications. Open the application associated with the linked accounts, and click ‘Edit’. Under Capabilities in the Messages section, set the Inbound URL and Status URL to match the ngrok baseurl /Messages/Inbound and /Messages/Status respectively and click save.

Per the example ngrok tunnel it will look something like:

messages urls

NOTE: The 8 characters preceding ngrok.io are not fixed on the free tier. This means every time the ngrok command is run it will be necessary to change where the webhooks are aiming. It’s possible to create a static hostname by upgrading to a paid ngrok tier.

Fire It Up and Test

And that’s it! Santa’s Nexmo Helper is ready to deploy. Fire up IIS Express and message away. This can be reached over any channel configured to reach the messages app.

Here’s an example from Facebook:

Facebook Example

And one from SMS:

SMS Example

Well, there it is, Santa’s Nexmo Helper is up and operational.

Further reading

  • Full source code for this demo can be found in GitHub
  • For more info on QnAMaker check out their website here
  • For fully interactive bots check out Luis Ai
  • For more information on the Nexmo Messages API, check out the documentation on Nexmo Developer
  • For more APIs by Nexmo check out our Developer site
  • To check out the Nexmo .NET SDK you can take a look at out our GitHub Repo

Leave a Reply

Your email address will not be published.