Cómo enviar un mensaje

En esta guía, se explican las diferentes formas en que las apps de Google Chat pueden enviar mensajes:

  • Envía mensajes de texto y de tarjetas en tiempo real respondiendo a una interacción del usuario.
  • Envía mensajes de texto y de tarjetas de forma asíncrona llamando al método create en el recurso Message.
  • Inicia o responde una conversación de mensajes.
  • Envía un mensaje y asígnale un nombre.

El recurso Message representa un mensaje de texto o tarjeta en Google Chat. Puedes create, get, update o delete un mensaje en la API de Google Chat si llamas a los métodos correspondientes. Para obtener más información sobre los mensajes de texto y de tarjetas, consulta la descripción general de los mensajes de Google Chat.

En lugar de llamar al método create en el recurso Message de la API de Google Chat para enviar un mensaje de texto o una tarjeta de forma asíncrona, las apps de Google Chat también pueden crear mensajes para responder a las interacciones de los usuarios en tiempo real. Las respuestas a las interacciones del usuario no requieren autenticación y admiten otros tipos de mensajes, incluidos los diálogos interactivos y las vistas previas de vínculos. Para obtener más información, consulta Recibe y responde interacciones con tu app de Google Chat.

Requisitos previos

Node.js

Python

  • Una cuenta de Google Workspace con acceso a Google Chat
  • Python 3.6 o superior
  • La herramienta de administración de paquetes pip
  • Las bibliotecas cliente de Google más recientes para Python. Para instalarlos o actualizarlos, ejecuta el siguiente comando en tu interfaz de línea de comandos:

    pip3 install --upgrade google-api-python-client google-auth
    
  • Un proyecto de Google Cloud con la API de Google Chat habilitada y configurada Para conocer los pasos, consulta Compila una app de Google Chat.
  • Autorización configurada para que la app de Chat envíe mensajes asíncronos No se requiere una configuración de autorización para enviar mensajes en tiempo real.

Apps Script

Enviar mensajes de texto

Esta sección describe cómo enviar mensajes de texto de las siguientes dos maneras:

  • Envía un mensaje de texto en tiempo real respondiendo a la interacción del usuario.
  • Envía un mensaje de texto llamando a la API de Google Chat de forma asíncrona.

Envía un mensaje de texto en tiempo real

En este ejemplo, la app de Chat crea y envía un mensaje de texto cada vez que se agrega a un espacio. Si quieres obtener información sobre las prácticas recomendadas para incorporar usuarios, consulta Comienza a usar personas y espacios con integraciones útiles.

Para enviar un mensaje de texto cuando un usuario agrega tu app de Chat a un espacio, esta responde a un evento de interacción ADDED_TO_SPACE. Para responder a los eventos de interacción ADDED_TO_SPACE con un mensaje de texto, usa el siguiente código:

Node.js

/**
 * 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.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      '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 onAddToSpace(event) {

  return {
    '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`.'
  }
}

La muestra de código muestra el siguiente mensaje de texto:

Ejemplo de mensaje de integración.

Envía un mensaje de texto de forma asíncrona

En la siguiente sección, se explica cómo enviar un mensaje de texto de forma asíncrona con la autenticación de la app y del usuario.

Para enviar un mensaje de texto, pasa lo siguiente en la solicitud:

  • Con la autenticación de la app, especifica el alcance de la autorización chat.bot. Con la autenticación del usuario, especifica el alcance de la autorización chat.messages.create.
  • Llama al método create en el recurso Message.

Envía un mensaje de texto con la autenticación de la app

A continuación, te mostramos cómo enviar un mensaje de texto con la autenticación de la app:

Python

  1. En el directorio de trabajo, crea un archivo llamado chat_create_text_message_app.py.
  2. Incluye el siguiente código en chat_create_text_message_app.py:

    from apiclient.discovery import build
    from google.oauth2 import service_account
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = service_account.Credentials.from_service_account_file(
        'credentials.json', scopes=SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', credentials=CREDENTIALS)
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. En el código, reemplaza SPACE por un nombre de espacio, que puedes obtener del método spaces.list() en la API de Chat o desde la URL de un espacio.

  4. En el directorio de trabajo, compila y ejecuta la muestra:

    python3 chat_create_text_message_app.py
    

La API de Chat muestra una instancia de Message en la que se detalla el mensaje que se envía.

Envía un mensaje de texto con la autenticación del usuario

A continuación, te mostramos cómo enviar un mensaje de texto con la autenticación de usuario:

Python

  1. En el directorio de trabajo, crea un archivo llamado chat_create_text_message_user.py.
  2. Incluye el siguiente código en chat_create_text_message_user.py:

    import os.path
    
    from google.auth.transport.requests import Request
    from google.oauth2.credentials import Credentials
    from google_auth_oauthlib.flow import InstalledAppFlow
    from googleapiclient.discovery import build
    from googleapiclient.errors import HttpError
    
    # Define your app's authorization scopes.
    # When modifying these scopes, delete the file token.json, if it exists.
    SCOPES = ["https://www.googleapis.com/auth/chat.messages.create"]
    
    def main():
        '''
        Authenticates with Chat API via user credentials,
        then creates a text message in a Chat space.
        '''
    
        # Start with no credentials.
        creds = None
    
        # Authenticate with Google Workspace
        # and get user authorization.
        flow = InstalledAppFlow.from_client_secrets_file(
                        'client_secrets.json', SCOPES)
        creds = flow.run_local_server()
    
        # Build a service endpoint for Chat API.
        chat = build('chat', 'v1', credentials=creds)
    
        # Use the service endpoint to call Chat API.
        result = chat.spaces().messages().create(
    
            # The space to create the message in.
            #
            # Replace SPACE with a space name.
            # Obtain the space name from the spaces resource of Chat API,
            # or from a space's URL.
            parent='spaces/SPACE',
    
            # The message to create.
            body={'text': 'Hello, world!'}
    
        ).execute()
    
        # Prints details about the created membership.
        print(result)
    
    if __name__ == '__main__':
        main()
    
  3. En el código, reemplaza SPACE por un nombre de espacio, que puedes obtener del método spaces.list() en la API de Chat o desde la URL de un espacio.

  4. En el directorio de trabajo, compila y ejecuta la muestra:

    python3 chat_create_text_message_user.py
    

La API de Chat muestra una instancia de Message en la que se detalla el mensaje que se envía.

Enviar mensajes de tarjeta

En esta sección, se describe cómo enviar mensajes con tarjetas de las siguientes dos maneras:

  • Responde a la interacción del usuario para enviar un mensaje de tarjeta en tiempo real.
  • Llama a la API de Google Chat de forma asíncrona para enviar un mensaje de tarjeta.


Diseña tarjetas y obtén una vista previa de ellas con el Creador de tarjetas.

Abre el Creador de tarjetas

Envía un mensaje de tarjeta en tiempo real

Las apps de Chat pueden crear mensajes de tarjeta para responder a una interacción del usuario, como cuando un usuario envía un mensaje a la app de Chat o agrega la app de Chat a un espacio. Si quieres obtener más información para responder a las interacciones del usuario, consulta Recibe y responde eventos de interacción de la app de Chat.

En este ejemplo, un usuario envía un mensaje a una app de Chat, y la app de Chat responde con un mensaje de tarjeta que muestra el nombre y la imagen de avatar del usuario:

Una app de Chat que responde con una tarjeta que muestra el nombre visible y la imagen de avatar del remitente.

Node.js

node/avatar-app/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Apps Script

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Cómo enviar un mensaje de tarjeta de forma asíncrona

Para enviar un mensaje de tarjeta, pasa lo siguiente en la solicitud:

  • Con la autenticación de la app, especifica el alcance de la autorización chat.bot. No puedes enviar un mensaje de tarjeta con autenticación de usuario.
  • Llama al método create en el recurso Message.

El siguiente es un ejemplo de un mensaje de tarjeta:

Un mensaje de tarjeta que se envía con la API de Chat

A continuación, te indicamos cómo enviar un mensaje de tarjeta con la autenticación de la app:

Python

  1. En el directorio de trabajo, crea un archivo llamado chat_create_card_message.py.
  2. Incluye el siguiente código en chat_create_card_message.py:

    from apiclient.discovery import build
    from google.oauth2 import service_account
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = service_account.Credentials.from_service_account_file(
        'credentials.json', scopes=SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', credentials=CREDENTIALS)
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # The message to create.
        body=
        {
          'cardsV2': [{
            'cardId': 'createCardMessage',
            'card': {
              'header': {
                'title': 'A card message!',
                'subtitle': 'Created with the Chat API',
                'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
                'imageType': 'CIRCLE'
              },
              'sections': [
                {
                  'widgets': [
                    {
                      'buttonList': {
                        'buttons': [
                          {
                            'text': 'Read the docs!',
                            'onClick': {
                              'openLink': {
                                'url': 'https://developers.google.com/chat'
                              }
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              ]
            }
          }]
        }
    
    ).execute()
    
    print(result)
    
  3. En el código, reemplaza SPACE por un nombre de espacio, que puedes obtener del método spaces.list en la API de Chat o desde la URL de un espacio.

  4. En el directorio de trabajo, compila y ejecuta la muestra:

    python3 chat_create_card_message.py
    

Iniciar o responder una conversación de mensajes

Para iniciar una conversación, envía un mensaje y deja thread.name vacío. Google Chat lo propagará cuando cree la conversación. De manera opcional, para personalizar el nombre del subproceso, especifica el campo thread.threadKey.

Para responder una conversación, envía un mensaje que especifique el campo threadKey o name de la conversación. Si una persona o alguna otra app de Chat creó la conversación, debes usar el campo thread.name.

Si no se encuentra una conversación que coincida, puedes configurar el campo messageReplyOption para especificar si un mensaje debe iniciar una conversación nueva o no publicarse.

Si se configura messageReplyOption, también debes configurar thread.name o thread.threadKey.

A continuación, se muestra cómo iniciar o responder una conversación con el campo threadKey definido como nameOfThread:

Python

  1. En el directorio de trabajo, crea un archivo llamado chat_create_message_thread.py.
  2. Incluye el siguiente código en chat_create_message_thread.py:

    from apiclient.discovery import build
    from google.oauth2 import service_account
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = service_account.Credentials.from_service_account_file(
        'credentials.json', scopes=SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', credentials=CREDENTIALS)
    
    # Create a Chat message.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # Whether to start a thread or reply to an existing one.
        #
        # Required when threading is enabled in a space unless starting a
        # thread.  Ignored in other space types. Threading is enabled when
        # space.spaceThreadingState is THREADED_MESSAGES.
        #
        # REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD replies to an existing thread
        # if one exists, otherwise it starts a new one.
        messageReplyOption='REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD',
    
        # The message body.
        body={
    
            # The message to create.
            'text': 'Start or reply to another message in a thread!',
    
            # The thread to start or reply to.
            'thread': {
                'threadKey': 'nameOfThread'
            }
        }
    
    ).execute()
    
    print(result)
    
  3. En el código, reemplaza SPACE por un nombre de espacio, que puedes obtener del método spaces.list en la API de Chat o desde la URL de un espacio.

  4. En el directorio de trabajo, compila y ejecuta la muestra:

    python3 chat_create_message_thread.py
    

La API de Chat muestra una instancia de Message en la que se detalla el mensaje que se envía.

Asígnale un nombre a un mensaje

En esta sección, se explica cómo configurar un ID personalizado para asignarle un nombre a un mensaje. Puedes usar IDs personalizados para obtener, actualizar o borrar mensajes. Los IDs personalizados te permiten especificar un mensaje sin necesidad de almacenar el ID que asigna el sistema desde el nombre del recurso del mensaje (representado en el campo name). El nombre del recurso se genera en el cuerpo de la respuesta cuando creas el mensaje.

Por ejemplo, para recuperar un mensaje con el método get(), debes usar el nombre del recurso a fin de especificar qué mensaje recuperar. El nombre del recurso tiene el formato spaces/{space}/messages/{message}, en el que {message} representa el ID que asigna el sistema. Si le asignaste un nombre al mensaje, puedes reemplazar el valor de {message} por el ID personalizado.

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

Solo puedes asignarle un nombre a un mensaje cuando lo creas. No puedes asignar un nombre o modificar un ID personalizado para los mensajes existentes. El ID personalizado debe cumplir 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.

A continuación, te indicamos cómo enviar un mensaje con un ID personalizado:

Python

  1. En el directorio de trabajo, crea un archivo llamado chat_create_named_message.py.
  2. Incluye el siguiente código en chat_create_named_message.py:

    from apiclient.discovery import build
    from google.oauth2 import service_account
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = service_account.Credentials.from_service_account_file(
        'credentials.json', scopes=SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', credentials=CREDENTIALS)
    
    # Create a Chat message with a custom name.
    result = chat.spaces().messages().create(
    
        # The space to create the message in.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        parent='spaces/SPACE',
    
        # Custom name for the message used to facilitate later operations.
        messageId='client-NAME',
    
        # The message to create.
        body={'text': 'Hello, world!'}
    
    ).execute()
    
    print(result)
    
  3. En el código, reemplaza lo siguiente:

    • SPACE: Es el ID del espacio en el que quieres publicar el mensaje, que puedes obtener mediante el método spaces.list en la API de Chat o desde la URL de un espacio.
    • NAME: Es el nombre personalizado del mensaje.
  4. En el directorio de trabajo, compila y ejecuta la muestra:

    python3 chat_create_named_message.py
    

La API de Chat muestra una instancia de Message.

Cómo agregar widgets interactivos en la parte inferior de un mensaje

De manera opcional, puedes agregar mensajes con widgets accesorios. Los widgets accesorios aparecen después del texto o las tarjetas en un mensaje. Puedes usar estos widgets para solicitar a los usuarios que interactúen con tu mensaje de muchas maneras, como las siguientes:

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

Para agregar widgets accesorios, incluye el objeto accessoryWidgets[] en el mensaje y especifica uno o más AccessoryWidgets que desees incluir. El mensaje debe ser visible para todos los miembros del espacio (no puedes agregar widgets accesorios a los mensajes privados).

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

Ejemplos de widgets accesorios

En la siguiente muestra de código, se ve el JSON para este mensaje. Cuando un usuario hace clic en uno de los botones, la interacción activa la función correspondiente (como doUpvote) que procesa la calificació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",
             }
           }
         }
       ]
     }
   }
 ]

Envía mensajes de forma privada

Las apps de Chat pueden enviar mensajes de texto y de tarjetas de forma privada, de modo que solo un usuario del espacio pueda verlo. Para enviar un mensaje de forma privada, debes especificar el campo privateMessageViewer en el mensaje. Solo las apps de Chat pueden enviar mensajes privados. Para enviar un mensaje privado de forma asíncrona, debes usar la autenticación de la app.

Para obtener más información, consulta Envía mensajes privados a usuarios de Google Chat.

Solución de problemas

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

Si bien es posible que no se muestre un mensaje de error en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles que te ayudarán a corregir errores cuando se activa el registro de errores para las apps de Chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Cómo solucionar problemas de Google Chat.