You may recall Don Henley of Eagles fame, who crafted one of the best rock albums of all time, “Building the Perfect Beast.” At the time, Rolling Stone magazine referred to it as “meticulously crafted and programmed.” The title song’s refrain goes:
“And now the day is come
Soon he will be released
Glory hallelujah!
We're building the perfect beast.”
So indulging this metaphorical theme (thanks, Don), if you will, how do you, as a Cisco Spark Developer, embark on “Building the Perfect Bot?”
We’ve got the answers here on Cisco for Spark Developers. These include Cisco best practices when building a new bot that will help you and your bot improve the functionality and overall usefulness of Cisco Spark.
What are bots in Cisco Spark?
Many Cisco Spark bots reside on the Cisco Spark Depot and are identified by a “bot badge” that’s overlaid on the bot’s thumbnail:
Just click on the title, and the hyperlink takes you to the bot and further details on it.
Users can add bots in Cisco Spark via the Spark Depot or in Cisco Spark using the bot’s e-mail ID (e.g. ToChineseSimplified@sparkbot.io). Users can create a private conversation to talk with a bot directly or can add it to an existing space with others. In the latter, for security reasons, bots can only see messages in which they are @mentioned.
How to Build the Perfect Bot
The bots you create for Cisco Spark should always be focused on improving the user experience. With that in mind, beyond creating the bot, it’s crucial that you include/provide clear instructions to guide users on how to use your bot.
As you know, bots started out as very simple, very basic tools for people to interact with (e.g., chatbots) to complete simple, basic tasks. As bots have increased in sophistication and capabilities, Cisco wants to ensure those you are planning to build will effectively enhance the capabilities and usefulness of Cisco Spark.
With that in mind, check out these Cisco Spark ‘bot building’ best practices below.
For Effective User Interaction, we recommend:
- Create a help guide for users – Don’t assume they’ll immediately know what your bot is for and/or how to use it. Building and providing a simple, companion help menu is a great way to achieve this.
- Ensure users have control over the bot – If it is a broadcast or notification bot, be sure to have a command like “edit notifications” that can easily allow users to edit or delete their bot activity, including how to unsubscribe from the bot, if desired. Be sure to list this command in your help menu, too. If you need help building this key component, check out this previously posted Cisco blog explaining how to accomplish this.
- Listen to what your bot’s users have to say – Include a “feedback” command to accept feedback directly from Cisco Spark users. In addition, we encourage you to include a “support” command so you can receive bug reports.
- Include basic commands – Your bot needs to be able to respond to basic and common commands, such as “@BotName help” and “@BotName hi.” For Cisco Spark users, it’s a common, intuitive way they start an interaction with a bot.
- Include error handling – Your bot also needs to be able to respond to any commands it doesn’t recognize. For example, a response to an error could be, “I’m sorry, I don’t recognize that command,” followed by a list of sample commands to try to resolve the error.
- Consider utilizing NLP – Natural Language Processing (NLP) is an alternative to creating a command driven bot. Services like API.ai and Zenbot integrate with Cisco Spark to enable you to incorporate NLP into your bot. Another option is Botkit, which has plugins including IBM Watson, API.ai, WIT.ai, and Luis.ai that you can leverage.
- Communicate new features – As you add new functionality and/or commands to your bot, enable it to inform users by including a special command or broadcast.
- Simplify option selection – Number your options instead of just naming them, so the user can choose and act on one without having to type out the full word or phrase.
- Create effective message posting to spaces – Several tips in this regard include:
- Use Markdown to format all links as hyperlinks, and to format your messages with spacing, line breaks, and bullets for better readability, eliminating ‘mashed up’ walls of text. The Spark for Developers website’s Formatting Messages page is chock full of examples to help you.
- Avoid hammering spaces with many successive messages, since a bot that takes over a space will often be quickly kicked out. Instead, either group them together in larger, formatted messages or insert delays so they’re delivered more slowly/methodically.
- Since the Spark user community is global, consider giving the user customization options for things vital to interacting with your bot, but that may vary globally (e.g., metric versus imperial measurements). Communicating the wrong terminology can create user misunderstandings and confusion of what the bot is posting, rendering it useless.
- Communicate when your bot encounters an error message (e.g., whenever Spark API calls (e.g., GET, POST on /X resource) are down and throwing out specifically 5xx error codes (i.e., excluding/messages), so users are aware there is/are (a) problem(s).
For Creating Naming Conventions, we recommend:
- Naming what it does – Name your bot to what it does (e.g., “SparkHelp”). If you prefer to personalize your naming, avoid using actual personal names, such as John Doe, to avoid your bot being confused with an individual.
- Name clearly and simply – Abbreviated names when your bot is mentioned, e.g., “The Best Bot,” might be tagged as just “The” when mentioned in a group space, which could make reference to it unclear. We recommend that bot names contain at least three unique letters in the first word (i.e., don’t use “The”), so that they accurately display for “quick tagging.”
Finally, be prepared to effectively address and resolve potential issues with using/interacting with your bot by considering and providing solutions for these bot edge test cases, including:
- In a space with many users (e.g., 20 or more), what happens if multiple users @mention your bot simultaneously?
- What happens if your bot is added to a space from which it was previously removed?
- What happens if a user talks to your bot using similar words as your commands, but not the exact matches?
- What happens if a user sends an extraordinary amount of requests (e.g., 1,000 messages a minute) to your bot?
- If your bot has an auto-reply feature, does it prevent looping between other bots with a similar feature?
Make the Metaphor a Reality
In conclusion, remember good communication is essential to building a useful and successful bot for Cisco Spark. If your bot is hard to understand and communicate with, it makes it difficult to use, and that means Spark users will stop using it. That’s why we’re here to help. You’re a vital part of the Cisco Spark ecosystem, and thus we encourage you to consider implementing these suggested best practices for our continued mutual success.
To learn more, we also recommend you visit https://developer.ciscospark.com/bots.html
So go forth and meticulously craft, program, and build that perfect bot for Cisco Spark, so you can paraphrase Don Henley’s refrain:
“And now the day is come
Soon it will be released
Glory hallelujah!
We're building the perfect bot.”
- Rebecca Amato, Product Manager
