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

El recurso Message representa un mensaje de texto o de tarjeta en Google Chat. Puedes create, get, update o delete un mensaje en la API de Google Chat llamando 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 con tarjeta de manera 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 detalles, consulta Recibe y responde interacciones con tu app de Google Chat.

Requisitos previos

Node.js

Python

  • 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 la interfaz de línea de comandos:

    pip3 install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib oauth2client

  • Una app de Chat publicada. Para crear y publicar una app de Chat, consulta Cómo compilar 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 una 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, tu 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 la integración de personas y espacios.

Para enviar un mensaje de texto cuando un usuario agrega tu app de Chat a un espacio, la app de Chat 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 tu 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 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

Para enviar un mensaje de texto con la autenticación de la app, sigue estos pasos:

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 httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 envió.

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

Para enviar un mensaje de texto con la autenticación del usuario, sigue estos pasos:

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 el nombre de un 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 envió.

Enviar mensajes con tarjetas

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

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

Envía un mensaje con tarjeta en tiempo real

Las apps de Chat pueden crear mensajes de tarjetas 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 deseas 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 del avatar del usuario:

Una app de Chat que responde con una tarjeta que muestra el nombre visible y la imagen del 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],
      }
    }],
  };
}

Envía un mensaje con tarjeta de manera 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 con tarjeta mediante la autenticación del usuario.
  • Llama al método create en el recurso Message.

El siguiente es un ejemplo de un mensaje de tarjeta:

Un mensaje de tarjeta enviado con la API de Chat.

Sigue estos pasos para enviar un mensaje de tarjeta mediante 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 httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 de mensajes, envía un mensaje y deja thread.name vacío. Google Chat lo propaga cuando se crea 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 ningún subproceso que coincida, puedes especificar si un mensaje debe iniciar uno nuevo o no publicarlo. Para ello, configura el campo messageReplyOption.

A continuación, se explica 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 httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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 envió.

Cómo enviar un mensaje y asignarle un nombre

En esta sección, se explica cómo enviar un mensaje con un nombre personalizado. Los nombres de los mensajes se usan para obtener, actualizar o borrar mensajes. Asignar un nombre personalizado también permite que una app de Chat recupere el mensaje sin guardar el name del mensaje del cuerpo de la respuesta que se muestra cuando se envía el mensaje.

Asignar un nombre personalizado no reemplaza el campo name generado, el nombre del recurso del mensaje. En cambio, establece el nombre personalizado como el campo clientAssignedMessageId, al que puedes hacer referencia durante operaciones posteriores, como actualizar o borrar el mensaje.

Los nombres personalizados tienen los siguientes requisitos:

  • Comienza con client-. Por ejemplo, client-custom-name es un nombre personalizado válido, pero custom-name no lo es.
  • Contener solo letras minúsculas, números y guiones
  • No debe tener más de 63 caracteres de longitud.
  • Si especificas un nombre personalizado usado mientras envías un mensaje, se muestra un error, pero otros métodos, como update y delete, funcionan como se espera.

Para enviar un mensaje y asignarle un nombre, sigue estos pasos:

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 httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'credentials.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# 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-custom-name',

    # 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_named_message.py

La API de Chat muestra una instancia de Message en la que se detalla el mensaje que se envió.

Solución de problemas

Cuando una app o tarjeta de Google Chat 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.

Aunque 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 para ayudarte a corregir errores cuando se activa el registro de errores de las apps de chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Cómo solucionar y corregir errores de Google Chat.