Envía un mensaje con la API de Google Chat

En esta guía, se explica cómo usar el método create() en el recurso Message de la API de Google Chat para realizar cualquiera de las siguientes acciones:

  • Envía mensajes que contengan texto, tarjetas y widgets interactivos.
  • Envía mensajes de forma privada a un usuario específico de Chat.
  • Iniciar una conversación o responder un mensaje en ella
  • Asigna un nombre a un mensaje para que puedas especificarlo en otras solicitudes a la API de Chat.

El tamaño máximo del mensaje (incluido cualquier texto o tarjeta) es de 32,000 bytes. Para enviar un mensaje que supere este tamaño, tu app de Chat debe enviar varios mensajes.

Además de llamar a la API de Chat para crear mensajes, las apps de Chat pueden crear y enviar mensajes para responder a las interacciones de los usuarios, como publicar un mensaje de bienvenida después de que un usuario agrega la app de Chat a un espacio. Cuando responden a las interacciones, las apps de Chat pueden usar otros tipos de funciones de mensajería, como diálogos interactivos y vistas previas de vínculos. Para responder a un usuario, la app de Chat devuelve el mensaje de forma síncrona, sin llamar a la API de Chat. Para obtener información sobre cómo enviar mensajes para responder a interacciones, consulta Recibe y responde interacciones con tu app de Google Chat.

Cómo Chat muestra y atribuye los mensajes creados con la API de Chat

Puedes llamar al método create() con la autenticación de la app y la autenticación del usuario. Chat atribuye el remitente del mensaje de manera diferente según el tipo de autenticación que uses.

Cuando te autenticas como la app de Chat, esta envía el mensaje.

Llamar al método create() con la autenticación de la app
Figura 1: Con la autenticación de la app, la app de Chat envía el mensaje. Para indicar que el remitente no es una persona, Chat muestra App junto a su nombre.

Cuando te autenticas como usuario, la app de Chat envía el mensaje en nombre del usuario. Chat también atribuye la app de Chat al mensaje mostrando su nombre.

Llama al método create() con la autenticación del usuario.
Figura 2: Con la autenticación de usuario, el usuario envía el mensaje y Chat muestra el nombre de la app de Chat junto al nombre del usuario.

El tipo de autenticación también determina qué funciones y, además, interfaces de mensajería puedes incluir en el mensaje. Con la autenticación de apps, las apps de Chat pueden enviar mensajes que contengan texto enriquecido, interfaces basadas en tarjetas y widgets interactivos. Con la autenticación de usuarios, puedes enviar mensajes de texto o crear mensajes con tarjetas, como se documenta en Crea y actualiza tarjetas interactivas.

Para obtener más información sobre las funciones de mensajería disponibles para la API de Chat, consulta la descripción general de los mensajes de Google Chat.

En esta guía, se explica cómo usar cualquiera de los tipos de autenticación para enviar un mensaje con la API de Chat.

Requisitos previos

Node.js

Python

Java

Apps Script

Envía un mensaje como la app de Chat

En esta sección, se explica cómo enviar mensajes que contengan texto, tarjetas y widgets de accesorios interactivos con la autenticación de apps.

Mensaje enviado con autenticación de la app
Figura 4: Una app de Chat envía un mensaje con texto, una tarjeta y un botón de accesorio.

Para llamar al método CreateMessage() con la autenticación de la app, debes especificar los siguientes campos en la solicitud:

  • El permiso de autorización de chat.bot.
  • Es el recurso Space en el que deseas publicar el mensaje. La app de Chat debe ser miembro del espacio.
  • Es el recurso Message que se creará. Para definir el contenido del mensaje, puedes incluir texto enriquecido (text), una o más interfaces de tarjeta (cardsV2) o ambos.

De manera opcional, puedes incluir lo siguiente:

En el siguiente código, se muestra un ejemplo de cómo una app de Chat puede enviar un mensaje publicado como la app de Chat que contiene texto, una tarjeta y un botón en el que se puede hacer clic en la parte inferior del mensaje:

Node.js

chat/client-libraries/cloud/create-message-app-cred.js
import {createClientWithAppCredentials} from './authentication-utils.js';

// This sample shows how to create message with app credential
async function main() {
  // Create a client
  const chatClient = createClientWithAppCredentials();

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text:
        '👋🌎 Hello world! I created this message by calling ' +
        "the Chat API's `messages.create()` method.",
      cardsV2: [
        {
          card: {
            header: {
              title: 'About this message',
              imageUrl:
                'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg',
            },
            sections: [
              {
                header: 'Contents',
                widgets: [
                  {
                    textParagraph: {
                      text:
                        '🔡 <b>Text</b> which can include ' +
                        'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.',
                    },
                  },
                  {
                    textParagraph: {
                      text:
                        '🖼️ A <b>card</b> to display visual elements' +
                        'and request information such as text 🔤, ' +
                        'dates and times 📅, and selections ☑️.',
                    },
                  },
                  {
                    textParagraph: {
                      text:
                        '👉🔘 An <b>accessory widget</b> which adds ' +
                        'a button to the bottom of a message.',
                    },
                  },
                ],
              },
              {
                header: "What's next",
                collapsible: true,
                widgets: [
                  {
                    textParagraph: {
                      text: "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.",
                    },
                  },
                  {
                    textParagraph: {
                      text:
                        "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                        "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                        'the message.',
                    },
                  },
                ],
              },
            ],
          },
        },
      ],
      accessoryWidgets: [
        {
          buttonList: {
            buttons: [
              {
                text: 'View documentation',
                icon: {materialIcon: {name: 'link'}},
                onClick: {
                  openLink: {
                    url: 'https://developers.google.com/workspace/chat/create-messages',
                  },
                },
              },
            ],
          },
        },
      ],
    },
  };

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

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

await main();

Python

chat/client-libraries/cloud/create_message_app_cred.py
from authentication_utils import create_client_with_app_credentials
from google.apps import chat_v1 as google_chat

# This sample shows how to create message with app credential
def create_message_with_app_cred():
    # Create a client
    client = create_client_with_app_credentials()

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world! I created this message by calling ' +
                    'the Chat API\'s `messages.create()` method.',
            "cards_v2" : [{ "card": {
                "header": {
                    "title": 'About this message',
                    "image_url": 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg'
                },
                "sections": [{
                    "header": "Contents",
                    "widgets": [{ "text_paragraph": {
                            "text": '🔡 <b>Text</b> which can include ' +
                                    'hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.'
                        }}, { "text_paragraph": {
                            "text": '🖼️ A <b>card</b> to display visual elements' +
                                    'and request information such as text 🔤, ' +
                                    'dates and times 📅, and selections ☑️.'
                        }}, { "text_paragraph": {
                            "text": '👉🔘 An <b>accessory widget</b> which adds ' +
                                    'a button to the bottom of a message.'
                        }}
                    ]}, {
                        "header": "What's next",
                        "collapsible": True,
                        "widgets": [{ "text_paragraph": {
                                "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>."
                            }}, { "text_paragraph": {
                                "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                                        "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                                        "the message."
                            }
                        }]
                    }
                ]
            }}],
            "accessory_widgets": [{ "button_list": { "buttons": [{
                "text": 'View documentation',
                "icon": { "material_icon": { "name": 'link' }},
                "on_click": { "open_link": {
                    "url": 'https://developers.google.com/workspace/chat/create-messages'
                }}
            }]}}]
        }
    )

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

    # Handle the response
    print(response)

create_message_with_app_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageAppCred.java
import com.google.apps.card.v1.Button;
import com.google.apps.card.v1.ButtonList;
import com.google.apps.card.v1.Card;
import com.google.apps.card.v1.Icon;
import com.google.apps.card.v1.MaterialIcon;
import com.google.apps.card.v1.OnClick;
import com.google.apps.card.v1.OpenLink;
import com.google.apps.card.v1.TextParagraph;
import com.google.apps.card.v1.Widget;
import com.google.apps.card.v1.Card.CardHeader;
import com.google.apps.card.v1.Card.Section;
import com.google.chat.v1.AccessoryWidget;
import com.google.chat.v1.CardWithId;
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with app credential.
public class CreateMessageAppCred {

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithAppCredentials()) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world! I created this message by calling " +
                    "the Chat API\'s `messages.create()` method.")
          .addCardsV2(CardWithId.newBuilder().setCard(Card.newBuilder()
            .setHeader(CardHeader.newBuilder()
              .setTitle("About this message")
              .setImageUrl("https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg"))
            .addSections(Section.newBuilder()
              .setHeader("Contents")
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔡 <b>Text</b> which can include " +
                "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🖼️ A <b>card</b> to display visual elements " +
                "and request information such as text 🔤, " +
                "dates and times 📅, and selections ☑️.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "👉🔘 An <b>accessory widget</b> which adds " +
                "a button to the bottom of a message."))))
            .addSections(Section.newBuilder()
              .setHeader("What's next")
              .setCollapsible(true)
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.")))
              .addWidgets(Widget.newBuilder().setTextParagraph(TextParagraph.newBuilder().setText(
                "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                "the message."))))))
          .addAccessoryWidgets(AccessoryWidget.newBuilder()
            .setButtonList(ButtonList.newBuilder()
              .addButtons(Button.newBuilder()
                .setText("View documentation")
                .setIcon(Icon.newBuilder()
                  .setMaterialIcon(MaterialIcon.newBuilder().setName("link")))
                .setOnClick(OnClick.newBuilder()
                  .setOpenLink(OpenLink.newBuilder()
                    .setUrl("https://developers.google.com/workspace/chat/create-messages")))))));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with app credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.bot'
 * used by service accounts.
 */
function createMessageAppCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  const message = {
    text:
      "👋🌎 Hello world! I created this message by calling " +
      "the Chat API's `messages.create()` method.",
    cardsV2: [
      {
        card: {
          header: {
            title: "About this message",
            imageUrl:
              "https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg",
          },
          sections: [
            {
              header: "Contents",
              widgets: [
                {
                  textParagraph: {
                    text:
                      "🔡 <b>Text</b> which can include " +
                      "hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️.",
                  },
                },
                {
                  textParagraph: {
                    text:
                      "🖼️ A <b>card</b> to display visual elements" +
                      "and request information such as text 🔤, " +
                      "dates and times 📅, and selections ☑️.",
                  },
                },
                {
                  textParagraph: {
                    text:
                      "👉🔘 An <b>accessory widget</b> which adds " +
                      "a button to the bottom of a message.",
                  },
                },
              ],
            },
            {
              header: "What's next",
              collapsible: true,
              widgets: [
                {
                  textParagraph: {
                    text: "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>.",
                  },
                },
                {
                  textParagraph: {
                    text:
                      "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> " +
                      "or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> " +
                      "the message.",
                  },
                },
              ],
            },
          ],
        },
      },
    ],
    accessoryWidgets: [
      {
        buttonList: {
          buttons: [
            {
              text: "View documentation",
              icon: { materialIcon: { name: "link" } },
              onClick: {
                openLink: {
                  url: "https://developers.google.com/workspace/chat/create-messages",
                },
              },
            },
          ],
        },
      },
    ],
  };
  const parameters = {};

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

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

Para ejecutar este ejemplo, reemplaza SPACE_NAME por el ID del campo name del espacio. Puedes obtener el ID llamando al método ListSpaces() o desde la URL del espacio.

Agrega widgets interactivos en la parte inferior de un mensaje

En la primera muestra de código de esta guía, el mensaje de la app de Chat muestra un botón en el que se puede hacer clic en la parte inferior del mensaje, conocido como widget accesorio. Los widgets de accesorios aparecen después de cualquier texto o tarjeta en un mensaje. Puedes usar estos widgets para pedirles a los usuarios que interactúen con tu mensaje de muchas maneras, incluidas las siguientes:

  • Calificar la precisión o la satisfacción de un mensaje
  • Denuncia un problema con el mensaje o la app de Chat.
  • Abrir un vínculo al contenido relacionado, como la documentación
  • Descartar o posponer mensajes similares de la app de Chat durante un período específico

Para agregar widgets de accesorios, incluye el campo accessoryWidgets[] en el cuerpo de la solicitud y especifica uno o más widgets que quieras incluir.

En la siguiente imagen, se muestra una app de Chat que agrega un mensaje de texto con widgets de accesorios para que los usuarios puedan calificar su experiencia con la app de Chat.

Widget de accesorio.
Figura 5: Un mensaje de la app de Chat con widgets de texto y accesorios.

A continuación, se muestra el cuerpo de la solicitud que crea un mensaje de texto con dos botones de accesorio. Cuando un usuario hace clic en un botón, la función correspondiente (como doUpvote) procesa la interacción:

{
  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"
    }}
  }]}}]
}

Cómo enviar un mensaje de forma privada

Las apps de Chat pueden enviar mensajes de forma privada para que solo sean visibles para un usuario específico del espacio. Cuando una app de Chat envía un mensaje privado, este muestra una etiqueta que notifica al usuario que solo él puede verlo.

Para enviar un mensaje de forma privada con la API de Chat, especifica el campo privateMessageViewer en el cuerpo de la solicitud. Para especificar el usuario, establece el valor en el recurso User que representa al usuario de Chat. También puedes usar el campo name del recurso User, como se muestra en el siguiente ejemplo:

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

Para usar este ejemplo, reemplaza USER_ID por un ID único para el usuario, como 12345678987654321 o hao@cymbalgroup.com. Para obtener más información sobre cómo especificar usuarios, consulta Identifica y especifica usuarios de Google Chat.

Para enviar un mensaje de forma privada, debes omitir lo siguiente en tu solicitud:

Envía notificaciones forzadas o mensajes silenciosos

Cuando una app de Chat envía un mensaje, puede usar una de estas opciones para notificar a los usuarios:

  • Forzar una notificación: Chat siempre envía una notificación push a los destinatarios, independientemente de su configuración de notificaciones o su estado de No interrumpir (DND). En Chat, el mensaje activa un comportamiento de negrita y de salto en la lista de destinatarios o en la lista de la página principal, y muestra una insignia.
  • Enviar un mensaje silencioso: Chat suprime las notificaciones push para los destinatarios. En Chat, el mensaje no activa un comportamiento de negrita o de salto en la lista de destinatarios o en la lista de la página principal, y no muestra una insignia. Si el mensaje silencioso es el último de una conversación, su contenido no se muestra en el fragmento de la página principal.

Ya sean forzados o silenciosos, estos mensajes incluyen un indicador visual que notifica a los destinatarios sobre el comportamiento especial de la notificación.

Las notificaciones forzadas y los mensajes silenciosos solo están disponibles para las apps de Chat que usan la autenticación de apps.

Las notificaciones forzadas y los mensajes silenciosos tienen las siguientes limitaciones:

  • Usuarios externos: Las notificaciones forzadas y los mensajes silenciosos no se aplican a los usuarios externos (invitados) de un espacio. Los usuarios externos reciben notificaciones según su propia configuración.
  • Menciones: Los mensajes silenciosos no admiten mencionar usuarios. Si incluyes una mención en un mensaje silencioso, se tratará como texto sin formato.
  • Conversaciones: No puedes iniciar una conversación ni responder a ella con un mensaje silencioso.
  • Tipo de espacio: Las notificaciones forzadas y los mensajes silenciosos no se admiten en los mensajes directos (MD) ni en los espacios que pertenecen a personas que no tienen una cuenta de Google Workspace.
  • Notificaciones por correo electrónico: Los mensajes silenciosos no activan notificaciones por correo electrónico. Los mensajes con notificación forzada solo activan las notificaciones por correo electrónico si también incluyen una mención para un usuario específico.

Para forzar una notificación o enviar un mensaje silencioso, incluye el campo createMessageNotificationOptions en tu solicitud y establece notificationType en uno de los siguientes valores:

Valor Comportamiento
NOTIFICATION_TYPE_FORCE_NOTIFY Fuerza una notificación.
NOTIFICATION_TYPE_SILENT Envía el mensaje de forma silenciosa.

En el siguiente ejemplo, se muestra el cuerpo JSON de una solicitud para enviar un mensaje con una notificación forzada:

{
  "text": "Critical update: the server is down!",
  "createMessageNotificationOptions": {
    "notificationType": "NOTIFICATION_TYPE_FORCE_NOTIFY"
  }
}

Envía un mensaje de texto en nombre de un usuario

En esta sección, se explica cómo enviar mensajes en nombre de un usuario con la autenticación de usuarios. Con la autenticación de usuarios, puedes enviar mensajes de texto o crear mensajes con tarjetas en nombre de un usuario. Para obtener detalles sobre cómo enviar tarjetas en nombre de un usuario, consulta Crea y actualiza tarjetas interactivas.

Mensaje enviado con autenticación del usuario
Figura 3. Una app de Chat envía un mensaje de texto en nombre de un usuario.

Para llamar al método CreateMessage() con la autenticación de usuario, debes especificar los siguientes campos en la solicitud:

  • Un permiso de autorización que admita la autenticación de usuarios para este método. En el siguiente ejemplo, se usa el permiso chat.messages.create.
  • Es el recurso Space en el que deseas publicar el mensaje. El usuario autenticado debe ser miembro del espacio.
  • Es el recurso Message que se creará. Para definir el contenido del mensaje, debes incluir el campo text.

De manera opcional, puedes incluir lo siguiente:

En el siguiente código, se muestra un ejemplo de cómo una app de Chat puede enviar un mensaje de texto en un espacio determinado en nombre de un usuario autenticado:

Node.js

chat/client-libraries/cloud/create-message-user-cred.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 message with user credential
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    message: {
      text:
        '👋🌎 Hello world!' +
        'Text messages can contain things like:\n\n' +
        '* Hyperlinks 🔗\n' +
        '* Emojis 😄🎉\n' +
        '* Mentions of other Chat users `@` \n\n' +
        'For details, see the ' +
        '<https://developers.google.com/workspace/chat/format-messages' +
        '|Chat API developer documentation>.',
    },
  };

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

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

await main();

Python

chat/client-libraries/cloud/create_message_user_cred.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

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

def create_message_with_user_cred():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here.
        parent = "spaces/SPACE_NAME",
        message = {
            "text": '👋🌎 Hello world!' +
                    'Text messages can contain things like:\n\n' +
                    '* Hyperlinks 🔗\n' +
                    '* Emojis 😄🎉\n' +
                    '* Mentions of other Chat users `@` \n\n' +
                    'For details, see the ' +
                    '<https://developers.google.com/workspace/chat/format-messages' +
                    '|Chat API developer documentation>.'
        }
    )

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

    # Handle the response
    print(response)

create_message_with_user_cred()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCred.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with user credential.
public class CreateMessageUserCred {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText( "👋🌎 Hello world!" +
                    "Text messages can contain things like:\n\n" +
                    "* Hyperlinks 🔗\n" +
                    "* Emojis 😄🎉\n" +
                    "* Mentions of other Chat users `@` \n\n" +
                    "For details, see the " +
                    "<https://developers.google.com/workspace/chat/format-messages" +
                    "|Chat API developer documentation>."));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCred() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  const message = {
    text:
      "👋🌎 Hello world!" +
      "Text messages can contain things like:\n\n" +
      "* Hyperlinks 🔗\n" +
      "* Emojis 😄🎉\n" +
      "* Mentions of other Chat users `@` \n\n" +
      "For details, see the " +
      "<https://developers.google.com/workspace/chat/format-messages" +
      "|Chat API developer documentation>.",
  };

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

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

Para ejecutar este ejemplo, reemplaza SPACE_NAME por el ID del campo name del espacio. Puedes obtener el ID llamando al método ListSpaces() o desde la URL del espacio.

Cómo iniciar una conversación o responder en ella

En los espacios que usan conversaciones, puedes especificar si un mensaje nuevo inicia una conversación o responde a una existente.

De forma predeterminada, los mensajes que creas con la API de Chat inician una conversación nueva. Para ayudarte a identificar la conversación y responderla más tarde, puedes especificar una clave de conversación en tu solicitud:

  • En el cuerpo de la solicitud, especifica el campo thread.threadKey.
  • Especifica el parámetro de consulta messageReplyOption para determinar qué sucede si la clave ya existe.

Para crear un mensaje que responda a un hilo existente, sigue estos pasos:

  • En el cuerpo de la solicitud, incluye el campo thread. Si se establece, puedes especificar el threadKey que creaste. De lo contrario, debes usar el name del hilo.
  • Especifica el parámetro de consulta messageReplyOption.

En el siguiente código, se muestra un ejemplo de cómo una app de Chat puede enviar un mensaje de texto que inicie o responda una conversación determinada identificada por la clave de un espacio determinado en nombre de un usuario autenticado:

Node.js

chat/client-libraries/cloud/create-message-user-cred-thread-key.js
import {protos} from '@google-apps/chat';
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 message with user credential with thread key
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Creates the message as a reply to the thread specified by thread_key
    // If it fails, the message starts a new thread instead
    messageReplyOption:
      protos.google.chat.v1.CreateMessageRequest.MessageReplyOption
        .REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
    message: {
      text: 'Hello with user credential!',
      thread: {
        // Thread key specifies a thread and is unique to the chat app
        // that sets it
        threadKey: 'THREAD_KEY',
      },
    },
  };

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

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

await main();

Python

chat/client-libraries/cloud/create_message_user_cred_thread_key.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

import google.apps.chat_v1.CreateMessageRequest.MessageReplyOption

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

# This sample shows how to create message with user credential with thread key
def create_message_with_user_cred_thread_key():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Creates the message as a reply to the thread specified by thread_key.
        # If it fails, the message starts a new thread instead.
        message_reply_option = MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD,
        message = {
            "text": "Hello with user credential!",
            "thread": {
                # Thread key specifies a thread and is unique to the chat app
                # that sets it.
                "thread_key": "THREAD_KEY"
            }
        }
    )

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

    # Handle the response
    print(response)

create_message_with_user_cred_thread_key()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredThreadKey.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.CreateMessageRequest.MessageReplyOption;
import com.google.chat.v1.Message;
import com.google.chat.v1.Thread;

// This sample shows how to create message with a thread key with user
// credential.
public class CreateMessageUserCredThreadKey {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        // Creates the message as a reply to the thread specified by thread_key.
        // If it fails, the message starts a new thread instead.
        .setMessageReplyOption(
          MessageReplyOption.REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD)
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!")
          // Thread key specifies a thread and is unique to the chat app
          // that sets it.
          .setThread(Thread.newBuilder().setThreadKey("THREAD_KEY")));
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with thread key
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredThreadKey() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  // Creates the message as a reply to the thread specified by thread_key
  // If it fails, the message starts a new thread instead
  const messageReplyOption = "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD";
  const message = {
    text: "Hello with user credential!",
    thread: {
      // Thread key specifies a thread and is unique to the chat app
      // that sets it
      threadKey: "THREAD_KEY",
    },
  };

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

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

Para ejecutar este ejemplo, reemplaza lo siguiente:

  • THREAD_KEY: Es una clave de conversación existente en el espacio o, para crear una conversación nueva, un nombre único para la conversación.
  • SPACE_NAME: Es el ID del campo name del espacio. Puedes obtener el ID llamando al método ListSpaces() o desde la URL del espacio.

Asigna un nombre al mensaje

Para recuperar o especificar un mensaje en futuras llamadas a la API, puedes asignarle un nombre configurando el campo messageId en tu solicitud. Asignar un nombre a tu mensaje te permite especificarlo sin necesidad de almacenar el ID asignado por el sistema desde el nombre del recurso del mensaje (representado en el campo name).

Por ejemplo, para recuperar un mensaje con el método get(), usa el nombre del recurso para especificar qué mensaje recuperar. El nombre del recurso tiene el formato spaces/{space}/messages/{message}, en el que {message} representa el ID asignado por el sistema o el nombre personalizado que estableciste cuando creaste el mensaje.

Para asignar un nombre a un mensaje, especifica un ID personalizado en el campo messageId cuando crees el mensaje. El campo messageId establece el valor para el campo clientAssignedMessageId del recurso Message.

Solo puedes asignarle un nombre a un mensaje cuando lo creas. No puedes asignar un nombre ni modificar un ID personalizado para los mensajes existentes. El ID personalizado debe cumplir con los siguientes requisitos:

  • Comienza con client-. Por ejemplo, client-custom-name es un ID personalizado válido, pero custom-name no lo es.
  • Contiene hasta 63 caracteres y solo letras minúsculas, números y guiones.
  • Es único dentro de un espacio. Una app de Chat no puede usar el mismo ID personalizado para diferentes mensajes.

En el siguiente código, se muestra un ejemplo de cómo una app de Chat puede enviar un mensaje de texto con un ID a un espacio determinado en nombre de un usuario autenticado:

Node.js

chat/client-libraries/cloud/create-message-user-cred-message-id.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 with user credentials and a custom
// message id
async function main() {
  // Create a client
  const chatClient = await createClientWithUserCredentials(
    USER_AUTH_OAUTH_SCOPES,
  );

  // Initialize request argument(s)
  const request = {
    // Replace SPACE_NAME here.
    parent: 'spaces/SPACE_NAME',
    // Message id lets chat apps get, update or delete a message without needing
    // to store the system assigned ID in the message's resource name
    messageId: 'client-MESSAGE-ID',
    message: {text: 'Hello with user credential!'},
  };

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

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

await main();

Python

chat/client-libraries/cloud/create_message_user_cred_message_id.py
from authentication_utils import create_client_with_user_credentials
from google.apps import chat_v1 as google_chat

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

# This sample shows how to create message with user credential with message id
def create_message_with_user_cred_message_id():
    # Create a client
    client = create_client_with_user_credentials(SCOPES)

    # Initialize request argument(s)
    request = google_chat.CreateMessageRequest(
        # Replace SPACE_NAME here
        parent = "spaces/SPACE_NAME",
        # Message id let chat apps get, update or delete a message without needing
        # to store the system assigned ID in the message's resource name.
        message_id = "client-MESSAGE-ID",
        message = {
            "text": "Hello with user credential!"
        }
    )

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

    # Handle the response
    print(response)

create_message_with_user_cred_message_id()

Java

chat/client-libraries/cloud/src/main/java/com/google/workspace/api/chat/samples/CreateMessageUserCredMessageId.java
import com.google.chat.v1.ChatServiceClient;
import com.google.chat.v1.CreateMessageRequest;
import com.google.chat.v1.Message;

// This sample shows how to create message with message id specified with user
// credential.
public class CreateMessageUserCredMessageId {

  private static final String SCOPE =
    "https://www.googleapis.com/auth/chat.messages.create";

  public static void main(String[] args) throws Exception {
    try (ChatServiceClient chatServiceClient =
        AuthenticationUtils.createClientWithUserCredentials(
          ImmutableList.of(SCOPE))) {
      CreateMessageRequest.Builder request = CreateMessageRequest.newBuilder()
        // Replace SPACE_NAME here.
        .setParent("spaces/SPACE_NAME")
        .setMessage(Message.newBuilder()
          .setText("Hello with user credentials!"))
        // Message ID lets chat apps get, update or delete a message without
        // needing to store the system assigned ID in the message's resource
        // name.
        .setMessageId("client-MESSAGE-ID");
      Message response = chatServiceClient.createMessage(request.build());

      System.out.println(JsonFormat.printer().print(response));
    }
  }
}

Apps Script

chat/advanced-service/Main.gs
/**
 * This sample shows how to create message with user credential with message id
 *
 * It relies on the OAuth2 scope 'https://www.googleapis.com/auth/chat.messages.create'
 * referenced in the manifest file (appsscript.json).
 */
function createMessageUserCredMessageId() {
  // Initialize request argument(s)
  // TODO(developer): Replace SPACE_NAME here.
  const parent = "spaces/SPACE_NAME";
  // Message id lets chat apps get, update or delete a message without needing
  // to store the system assigned ID in the message's resource name
  const messageId = "client-MESSAGE-ID";
  const message = { text: "Hello with user credential!" };

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

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

Para ejecutar este ejemplo, reemplaza lo siguiente:

  • SPACE_NAME: Es el ID del campo name del espacio. Puedes obtener el ID llamando al método ListSpaces() o desde la URL del espacio.
  • MESSAGE-ID: Es un nombre para el mensaje que comienza con custom-. Debe ser único entre todos los demás nombres de mensajes que cree la app de Chat en el espacio especificado.

Citar un mensaje

Puedes citar otro mensaje llamando a CreateMessage() (rpc, rest) y configurando quotedMessageMetadata (rpc, rest) en la solicitud.

Puedes citar mensajes dentro de una conversación o en el chat principal, pero no puedes citar un mensaje de otra conversación.

En el siguiente código, se muestra cómo crear un mensaje que cita otro mensaje:

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);
}

Para ejecutar este ejemplo, reemplaza lo siguiente:

  • SPACE_NAME: Es el ID del campo name del espacio. Puedes obtener el ID llamando al método ListSpaces() (rpc, rest) o desde la URL del espacio.
  • QUOTED_MESSAGE_NAME: Es el recurso de mensaje name (rpc, rest) del mensaje que se citará en el formato spaces/{space}/messages/{message}.
  • QUOTED_MESSAGE_LAST_UPDATE_TIME: Es la hora de la última actualización del mensaje que quieres citar. Si el mensaje nunca se editó, corresponde a createTime (rpc, rest). Si se editó, corresponde a lastUpdateTime (rpc, rest).

Solucionar problemas

Cuando una app de Google Chat o una tarjeta devuelven un error, la interfaz de Chat muestra el mensaje "Se produjo un error". o "No se puede procesar tu solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app de Chat o la tarjeta producen un resultado inesperado; por ejemplo, es posible que no aparezca un mensaje de tarjeta.

Aunque es posible que no aparezca un mensaje de error en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores cuando se activa el registro de errores para las apps de Chat. Para obtener ayuda con la visualización, la depuración y la corrección de errores, consulta Cómo solucionar problemas y corregir errores de Google Chat.