En esta guía, se explican las diferentes formas en que las apps de Google Chat pueden enviar mensajes:
- Responde a la interacción de un usuario para enviar mensajes de texto y tarjetas en tiempo real.
- Envía mensajes de texto y tarjetas de forma asíncrona llamando al método
create
en el recursoMessage
. - Iniciar o responder 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 llamando a los métodos correspondientes. Para obtener más información sobre los mensajes de texto y tarjetas, consulta la
Descripción general de los mensajes de Google Chat.
El tamaño máximo de los mensajes (incluidos los mensajes de texto o las tarjetas) es de 32,000 bytes. Si un mensaje supera este tamaño, la app de Chat puede enviar varios mensajes en su lugar.
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 de 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 conocer más detalles, consulta
Recibe y responde las interacciones con tu app de Google Chat.
Requisitos previos
Node.js
- Una cuenta de Google Workspace con acceso a Google Chat
- 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.
- El envío de un mensaje de texto admite los siguientes métodos de autorización:
- Autenticación de usuarios con el alcance de autorización
chat.messages.create
ochat.messages
- Autenticación de la app con el permiso de autorización
chat.bot
- Autenticación de usuarios con el alcance de autorización
- Para enviar un mensaje de tarjeta, se requiere la autenticación de la app con el permiso de autorización
chat.bot
.
- El envío de un mensaje de texto admite los siguientes métodos de autorización:
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.
- El envío de un mensaje de texto admite los siguientes métodos de autorización:
- Autenticación de usuarios con el alcance de autorización
chat.messages.create
ochat.messages
- Autenticación de la app con el permiso de autorización
chat.bot
- Autenticación de usuarios con el alcance de autorización
- Para enviar un mensaje de tarjeta, se requiere la autenticación de la app con el permiso de autorización
chat.bot
.
- El envío de un mensaje de texto admite los siguientes métodos de autorización:
Apps Script
- Una cuenta de Google Workspace con acceso a Google Chat
- Una app de Chat publicada. Para compilar una app de Chat, sigue esta quickstart.
- 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.
- El envío de un mensaje de texto admite los siguientes métodos de autorización:
- Autenticación de usuarios con el alcance de autorización
chat.messages.create
ochat.messages
- Autenticación de la app con el permiso de autorización
chat.bot
- Autenticación de usuarios con el alcance de autorización
- Para enviar un mensaje de tarjeta, se requiere la autenticación de la app con el permiso de autorización
chat.bot
.
- El envío de un mensaje de texto admite los siguientes métodos de autorización:
Enviar mensajes de texto
Esta sección describe cómo enviar mensajes de texto de las dos maneras siguientes:
- 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, la app de Chat crea y envía un mensaje de texto cada vez que se agrega a un espacio. Si deseas obtener información sobre las prácticas recomendadas para incorporar usuarios, consulta Ayuda a las personas y los espacios a comenzar a usar integraciones útiles.
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 de 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 devuelve el siguiente mensaje de texto:
Cómo enviar mensajes 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 apps y la autenticación de usuarios.
Para enviar un mensaje de texto, incluye 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 de usuario, especifica el alcance de la autorizaciónchat.messages.create
. - Llama al método
create
en el recursoMessage
.
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 apps:
Python
- En el directorio de trabajo, crea un archivo llamado
chat_create_text_message_app.py
. 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)
En el código, reemplaza
SPACE
por un nombre de espacio, que puedes obtener del métodospaces.list()
en la API de Chat o de la URL de un espacio.En tu directorio de trabajo, compila y ejecuta la muestra:
python3 chat_create_text_message_app.py
La API de Chat muestra una instancia de
Message
que detalla el mensaje enviado.
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
- En el directorio de trabajo, crea un archivo llamado
chat_create_text_message_user.py
. 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 message. print(result) if __name__ == '__main__': main()
En el código, reemplaza
SPACE
por un nombre de espacio, que puedes obtener del métodospaces.list()
en la API de Chat o de la URL de un espacio.En tu directorio de trabajo, compila y ejecuta la muestra:
python3 chat_create_text_message_user.py
La API de Chat muestra una instancia de
Message
que detalla el mensaje enviado.
Enviar mensajes de tarjeta
En esta sección, se describe cómo enviar mensajes de tarjeta de las siguientes dos maneras:
- Envía un mensaje de tarjeta en tiempo real respondiendo a una interacción del usuario.
- Envía un mensaje de tarjeta llamando a la API de Google Chat de forma asíncrona.
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 la agrega 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 con la app de Chat.
En este ejemplo, un usuario envía un mensaje a una app de Chat y esta responde con un mensaje de tarjeta que muestra el nombre del usuario y la imagen de avatar:
Node.js
Python
Apps Script
En este ejemplo, se muestra el JSON de la tarjeta para enviar un mensaje de tarjeta. También puedes usar el servicio de tarjetas de Apps Script.
Envía 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 la autenticación de usuario. - Llama al método
create
en el recursoMessage
.
El siguiente es un ejemplo de un mensaje de tarjeta:
A continuación, te mostramos cómo enviar un mensaje de tarjeta con autenticación de app:
Python
- En el directorio de trabajo, crea un archivo llamado
chat_create_card_message.py
. 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)
En el código, reemplaza
SPACE
por un nombre de espacio, que puedes obtener del métodospaces.list
en la API de Chat o de la URL de un espacio.En tu 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 se cree la conversación. De manera opcional, para personalizar el nombre del subproceso, especifica el campo thread.threadKey
.
Para responder un hilo de mensajes, envía un mensaje que especifique el campo threadKey
o name
de la conversación. Si otra persona o app de Chat creó la conversación, debes usar el campo thread.name
.
De lo contrario, puedes configurar el campo messageReplyOption
para especificar si un mensaje debe iniciar una conversación nueva o no hacerlo.
Si se configura messageReplyOption
, también debes configurar thread.name
o thread.threadKey
.
A continuación, se indica cómo iniciar o responder una conversación con el campo threadKey
definido como nameOfThread
:
Python
- En el directorio de trabajo, crea un archivo llamado
chat_create_message_thread.py
. 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)
En el código, reemplaza
SPACE
por un nombre de espacio, que puedes obtener del métodospaces.list
en la API de Chat o de la URL de un espacio.En tu directorio de trabajo, compila y ejecuta la muestra:
python3 chat_create_message_thread.py
La API de Chat muestra una instancia de
Message
que detalla el mensaje enviado.
Escribe un nombre para el mensaje
En esta sección, se explica cómo asignarle un nombre a un mensaje mediante la configuración de un ID personalizado para el mensaje. Puedes usar IDs personalizados para obtener, actualizar o borrar mensajes. Los ID personalizados te permiten especificar un mensaje sin necesidad de almacenar el ID asignado por el sistema del 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 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. Si le pusiste un nombre al mensaje, puedes reemplazar el valor de {message}
por el ID personalizado.
Para asignar 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 nombrar 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, perocustom-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 mensajes diferentes.
A continuación, te indicamos cómo enviar un mensaje con un ID personalizado:
Python
- En el directorio de trabajo, crea un archivo llamado
chat_create_named_message.py
. 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)
En el código, reemplaza lo siguiente:
SPACE
: Es el ID del espacio en el que quieres publicar el mensaje, que puedes obtener del métodospaces.list
de la API de Chat o de la URL de un espacio.NAME
: Es el nombre personalizado del mensaje.
En tu 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 de accesorios aparecen después de texto o tarjetas en un mensaje. Puedes usar estos widgets para solicitar a los usuarios que interactúen con tu mensaje de varias maneras, incluidas las siguientes:
- Calificar la precisión o satisfacción de un mensaje.
- Informa un problema con el mensaje o la app de Chat.
- Abre un vínculo a 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 accesorios, incluye el objeto accessoryWidgets[]
en el mensaje y especifica uno o más AccessoryWidgets
que quieras incluir. El mensaje debe ser visible para todas las personas en el espacio (no puedes agregar widgets complementarios a los mensajes privados).
En la siguiente imagen, se muestra una app de Chat que agrega un mensaje de texto con widgets accesorios para que los usuarios puedan calificar su experiencia con la app de Chat.
En la siguiente muestra de código, se muestra el JSON de 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",
}
}
}
]
}
}
]
Cómo enviar mensajes de forma privada
Las apps de Chat pueden enviar mensajes de texto y tarjetas de forma privada para que solo un usuario pueda verlo en el espacio. Para enviar un mensaje de forma privada, especifica 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 conocer más detalles, consulta Envía mensajes privados a usuarios de Google Chat.
Solucionar problemas
Cuando una app o una tarjeta de Google Chat muestran un error, la interfaz de Chat muestra el mensaje “Se produjo un error”. o "No se pudo procesar la 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, puede que no aparezca un mensaje de tarjeta.
Aunque es posible que un mensaje de error no aparezca en la IU de Chat, hay mensajes de error descriptivos y datos de registro disponibles para ayudarte a corregir errores cuando está activado el registro de errores para las apps de Chat. Si necesitas ayuda para ver, depurar y corregir errores, consulta Cómo solucionar problemas y corregir errores de Google Chat.
Temas relacionados
- Da formato a un mensaje.
- Obtener detalles sobre un mensaje
- Crea una lista de los mensajes de un espacio.
- Actualiza un mensaje.
- Borra un mensaje.
- Identifica usuarios en mensajes de Google Chat.
- Envía mensajes a Google Chat con webhooks entrantes.