Working with the Cisco Spark Flint Framework .hears Method

If you don’t like looking at code then you probably wont like this post much. There is a bit of a art of working with the .hears method in the Flint framework. Nick Marus has done a fantastic job of documenting its many uses but I thought it might be helpful to give some coded examples using JavaScript. In saying that of course with code there are a million ways to do this. I am not saying I have done this the right way or wrong way its just the way I worked out how to do it. Feel free to send me your own examples. I am always looking for more ways to do things.

Hears Function Filtering Process

 Flint processes each of the hears function calls sequentially, testing the received web hook messages against each of your .hears functions. So there are a few ways to handle processing the incoming web hooks. I like to break out my hears functions into individual pieces of code. I have heard of others and tried my self using the switch command to derive the different commands being feed to the bot to lower the amount of code. Personally I like to see each command broken out for processing. I also like to mix my bots with natural language processing(NLP) and slash commands. While users may like to use NLP to ask questions and make requests, as an admin I like the ease of a slash command to perform tasks like broadcasting to all the rooms the bot is in.

Bot Welcome Message

 This is a great way to introduce your users to your bot. This is not using the hears function but actually the spawn event I thought it was worth a mention.  As the room is spawned and your bot enters this provides a welcome message to your users or a way they can get help for your bot. I have tried more extensive bot introductions but users complained it was to much. Just a quick hello here is how you get help is enough. Seeing as your bot may be in one on one or group rooms you may want to address each a little different. Remember bot accounts in a room only receive a web hook message if @mentioned.

Slash Commands

This is the bread and butter for a bot. Slash commands are actually pretty easy to handle. Nick has already taken care of removing the @mention when a /text is seen by the bot. This makes this type of command pretty simple to take care of. If the command itself is the only thing being processed you are ready to provide your bot logic and return your response using bot.say function. If you actually have text following the command you may want to strip the command out before more processing. The broadcast command example further along in the post provides an example of removing the base slash command. The example below also introduces the use of the trigger object to extract information from the incoming message. In this case the trigger.roomId. This is maybe something that your users are not to interested in but its a great way to quick grab your roomId when doing some development and testing.

Simple Reply

This example is basically the "hello world' for a bot. But it does show another important attribute of the trigger object. personDisplayName and personEmail are two handy attributes for dealing with bot hear function requests. We will take a look at the use of the personEmail attribute a little further on.

Broadcast and Restricted Commands

 This is a really handy bot command for event bots. Now you may be wondering what I am talking about. I have been to a number of conferences recently where bots have been used to provide information and encourage attendees to get involved with whats going on. I personally used a very simple bot at the TechCrunch hackathon to work with attendees and let them know when pizza was served. The thing with this command is you don't want everyone to have access to it. Last thing you need is some prankster letting loose with something obscene message to every room the bot is in. In my case I am using email to restrict the use of this command but you could take this further and include roomId as well. Another thing you can also use this method for is to restrict down who can interact with your bot to a domain. So if I use Cisco as an example I can build a bot just for internal use and say anyone with a cisco.com email address is good to go and everyone else gets a unauthorized access message.

NLP Processing

The NLP hears function I like to be the last hears function as a catch all after all the slash commands and everything else has been tested. The trick to this function though is that if you don't have a method to remove previously processed hears functions it will process them all over again.  I like to use the match function to test if commands had previously been used. Although this leads to having to edit a hears command function and this catchall function every time you add a new slash command I am sure a smart developer can work out how to fix that. This is just the way I worked out how to get around it. The whole idea of this function is to be able to send the request to a NLP engine for further processing and then use the response from Watson or api.ai etc. to send back your response to your user. Now if you do use the NLP response or do something else with the response from an NLP engine is totally up to you but this is the best way I found to capture the needed info from the user.

Posting Markdown and Files

Not really a hears function but still important is you want to make use of markdown or posting files using the Flint Framework using the bot.say function. Nick has changed this method a little between versions added the markdown JSON object. Pretty easy to understand once you see the example below.

Please comment if you have found more inventive ways to use this function.
VoIPNorm