Send private messages to Google Chat users

This page explains how to create and send private messages as a Google Chat app.

A private message is a Chat app message that's only visible to a specified Chat user. You can use private messages in spaces with multiple people so that they can interact privately with Chat apps. For example, your Chat app can privately send messages to do any of the following:

  • Respond to a slash command. For example, if a user invokes your Chat app's /about slash command in a space, your Chat app can reply with a private message that explains what your Chat app does and how to use it.
  • Notify or send information that's only relevant to one user. For example, notify a user that they've been assigned a task, or remind them to complete the task.
  • Send an error message. For example, if a user omits required argument text for a slash command, the Chat app can send a private message to explain the error and help the user format the command.

When a Chat app sends a private message, the message shows a label that notifies the user that the message is only visible to them:

Private message for the Cymbal Labs Chat app. The message says that the Chat app was created by Cymbal Labs and shares a link to documentation and a link to contact the support team.
Figure 1: When a Chat app sends a private message, the user sees a message with a label that says Only visible to you.

Prerequisites

Node.js

Note: The Node.js code samples in this guide are written to run as a Google Cloud Function.

Python

Note: The Python code samples in this guide are written to run as a Google Cloud Function, using Python 3.10.

Apps Script

Send a private message

To send a message privately as a Chat app, you specify the privateMessageViewer field in the message when you create it. You create private messages just like you create any message: by either responding to a user interaction, or asynchronously calling the Google Chat API's create() method on the Message resource. For steps to send text or card messages, see Send a message.

The following example shows the JSON for a private text message that says Hello private world!:

{
    "text": "Hello private world!",
    "privateMessageViewer": "USER"
}

In this example, USER represents the Chat user who can view the message, formatted as a User resource. If responding to a user interaction, you can specify the User object from the interaction event. For an example, see the following section Respond privately to a slash command.

Otherwise, to specify the viewer for a private message, you can use the name field of the User resource:

{
    "text": "Hello private world!",
    "privateMessageViewer": {
      "name": "users/USER_ID"
    }
}

In this example, you use the name field to specify the viewer's User resource name in Google Chat. Replace USER_ID with a unique ID for the user, such as 12345678987654321 or hao@cymbalgroup.com.

For more information about specifying users, see Identify and specify Google Chat users.

Respond privately to a slash command

The following code shows an example of a Chat app that responds to a slash command with a private message.

The Chat app processes a MESSAGE interaction event and replies to the /help slash command with a private text message that explains how to use it:

Node.js 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case '1':  // /help
        return res.json({
          privateMessageViewer: event.user,
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps Script 

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // Responds to /help
        return {
          "privateMessageViewer": event.user,
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python 

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == '1':  # /help
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'),
      'text': 'Try a slash command.',
  }

Limitations

To send a private message, the message can't contain or use the following:

  • Attachments.
  • Accessory actions.
  • Partially-private messages. For example, a Chat app can't send a message with text and a card where the text is visible to only one user but the card is visible to everyone in the space.
  • User authentication. Only Chat apps can send private messages, so your Chat app can't authenticate as a user to send a message privately.

Update or delete private messages

To update or delete Google Chat messages, you must call the Chat API. You can't change the viewer of the private message or make the message public. Therefore, when you update private messages, you must omit the privateMessageViewer field in the API call (the field is output only).

To update a private message, see Update a message. To delete a private message, see Delete a message.