This page explains how Google Chat apps can send messages to reply to user interactions.
Note: In Google Chat, add-ons appear to users as Google Chat apps. You can also build your Chat app using Google Chat API interaction events . To learn more, see the Extend Google Chat overview .
-
Figure 1. A Chat app responds to a slash command with a text message and button. 
Figure 2. A Chat app opens a dialog where users can input information. 
Figure 5. A Chat app sends a message with text and an interactive card.
Prerequisites
Node.js
A Google Workspace add-on that extends Google Chat. To build one, complete the HTTP quickstart .
Apps Script
A Google Workspace add-on that extends Google Chat. To build one, complete the Apps Script quickstart .
Design the message
Chat apps can include any of the following in a message:
- Text that contains hyperlinks, @mentions, and emoji.
- One or more cards, which can appear in a message or open in a new window as a dialog.
- One or more accessory widgets, which are buttons that appear after any text or cards in a message.
To learn about designing messages, see the following Google Chat API documentation:
- Messaging overview
- Format messages
- Build cards for Google Chat apps
- Add text and images to cards
- Add interactive UI elements to cards
Reply with a message
Chat apps can respond with a message to any of the following triggers or interactions:
- Messagetriggers , such as when users @mention or direct message a Chat app.
- Added to spacetriggers , such as when users install the Chat app from the Google Workspace Marketplace or add it to a space.
- Button clicks from cards in messages or dialogs. For example, when users input information and click submit.
Otherwise, Chat apps can send messages proactively by calling the Google Chat API .
To reply with a message, return the action DataActions
with a CreateMessageAction
object:
{
"hostAppDataAction"
:
{
"chatDataAction"
:
{
"createMessageAction"
:
{
"message"
:
MESSAGE
}}}
Replace MESSAGE
with a Message
resource from the Chat API. To learn more about how actions work, see Chat actions
.
In the following example, a Chat app creates and sends
a text message whenever it's added to a space. To send a text message when a
user adds your Chat app
to a space, your Chat app responds to the Added to spacetrigger by returning the action DataActions
:
Node.js
/**
* Sends an onboarding message when the Chat app is added to a space.
*
* @param {Object} req The request object from Google Workspace add-on.
* @param {Object} res The response object from the Chat app. An onboarding message that
* introduces the app and helps people get started with it.
*/
exports
.
cymbalApp
=
function
cymbalApp
(
req
,
res
)
{
const
chatEvent
=
req
.
body
.
chat
;
// Send an onboarding message when added to a Chat space
if
(
chatEvent
.
addedToSpacePayload
)
{
res
.
json
({
hostAppDataAction
:
{
chatDataAction
:
{
createMessageAction
:
{
message
:
{
text
:
'Hi, Cymbal 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 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
onAddedToSpace
(
event
)
{
return
{
hostAppDataAction
:
{
chatDataAction
:
{
createMessageAction
:
{
message
:
{
text
:
'Hi, Cymbal 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`.'
}}}}};
}
The code sample returns the following text message:
For additional examples of how to respond with a message, see the following guides:
- Respond to quick commands
- Respond to slash commands
- Open interactive dialogs
- Collect information from Google Chat users
Update a message
Chat apps can also update messages that they send. For example, to update a message after a user has submitted a dialog or clicked a button an a message.
To update a Chat app message, return the action DataActions
with a UpdateMessageAction
, as shown in
the following example:
{
"hostAppDataAction"
:
{
"chatDataAction"
:
{
"updateMessageAction"
:
{
"message"
:
MESSAGE
}}}}
Replace MESSAGE
with a Message
resource from the Chat API.
To learn more about how actions work, see Chat actions .
Chat apps can also update a message from a user, to return a preview of a link that they sent. For details, see Preview links in Google Chat messages .
Reply to interactions or send proactive messages using the Google Chat API
Instead of returning an add-on action, Chat apps might need to use the Google Chat API respond to an interaction. For example, Chat apps must call the Google Chat API to do any of the following:
- Send messages on a schedule, or about changes to external resources. For example, notifications about a new issue or case.
- Reply more than 30 seconds after the interaction. For example, to respond with a message after completing a long-running task.
- Send a message outside of the space where the interaction took place.
- Send a message on behalf of a Chat user.
To send a message using the Chat API, you must set up authentication
and call the create()
method on the Message
resource. For steps, see Send a message using the Google Chat API
.
