Get people and spaces started with helpful onboarding

Onboard people and spaces to your Chat bot with a welcome message that details what your Chat bot does, and how people can best work with it. The onboarding message is the first message that many people in Google Chat receive from your bot, and you only get one first impression, so make it count!

Write effective onboarding messages

An effective onboarding message tells users what your bot does, how they can work with your bot, and how they can learn more about your bot or get help.

An effective onboarding message is structured like this:

  • Say hello. If you were messaging a person for the first time, you'd probably start with "hello"!
  • Describe what your Chat bot does in one to two sentences. Introduce your Chat bot by telling people what it can help them do. People might use your app elsewhere, such as on a mobile or web app, and this might be the first time they see it in Google Chat. Or, this might be the first time they see your app, so be sure to give a thorough description.
  • Tell people how to get started. For example, suggest one or two common commands. Now that people know what your bot does, tell them how to work with your bot. If your bot requires configuration or authorization, this is a good place to prompt people to complete the set up process.
  • Explain how to get help and how to give feedback. End the message by telling people how they can get help or offer feedback. This could be as simple as buttons labeled "Help" and "Feedback", but you might want to indicate how they can get help if they need it in the future, such as via a /help slash command.

Things to avoid

There are some things that onboarding messages should never do:

  • Don't mention everyone in a space. If your Chat bot mentions everyone in a space, it will annoy them, and they will perceive your bot as spam.
  • Don't write long onboarding messages. People do not read very long messages. If you find yourself writing a very long onboarding message, consider moving details into a help command.
  • Don't assume that people know what your app does. Introduce users to your Chat bot's functionality as though this is the first time they are working with your app.

Example onboarding message: Scheduler bot

The Scheduler bot's onboarding message prepares users for success. It's friendly, describes what Scheduler bot can do, and tells them how to learn more or get help.

Example onboarding message.

Send an onboarding message

To send an onboarding message, your bot responds to the ADDED_TO_SPACE event from Chat API, which your bot receives each time it is added to a Chat space.

The following JSON example shows the request body for an ADDED_TO_SPACE event:

JSON

{
  "type": "ADDED_TO_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",

  // "space" provides details about the Chat space the bot was added to.
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "type": "ROOM"
  },

  // "user" provides details about the user who added the bot to the space.
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Respond to the ADDED_TO_SPACE event with an effective onboarding message:

Node.js

/**
 * Sends an onboarding message when the Chat bot is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat bot. An onboarding message that
 * introduces the bot and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if(req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Scheduler at your service. I help you manage your calendar
      from Google Chat. Take a look at your schedule today by typing
      `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To
      learn what else I can do, type `/help`.'
    });
  }
};

Apps Script

/**
 * Sends an onboarding message when the Chat bot is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat bot. An onboarding message that
 * introduces the bot and helps people get started with it.
 */
function onAddToSpace(event) {

  return {
    'text': 'Hi, Scheduler at your service. I help you manage your calendar
    from Google Chat. Take a look at your schedule today by typing
    `/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn
    what else I can do, type `/help`.'
  }
}