Get people and spaces started with helpful onboarding

Onboard people and spaces to your Chat app with a welcome message that details what your Chat app 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 app, and you only get one first impression, so make it count!

Write effective onboarding messages

An effective onboarding message tells users what your app does, how they can work with your app, and how they can learn more about your app 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 app does in one to two sentences. Introduce your Chat app 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 app does, tell them how to work with your app. If your app 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 app mentions everyone in a space, it will annoy them, and they will perceive your app 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 app's functionality as though this is the first time they are working with your app.

Example onboarding message: Scheduler app

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

Send an onboarding message

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

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

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

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

  // "user" provides details about the user who added the app 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:

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app 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`.'
    });
  }
};

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat api.
 * @return {Object} Response from the Chat app. An onboarding message that
 * introduces the app 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`.'
  }
}