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:
Prerequisites
Node.js
- A Google Cloud project with the Google Chat API enabled and configured. For steps, see Build a Google Chat app.
- To respond privately to a slash command, a slash command configured for the Chat app. To build one, see Respond to slash commands.
- To send a private message using the
messages.create()
method, you must use app authentication.
Note: The Node.js code samples in this guide are written to run as a Google Cloud Function.
Python
- A Google Cloud project with the Google Chat API enabled and configured. For steps, see Build a Google Chat app.
- To respond privately to a slash command, a slash command configured for the Chat app. To build one, see Respond to slash commands.
- To send a private message using the
messages.create()
method, you must use app authentication.
Note: The Python code samples in this guide are written to run as a Google Cloud Function, using Python 3.10.
Apps Script
- A Chat app. To build a Chat app, follow this quickstart.
- To respond privately to a slash command, a slash command configured for the Chat app. To build one, see Respond to slash commands.
- To send a private message using the
messages.create()
method, you must use app authentication.
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.
Related topics
- Send a message
- Identify and specify Google Chat users
- Respond to slash commands
- Update a message
- Delete a message