En esta guía, se explican las diferentes formas en que las apps de Google Chat pueden mensajes:
- Responde al usuario para enviar mensajes de texto y tarjetas en tiempo real interacción.
- 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
texto
o
tarjeta
mensaje en Google Chat. Puedes
create
, get
, update
o delete
un mensaje en la API de Google Chat llamando
métodos correspondientes. Para obtener más información sobre los mensajes de texto y de tarjetas, consulta
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, tu app de Chat puedes 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 mensajes de texto o tarjetas de forma asíncrona
Las apps de Google Chat también pueden crear mensajes para responder a las interacciones de los usuarios en
en tiempo real. Las respuestas a las interacciones del usuario no requieren autenticación y
Admitir otros tipos de mensajes, como los vínculos y diálogos interactivos
vistas previas. Para obtener más información, 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 ver los pasos, consulta Compila una app de Google Chat.
- Autorización configurada para que la app de Chat envíe
y asíncronos. No se requiere ninguna configuración de autorización para enviar
mensajes en tiempo real.
- Enviar un
mensaje de texto
admite los siguientes métodos de autorización:
- Autenticación de usuarios
con la autorización
chat.messages.create
ochat.messages
del proyecto. - Autenticación de apps
con el permiso de autorización
chat.bot
.
- Autenticación de usuarios
con la autorización
- Enviar un
mensaje de tarjeta
requiere
autenticación de apps
con el permiso de autorización
chat.bot
.
- Enviar 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
- El valor pip herramienta de administración de paquetes
Las bibliotecas cliente de Google más recientes para Python. Para instalarlas o actualizarlas, 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 ver los pasos, consulta Compila una app de Google Chat.
Autorización configurada para que la app de Chat envíe y asíncronos. No se requiere ninguna configuración de autorización para enviar mensajes en tiempo real.
- Enviar un
mensaje de texto
admite los siguientes métodos de autorización:
- Autenticación de usuarios
con la autorización
chat.messages.create
ochat.messages
del proyecto. - Autenticación de apps
con el permiso de autorización
chat.bot
.
- Autenticación de usuarios
con la autorización
- Enviar un
mensaje de tarjeta
requiere
autenticación de apps
con el permiso de autorización
chat.bot
.
- Enviar 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 crear un App de Chat, sigue esta guía de inicio rápido.
- Autorización configurada para que la app de Chat envíe
y asíncronos. No se requiere ninguna configuración de autorización para enviar
mensajes en tiempo real.
- Enviar un
mensaje de texto
admite los siguientes métodos de autorización:
- Autenticación de usuarios
con la autorización
chat.messages.create
ochat.messages
del proyecto. - Autenticación de apps
con el permiso de autorización
chat.bot
.
- Autenticación de usuarios
con la autorización
- Enviar un
mensaje de tarjeta
requiere
autenticación de apps
con el permiso de autorización
chat.bot
.
- Enviar 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, tu app de Chat crea y envía un mensaje cada vez que se agrega a un espacio. Si quieres conocer las prácticas recomendadas para integrar usuarios, consulta Logra que las personas y los espacios comiencen con una integración útil.
Para enviar un mensaje de texto cuando un usuario agrega tu app de Chat
a un espacio, la app de Chat
responde a un ADDED_TO_SPACE
evento de interacción. Para responder a
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
La siguiente sección 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 autenticación de usuario, especifica el permiso de la autorización dechat.messages.create
. - Llama al
Método
create
en la 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 Autenticación de la app:
Python
- En tu 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 que puedes obtener de la Métodospaces.list()
en la API de Chat o desde 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 devuelve una instancia de
Message
en el 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 Autenticación de usuarios:
Python
- En tu 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 que puedes obtener de la Métodospaces.list()
en desde la API de Chat o desde 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 devuelve una instancia de
Message
en el que se detalla el mensaje que se envía.
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 con tarjetas para responder a un usuario como cuando un usuario envía a la app de Chat una mensaje o agregar la app de Chat a un espacio. Para obtener más información sobre cómo responder a las interacciones del usuario, consulta Recibe y responde a Interacción con la app de Chat eventos.
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 del usuario y la imagen del avatar:
Node.js
Python
Apps Script
En este ejemplo, se envía un mensaje de tarjeta mostrando JSON de la tarjeta. También puedes usar 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 tu 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 la 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 tu 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 que puedes obtener de la Métodospaces.list
en la API de Chat o desde 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 sal del mensaje.
thread.name
vacío; Google Chat la propaga cuando se crea la conversación. Opcionalmente, para
personalizar el nombre del subproceso, especificar
thread.threadKey
.
Para responder a un hilo de mensajes, envía un mensaje que especifique los
Campo threadKey
o name
. Si otra persona o alguien creó la conversación
en una app de Chat, debes usar el campo thread.name
.
Si no se encuentra ningún subproceso que coincida, puedes especificar
estableciendo si un mensaje debe iniciar una nueva conversación o no se publica
messageReplyOption
.
Si es messageReplyOption
, también debes establecer thread.name
o thread.threadKey
.
A continuación, te mostramos cómo iniciar o responder una conversación con el campo threadKey
definido de la siguiente manera:
nameOfThread
Python
- En tu 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 que puedes obtener de la Métodospaces.list
en la API de Chat o desde 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 devuelve una instancia de
Message
en el que se detalla el mensaje que se envía.
Escribe un nombre para el mensaje
En esta sección, se explica cómo asignarle un nombre a un mensaje configurando un ID personalizado para
mensaje. Puedes usar IDs personalizados para obtener, actualizar o borrar mensajes. ID personalizados
te permiten especificar un mensaje sin necesidad de almacenar el ID asignado por el sistema de
el nombre de recurso del mensaje (representado en el campo name
) El recurso
de Terraform se genera en la
cuerpo de la respuesta
cuando creas el mensaje.
Por ejemplo, para recuperar un mensaje con el método get()
, debes usar el
el nombre del recurso para especificar qué mensaje se recuperará. El nombre del recurso es
con 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 reemplazarlo
el valor de {message}
con el ID personalizado
Para asignar un nombre a un mensaje, especifica un ID personalizado en la
messageId
cuando crees el mensaje. El campo messageId
establece el valor de la
clientAssignedMessageId
del recurso Message
.
Solo puedes asignarle un nombre a un mensaje cuando lo creas. No puedes nombrar ni modificar un ID personalizado para mensajes existentes. El ID personalizado debe cumplir con los siguientes requisitos:
- Comienza con
client-
. Por ejemplo,client-custom-name
es una etiqueta personalizada válida ID, perocustom-name
no lo es. - Contiene hasta 63 caracteres y solo letras minúsculas, números guiones.
- Es único dentro de un espacio. Una app de Chat no puede usar mismo ID personalizado para diferentes mensajes.
A continuación, te indicamos cómo enviar un mensaje con un ID personalizado:
Python
- En tu 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 deseas realizar la acción. publicar el mensaje, que puedes obtener del Métodospaces.list
en la API de Chat o desde 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 devuelve 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 estas widgets para solicitar a los usuarios que interactúen con tu mensaje de muchas maneras, como lo siguiente:
- 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.
- Cómo descartar o posponer mensajes similares desde la app de Chat durante un período específico.
Para agregar widgets de accesorios, incluye el
accessoryWidgets[]
objeto en el mensaje y especificar uno o más
AccessoryWidgets
que quieres incluir. El mensaje debe ser visible para todas las personas del 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 adicionales 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
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 la
mensaje solo es visible para un usuario en el espacio. Para enviar un mensaje privado,
especificas el campo privateMessageViewer
en el mensaje. Solo
Las apps de Chat pueden enviar mensajes privados. Cómo 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 Google Chat individuales.
Solucionar problemas
Cuando una app de Google Chat o card muestra un error, el En la interfaz de Chat, aparece un mensaje que dice “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 de Chat la tarjeta produce un resultado inesperado; Por ejemplo, es posible que un mensaje de tarjeta no para que aparezca la opción.
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 de las apps de Chat. Para obtener ayuda sobre la visualización, la depuración y la corrección de errores, consulta Soluciona problemas y corrige 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.