People often need to call external services to get the information that their users are looking for and so in this article I describe a simple sample application written by myself and my colleague David Curran which shows a common pattern whereby the conversation service provides a template response along with parameters which can be used by the calling application to retrieve the necessary information to give the end user the answer that they are looking for.
This pattern is useful in a lot of different situations, but we will use a fictitious application of where people want to use a conversational interface to track their parcels. We will leverage the simple conversation application as a starting point to minimise the amount of work. You can either download that sample and follow the steps below to add the interface to the conversation agent, or if your prefer you can download the completed example from our GitHub repository.
Adding the Parcel Intent to the conversation
In order to modify the conversation agent to handle parcel requests, you first need to add a parcel intent to the list of intents. The original sample contains 25 intents which is the maximum allowed with the free plan, so you will need to delete one of the existing intents. I deleted the weather intent since it is not being used and then I added a parcel intent with a few sample inputs as you can see below,
The next step is to add a node to the dialog to specify how parcel queries are to be dealt with. Our logic is quite simple. If a number is detected in the input we assume that this is the parcel number so we set a context variable parcel_num with this value and then we send back a response message with placeholders where the parcel location should be inserted. However, if no number is detected in the input stream, we simply reply saying that they need to supply us with a parcel number. For simplicity sake we won't consider holding context from one question to the next.
Implementing the dummy parcel lookup service
We don't want to use a real parcel lookup service for this sample, because when testing we won't know the parcel number for parcels in transit. Instead we will implement a very simple lookup service.
To implement the parcel lookup service you need to add the following function near the end of app.js
what this does is respond to get requests on /api/parcel and respond with one of the sample location names e.g. requesting http://localhost:3000/api/parcel?parcel_num=6 will return the string "Buckingham Palace". Just to illustrate how we should deal with errors, we have implemented the rule that if the parcel number is divisible by 13 it will return a status code 404 and an error message saying that the parcel number is unlucky.
To implement the parcel lookup service you need to add the following function near the end of app.js
what this does is respond to get requests on /api/parcel and respond with one of the sample location names e.g. requesting http://localhost:3000/api/parcel?parcel_num=6 will return the string "Buckingham Palace". Just to illustrate how we should deal with errors, we have implemented the rule that if the parcel number is divisible by 13 it will return a status code 404 and an error message saying that the parcel number is unlucky.
/**
* A dummy parcel tracking service
*/
app.get('/api/parcel', function(req, res) {
var parcel_num = parseInt(req.query.parcel_num);
if (!req.query.parcel_num || isNaN(parcel_num)) {
return res.status(400).end("Not a valid parcel number "
+req.query.parcel_num);
}
if (0 == (parcel_num %13)) {
return res.status(404).end("We can't find parcel number "
+parcel_num+" it is unlucky!");
}
var locations = [
'Anfield', 'Stamford Bridge', 'Old Trafford', 'Parkhead',
'Heathrow Airport', 'Westminister, London', 'Buckingham Palace',
'Lands End, Cornwall', 'John O\'Groats'
];
parcel_num = parcel_num % locations.length;
var location = locations[parcel_num];
res.end(location);
});
You should experiment with this service and/or customise it before moving on to the next steps.
Recognising a parcel location request and filling in the details
The main code modification we need to do is in the app.post('/api/message', function in app.js. However we first need to do some housekeeping changed due to the fact that we will be using the requestify library.
Add the following line to the dependencies section of package.json:
"requestify": "^0.2.5",
Then add this line near the top of app.js
var requestify = require('requestify');
The nub of the code is contained in the function below. You should paste this into app.js to replace the call to conversation.message which is around line 56 of the original file.
// Send the input to the conversation service
conversation.message(payload, function(err, data) {
if (err) {
// the conversation service returned an error
return res.status(err.code || 500).json(err);
}
var parcel_num = data.context.parcel_num;
if (data.intents && (data.intents.length>0) && data.intents[0].intent
&& (data.intents[0].intent === 'parcel') && parcel_num) {
var server = 'localhost';
var port = process.env.PORT || process.env.VCAP_APP_PORT || 3000;
var url = 'http://' + server + ':' + port +'/api/parcel?parcel_num='+parcel_num;
requestify.get(url)
.then(function(response) {
var location = response.body;
data.output.text[0] = data.output.text[0].replace( /\{0\}/g, location);
return res.json(data);
})
.catch(function(err){
data.output.text[0] = "Parcel lookup service returned an error: "+err.body;
return res.json(data);
});
} else {
return res.json(data);
}
});
The original code did nothing other than calling the updateMessage function before passing the data received from the Conversation service back to the UI layer. However, the updateMessage function didn't do anything useful so we can delete it and instead we will call our dummy parcel location service to find the location of the parcel whose number appears in the context variable.
If the http call succeeds we assume that we have a good location and we replace any placeholder {0} strings in the message received from the conversation service with this location. If we get an error status from the http call, we replace the entire string received from the conversation service with a message saying we failed to locate the parcel.
Summary
You have a conversation service which can reply to questions such as "where is my parcel number 543210" with details of where the parcel is located. It is currently only using a toy implementation which pseudo-randomly selects locations in the UK. However, it should be relatively easy to extend it to any real parcel tracing service you want. In fact, the methods used can easily be applied to interfacing with any 3rd party service.You can go to https://github.com/bodonova/conversation-parcel to download the complete working sample.
