Send a message using the Google Chat API (original) (raw)

Skip to main content

Send a message using the Google Chat API

This guide explains how to use thecreate()method on the Message resource of the Google Chat API to do any of the following:

The maximum message size (including any text or cards) is 32,000 bytes. To send a message that exceeds this size, your Chat app must send multiple messages instead.

In addition to calling the Chat API to create messages, Chat apps can create and send messages to reply to user interactions, such as posting a welcome message after a user adds the Chat app to a space. When responding to interactions, Chat apps can use other types of messaging features, including interactive dialogs and link preview interfaces. To reply to a user, the Chat app returns the message synchronously, without calling the Chat API. To learn about sending messages to respond to interactions, seeReceive and respond to interactions with your Google Chat app.

How Chat displays and attributes messages created with the Chat API

You can call the create() method usingapp authenticationand user authentication. Chat attributes the message sender differently depending on the type of authentication that you use.

When you authenticate as the Chat app, the Chat app sends the message.

Calling the create() method with app authentication.

Figure 1: With app authentication, the Chat app sends the message. To note that the sender isn't a person, Chat displays App next to its name.

When you authenticate as a user, the Chat app sends the message on behalf of the user. Chat also attributes the Chat app to the message by displaying its name.

Calling the create() method with user authentication.

Figure 2: With user authentication, the user sends the message, and Chat displays the Chat app name next to the user's name.

The authentication type also determines which messaging features and interfaces that you can include in the message. With app authentication, Chat apps can send messages that contain rich text, card-based interfaces, and interactive widgets. With user authentication, you can send text messages. InDeveloper Preview, you can also send cards, as documented inCreate and update cards.

To learn more about messaging features available for the Chat API, see theGoogle Chat messages overview.

This guide explains how to use either authentication type to send a message with the Chat API.

Prerequisites

Node.js

Python

Java

Apps Script

This section explains how to send messages that contain text, cards, and interactive accessory widgets usingapp authentication.

Message sent with app authentication

Figure 4. A Chat app sends a message with text, a card, and an accessory button.

To call the CreateMessage()method using app authentication, you must specify the following fields in the request:

Optionally, you can include the following:

The following code shows an example of how a Chat app can send a message posted as the Chat app that contains text, a card, and a clickable button at the bottom of the message:

Node.js

Python

Java

Apps Script

To run this sample, replace SPACE_NAME with the ID from the space'snamefield. You can obtain the ID by calling theListSpaces()method or from the space's URL.

Add interactive widgets at the bottom of a message

In the first code sample of this guide, the Chat app message displays a clickable button at the bottom of the message, known as an accessory widget. Accessory widgets appear after any text or cards in a message. You can use these widgets to prompt users to interact with your message in many ways, including the following:

To add accessory widgets, include theaccessoryWidgets[]field in the body of your request and specify one or more widgets that you want to include.

The following image shows a Chat app that appends a text message with accessory widgets so that users can rate their experience with the Chat app.

Accessory widget.

Figure 5: A Chat app message with text and accessory widgets.

The following shows the body of the request that creates a text message with two accessory buttons. When a user clicks a button, the corresponding function (such as doUpvote) processes the interaction:

{
  text: "Rate your experience with this Chat app.",
  accessoryWidgets: [{ buttonList: { buttons: [{
    icon: { material_icon: {
      name: "thumb_up"
    }},
    color: { red: 0, blue: 255, green: 0 },
    onClick: { action: {
      function: "doUpvote"
    }}
  }, {
    icon: { material_icon: {
      name: "thumb_down"
    }},
    color: { red: 0, blue: 255, green: 0 },
    onClick: { action: {
      function: "doDownvote"
    }}
  }]}}]
}

Send a message privately

Chat apps can send messages privately so that the message is only visible to a specific user in the space. 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.

To send a message privately using the Chat API, specify theprivateMessageViewerfield in the body of your request. To specify the user, you set the value to theUserresource that represents the Chat user. You can also use thenamefield of the User resource, as shown in the following example:

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

To use this sample, replace USER_IDwith a unique ID for the user, such as 12345678987654321 orhao@cymbalgroup.com. For more information about specifying users, seeIdentify and specify Google Chat users.

To send a message privately, you must omit the following in your request:

Send a text message on behalf of a user

This section explains how to send messages on behalf of a user usinguser authentication. With user authentication, the content of the message can only contain text and must omit messaging features that are only available to Chat apps, including card interfaces and interactive widgets. In Developer Preview, you can create messages with cards on behalf of a user. For details, seeCreate and update cards.

Message sent with user authentication

Figure 3. A Chat app sends a text message on behalf of a user.

To call the CreateMessage() method using user authentication, you must specify the following fields in the request:

Optionally, you can include the following:

The following code shows an example of how a Chat app can send a text message in a given space on behalf of an authenticated user:

Node.js

Python

Java

Apps Script

To run this sample, replace SPACE_NAME with the ID from the space'snamefield. You can obtain the ID by calling theListSpaces()method or from the space's URL.

Start or reply in a thread

For spaces that use threads, you can specify whether a new message starts a thread, or replies to an existing thread.

By default, messages that you create using the Chat API start a new thread. To help you identify the thread and reply to it later, you can specify a thread key in your request:

To create a message that replies to an existing thread:

The following code shows an example of how a Chat app can send a text message that starts or replies to a given thread identified by key of a given space on behalf of an authenticated user:

Node.js

Python

Java

Apps Script

To run this sample, replace the following:

Name a message

To retrieve or specify a message in future API calls, you can name a message by setting the messageId field in your request. Naming your message lets you specify the message without needing to store the system-assigned ID from the resource name of the message (represented in thenamefield).

For example, to retrieve a message using the get() method, you use the resource name to specify which message to retrieve. The resource name is formatted as spaces/{space}/messages/{message}, where {message} represents the system-assigned ID or the custom name that you set when you created the message.

To name a message, specify a custom ID in themessageIdfield when you create the message. The messageId field sets the value for theclientAssignedMessageIdfield of the Message resource.

You can only name a message when you create the message. You can't name or modify a custom ID for existing messages. The custom ID must meet the following requirements:

The following code shows an example of how a Chat app can send a text message with an ID to a given space on behalf of an authenticated user:

Node.js

Python

Java

Apps Script

To run this sample, replace the following:

Quote a message

You can quote another message by callingCreateMessage()(rpc,rest) and setting quotedMessageMetadata(rpc,rest) in the request.

You can quote messages within a thread or in the main chat, but you can't quote a message from a different thread.

The following code shows how to create a message that quotes another message:

Node.js

import {createClientWithUserCredentials} from './authentication-utils.js';

const USER_AUTH_OAUTH_SCOPES = ['https://www.googleapis.com/auth/chat.messages.create'];

// This sample shows how to create a message that quotes another message.
async function main() {

  // Create a client
  const chatClient = await createClientWithUserCredentials(USER_AUTH_OAUTH_SCOPES);

  // Initialize request argument(s)
  const request = {

    // TODO(developer): Replace SPACE_NAME .
    parent: 'spaces/SPACE_NAME',

    message: {
      text: 'I am responding to a quoted message!',

      // quotedMessageMetadata lets chat apps respond to a message by quoting it.
      quotedMessageMetadata: {

        // TODO(developer): Replace QUOTED_MESSAGE_NAME
        // and QUOTED_MESSAGE_LAST_UPDATE_TIME.
        name: 'QUOTED_MESSAGE_NAME',
        lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME'
      }
    }
  };

  // Make the request
  const response = await chatClient.createMessage(request);

  // Handle the response
  console.log(response);
}

main().catch(console.error);

Python

from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat
from google.protobuf.timestamp_pb2 import Timestamp

SCOPES = ['https://www.googleapis.com/auth/chat.messages.create']

# This sample shows how to create a message that quotes another message.
def create_message_quote_message():
    '''Creates a message that quotes another message.'''

    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Create a timestamp from the RFC-3339 string.
    # TODO(developer): Replace QUOTED_MESSAGE_LAST_UPDATE_TIME.
    last_update_time = Timestamp()
    last_update_time.FromJsonString('QUOTED_MESSAGE_LAST_UPDATE_TIME')

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(

        # TODO(developer): Replace SPACE_NAME.
        parent='spaces/SPACE_NAME',

        # Create the message.
        message = google_chat.Message(
            text='I am responding to a quoted message!',

            # quotedMessageMetadata lets chat apps respond to a message by quoting it.
            quoted_message_metadata=google_chat.QuotedMessageMetadata(

                name='QUOTED_MESSAGE_NAME',
                last_update_time=last_update_time
            )
        )
    )

    # Make the request
    response = client.create_message(request)

    # Handle the response
    print(response)

create_message_quote_message()

Java

import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;
import com.google.chat.v1.QuotedMessageMetadata;
import com.google.protobuf.util.Timestamps;
import com.google.workspace.api.chat.samples.utils.AuthenticationUtils;
import java.text.ParseException;

// This sample shows how to create a message that quotes another message.
public class CreateMessageQuoteMessage {
  public static void main(String[] args) throws Exception, ParseException {
    // Create a client.
    ChatServiceClient chatClient = AuthenticationUtils.createClientWithUserCredentials();

    // Initialize request argument(s).
    // TODO(developer): Replace SPACE_NAME, QUOTED_MESSAGE_NAME,
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME here.
    String parent = "spaces/SPACE_NAME";
    String quotedMessageName = "QUOTED_MESSAGE_NAME";
    String lastUpdateTime = "QUOTED_MESSAGE_LAST_UPDATE_TIME";

    QuotedMessageMetadata quotedMessageMetadata =
        QuotedMessageMetadata.newBuilder()
            .setName(quotedMessageName)
            .setLastUpdateTime(Timestamps.parse(lastUpdateTime))
            .build();

    Message message = Message.newBuilder()
        .setText("I am responding to a quoted message!")
        .setQuotedMessageMetadata(quotedMessageMetadata)
        .build();

    CreateMessageRequest request =
        CreateMessageRequest.newBuilder()
            .setParent(parent)
            .setMessage(message)
            .build();

    // Make the request.
    Message response = chatClient.createMessage(request);

    // Handle the response.
    System.out.println(response);
  }
}

Apps Script

/**
 * Creates a message that quotes another message.
 *
 * Relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageQuoteMessage() {

  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = 'spaces/SPACE_NAME';

  const message = {

    // The text content of the message.
    text: 'I am responding to a quoted message!',

    // quotedMessageMetadata lets chat apps respond to a message by quoting it.
    //
    // TODO(developer): Replace QUOTED_MESSAGE_NAME
    // and QUOTED_MESSAGE_LAST_UPDATE_TIME .
    quotedMessageMetadata: {
      name: 'QUOTED_MESSAGE_NAME',
      lastUpdateTime: 'QUOTED_MESSAGE_LAST_UPDATE_TIME',
    }
  };

  // Make the request
  const response = Chat.Spaces.Messages.create(message, parent);

  // Handle the response
  console.log(response);
}

To run this sample, replace the following:

Troubleshoot

When a Google Chat app orcard returns an error, the Chat interface surfaces a message saying "Something went wrong." or "Unable to process your request." Sometimes the Chat UI doesn't display any error message, but the Chat app or card produces an unexpected result; for example, a card message might not appear.

Although an error message might not display in the Chat UI, descriptive error messages and log data are available to help you fix errors when error logging for Chat apps is turned on. For help viewing, debugging, and fixing errors, seeTroubleshoot and fix Google Chat errors.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-04-01 UTC.