Design guidelines

This guide tells you what principles to follow when you design how your bot looks, talks, and interacts with users.

Why build a bot for Hangouts Chat?

Bots provide a lightweight, conversational way to connect services to users in Hangouts Chat. Great bots deliver quality services while leveraging the advantages of the medium.

Bots are ideal for:

  • Returning information (for example, by searching a data source)
  • Helping users to perform a specific task
  • Sending notifications about updates, edits, or recurring events

To summon a bot in a room, a user @mentions the bot (for example, by typing "@WorkerBee") and then selects the bot from an autocomplete menu.

If you enable the capability for your bot, users can send a direct message to the bot once they've installed it from the "Message a bot" screen.

Plain text vs formatted cards

Bots can interact with users with either plain text or formatted cards. The following paragraphs present some guidelines on when to use each.

Text

Text is the primary medium for a bot's communication. Well-written text can guide users in a straightforward way, and allow them to respond naturally.

Cards

Use cards when you want to do the following:

  • Succinctly display information and provide visual flair
  • Include more advanced formatting like key/value pairs, images, and icons

Rooms vs direct messages

You can enable your bot in rooms, in direct messages, or both. We recommend you enable your bot in both, even if you want to limit the experience to one or the other.

But what if you want users to interact with your bot in rooms only? We recommend the following practice:

  • Enable your bot in direct messages (as well as in rooms)

  • If your bot receives a direct message, have it respond with a simple reply that directs the user to the right place.

This helps with discoverability for your bot, makes it appear intelligent, and provides another opportunity for user education.

Writing style

This section provides guidance on how to compose text from your bot.

Principles

Be brief. Break up large chunks of text into multiple messages. Avoid saying everything in favor of saying the important things.

Good:

Not so good:

Each message has one purpose. The value of bots is the ability to interact quickly. Be resourceful with your bot's messages. Try to limit them to one call to action, and make the information presented as relevant as possible.

Good:

Not so good:

Be transparent. Don't overpromise. Make sure the user knows what your bot can do and what it can't do.

Good:

Not so good:

**Avoid personification. **Your bot should focus on its utility, not its character.

Good:

Not so good:

Use appropriate voice

Voice refers to the way your bot reflects the service that it represents. Each bot is different, and the choice is ultimately yours.

To communicate effectively with Hangouts Chat users, your bot's voice should convey the following characteristics:

Professional. Your bot will be helping people at work. Make sure its personality fits into a professional setting, or it may feel jarring and inappropriate.

Authentic. Bots can speak colloquially, but should not pretend to be human. Avoid giving your bot a gender, or a name that could be confused with a real person.

Humble. There are few opportunities to convey your bot's user benefits. Don't waste them on vague claims. Undersell and overdeliver.

Considerate. Be thoughtful and noninvasive. Your bot shouldn't bother users unnecessarily. It should strive to anticipate user needs and offer solutions.

Efficient. Recognize that most users aren't looking for chitchat. Help people complete tasks by keeping the bot experience focused.

Use appropriate tone

While your bot's voice should be crisply defined, tone can vary depending on the context. Here are some tonal notes we think are particularly important to hit when writing for bots.

Encouraging. Bots are new to most people. Be optimistic and friendly with the user as they explore.

Attentive. Your bot should make the user feel as if they're important and cared for.

Optimistic. Bots will fail the user at times. Remain optimistic in these moments to keep the user engaged and hopeful about future interactions.

Communicating with the user

Conversing with a bot can be confusing. Here are a few principles to help ensure users have a smooth and engaging interaction.

Use confirmations

It's good to let the user know when actions have been completed. Quick confirmations like "Done!" or "OK, you're all set!" are better than silence.

Keep confirmations short. This not a good place to inject new information, or tell the user about other things they can do.

Be responsive

The user should never be unclear about whether the bot "heard" them. Work hard to reduce latency; if latency is unavoidable, make sure you touch base with the user in the interim.

Avoid spamming users

Be mindful of how much your bot is posting. If your bot can be configured to send a lot of updates or notifications, make sure users are clear on how to dial down the noise by including that in your "Help" message.

Allow cancellations

If your bot makes changes to a user's data, make sure they can quickly undo the changes.

Check for spelling, punctuation, and grammar

Avoid obvious spelling and grammar mistakes. Look out for typos, and have someone with strong English skills review your bot's messages before submitting.

When in doubt about grammatical style, consult the Google Material writing guidelines.

Help the user in need

Make sure your bot can communicate with the user if they're lost or stuck. Error messages are crucial to a high-quality bot experience. Consider making a generic help message that users can trigger at any point if they don't know what to say.

Stages of the life cycle

A user's experience with your bot has a life cycle, starting when the bot is invoked and ending when the user action is complete. Your bot should navigate the user through the stages of that cycle with good messaging.

Initiation

Setting expectations about what your bot does is crucial. You must craft a welcome message that triggers automatically when the user adds your bot to a room or messages it directly.

The welcome message should include a few pieces of information:

  • Include a one-sentence introduction (name and bot function are important)
  • Include a prompt for the user to begin interacting with the bot

There are also some things your welcome message should not do:

  • Don't tell the user everything they can possibly do with the bot at once
  • Don't send large, overwhelming blocks of text

Progressive guidance

If there are multiple steps in the user's journey, you may want to offer textual indicators to help ground them. Transitional phrases like, "Next, what size do you want?" help keep focus and orientation.

You may want to announce when the user is near the end of a long journey. Phrases like, "Last step..." or "One more thing" can help reduce user fatigue.

Rerouting

If the journey has stalled for any other reason, and the action has not been completed, help guide the user back towards the beginning.

Supporting specific commands

There are a few important commands that we either require or strongly suggest your bot support. These commands will become familiar to Hangouts Chat users who have used other bots in the ecosystem, and so they'll come to expect every bot can handle them.

A good place to communicate that your bot handles these commands is in your welcome message.

"Help"

This command is required for all bots. A user should come to expect that typing "@bot Help" in an interaction with any bot will return some information about how they can proceed.

"Settings"

If your bot requires any type of user configuration, you should allow the user to reconfigure that quickly at any time.

"Feedback"

All bots can be improved over time, and users can help you make good product choices. Users will get used to easily registering feedback with bots in Chat.

User authentication in rooms

If your bot requires authentication or configuration, you can opt to show a user a private card in a room. This provides a better user experience, allowing users to set up the bot in a room without disturbing the rest of the room members.

Error messages

Your bot should handle unexpected events gracefully and appropriately. Otherwise, trust in the bot will erode.

Problems with user input

The more nuanced with your error handling you are, the better. At the very least, you need a generic error to account for unanticipated messages from the user.

Generic errors

In most cases, your bot won't know what it doesn't know. You'll need a generic error to account for every user request that your bot isn't programmed to deal with.

This can be as simple as a reiteration of the help message, with an acknowledgment of the fact that your bot didn't understand.

Send feedback about...

Hangouts Chat API
Hangouts Chat API
Need help? Visit our support page.