En esta guía, se explica cómo usar el método create()
en el recurso Message
de la API de Google Chat para hacer lo siguiente:
- Envía mensajes que contengan texto, tarjetas y widgets interactivos.
- Enviar mensajes de forma privada a un usuario específico de Chat
- Iniciar o responder una conversación de mensajes
- Asigna un nombre a un mensaje para que puedas especificarlo en otras solicitudes a la API de Chat.
El tamaño máximo del mensaje (incluidos el texto o las tarjetas) es de 32,000 bytes. Para enviar un mensaje que supere este tamaño, la app de Chat debe enviar varios mensajes.
Además de llamar a la API de Chat para crear mensajes, las apps de Chat pueden crear y enviar mensajes para responder a las interacciones de los usuarios, como publicar un mensaje de bienvenida después de que un usuario agrega la app de Chat a un espacio. Cuando responden a interacciones, las apps de Chat pueden usar otros tipos de funciones de mensajería, como diálogos interactivos e interfaces de vista previa de vínculos. Para responder a un usuario, la app de Chat muestra el mensaje de forma síncrona, sin llamar a la API de Chat. Para obtener información sobre cómo enviar mensajes para responder a las interacciones, consulta Cómo recibir y responder interacciones con la app de Google Chat.
Cómo Chat muestra y atribuye los mensajes creados con la API de Chat
Puedes llamar al método create()
con la autenticación de apps y la autenticación de usuarios.
Chat atribuye al remitente del mensaje de forma diferente según el tipo de autenticación que uses.
Cuando te autenticas como la app de Chat, esta envía el mensaje.
Cuando te autenticas como usuario, la app de Chat envía el mensaje en nombre del usuario. Chat también muestra el nombre de la app de Chat para atribuirla al mensaje.
El tipo de autenticación también determina qué funciones y interfaces de mensajería puedes incluir en el mensaje. Con la autenticación de apps, las apps de Chat pueden enviar mensajes que contienen texto enriquecido, interfaces basadas en tarjetas y widgets interactivos. Dado que los usuarios de Chat solo pueden enviar texto en sus mensajes, solo puedes incluir texto cuando creas mensajes con la autenticación del usuario. Para obtener más información sobre las funciones de mensajería disponibles para la API de Chat, consulta la descripción general de los mensajes de Google Chat.
En esta guía, se explica cómo usar cualquiera de los tipos de autenticación para enviar un mensaje con la API de Chat.
Requisitos previos
Node.js
- Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat
- Configura tu entorno:
- Crea un proyecto de Google Cloud
- Configura la pantalla de consentimiento de OAuth.
- Habilita y configura la API de Google Chat con un nombre, un ícono y una descripción para tu app de Chat.
- Instala la biblioteca cliente de Cloud para Node.js.
- Crea credenciales de acceso según la forma en que deseas autenticarte en tu solicitud a la API de Google Chat:
- Para autenticarte como usuario de Chat,
crea credenciales de ID de cliente de
OAuth y guárdalas como un archivo JSON llamado
client_secrets.json
en tu directorio local. - Para autenticarte como la app de Chat,
crea credenciales de cuenta de servicio y guárdalas como un archivo JSON con el nombre
credentials.json
.
- Para autenticarte como usuario de Chat,
crea credenciales de ID de cliente de
OAuth y guárdalas como un archivo JSON llamado
- Elige un alcance de autorización según si deseas autenticarte como usuario o como la app de Chat.
- Un espacio de Google Chat del que sea miembro el usuario autenticado o la app de Chat que realiza la llamada. Para autenticarte como la app de Chat, agrégala al espacio.
Python
- Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat
- Configura tu entorno:
- Crea un proyecto de Google Cloud
- Configura la pantalla de consentimiento de OAuth.
- Habilita y configura la API de Google Chat con un nombre, un ícono y una descripción para tu app de Chat.
- Instala la biblioteca cliente de Cloud de Python.
- Crea credenciales de acceso según la forma en que deseas autenticarte en tu solicitud a la API de Google Chat:
- Para autenticarte como usuario de Chat,
crea credenciales de ID de cliente de
OAuth y guárdalas como un archivo JSON llamado
client_secrets.json
en tu directorio local. - Para autenticarte como la app de Chat,
crea credenciales de cuenta de servicio y guárdalas como un archivo JSON con el nombre
credentials.json
.
- Para autenticarte como usuario de Chat,
crea credenciales de ID de cliente de
OAuth y guárdalas como un archivo JSON llamado
- Elige un alcance de autorización según si deseas autenticarte como usuario o como la app de Chat.
- Un espacio de Google Chat del que sea miembro el usuario autenticado o la app de Chat que realiza la llamada. Para autenticarte como la app de Chat, agrégala al espacio.
Java
- Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat
- Configura tu entorno:
- Crea un proyecto de Google Cloud
- Configura la pantalla de consentimiento de OAuth.
- Habilita y configura la API de Google Chat con un nombre, un ícono y una descripción para tu app de Chat.
- Instala la biblioteca cliente de Cloud para Java.
- Crea credenciales de acceso según la forma en que deseas autenticarte en tu solicitud a la API de Google Chat:
- Para autenticarte como usuario de Chat,
crea credenciales de ID de cliente de
OAuth y guárdalas como un archivo JSON llamado
client_secrets.json
en tu directorio local. - Para autenticarte como la app de Chat,
crea credenciales de cuenta de servicio y guárdalas como un archivo JSON con el nombre
credentials.json
.
- Para autenticarte como usuario de Chat,
crea credenciales de ID de cliente de
OAuth y guárdalas como un archivo JSON llamado
- Elige un alcance de autorización según si deseas autenticarte como usuario o como la app de Chat.
- Un espacio de Google Chat del que sea miembro el usuario autenticado o la app de Chat que realiza la llamada. Para autenticarte como la app de Chat, agrégala al espacio.
Apps Script
- Una cuenta de Google Workspace para empresas o empresas con acceso a Google Chat
- Configura tu entorno:
- Crea un proyecto de Google Cloud
- Configura la pantalla de consentimiento de OAuth.
- Habilita y configura la API de Google Chat con un nombre, un ícono y una descripción para tu app de Chat.
- Crea un proyecto independiente de Apps Script y activa el servicio de Chat avanzado.
- En esta guía, debes usar la autenticación del usuario o de la app. Para autenticar como la app de Chat, crea credenciales de cuenta de servicio. Para conocer los pasos, consulta Autentícate y autoriza como una app de Google Chat.
- Elige un alcance de autorización según si deseas autenticarte como usuario o como la app de Chat.
- Un espacio de Google Chat del que sea miembro el usuario autenticado o la app de Chat que realiza la llamada. Para autenticarte como la app de Chat, agrégala al espacio.
Envía un mensaje como la app de Chat
En esta sección, se explica cómo enviar mensajes que contienen texto, tarjetas y widgets de accesorios interactivos con la autenticación de apps.
Para llamar al método CreateMessage()
con la autenticación de apps, debes especificar los siguientes campos en la solicitud:
- El alcance de la autorización de
chat.bot
- El recurso
Space
en el que deseas publicar el mensaje. La app de Chat debe ser miembro del espacio. - El recurso
Message
que se creará. Para definir el contenido del mensaje, puedes incluir texto enriquecido (text
), una o más interfaces de tarjetas (cardsV2
), o ambas.
De manera opcional, puedes incluir lo siguiente:
- El campo
accessoryWidgets
para incluir botones interactivos en la parte inferior del mensaje. - El campo
privateMessageViewer
para enviar el mensaje de forma privada a un usuario específico. - El campo
messageId
, que te permite asignar un nombre al mensaje para usarlo en otras solicitudes a la API. - Los campos
thread.threadKey
ymessageReplyOption
para iniciar o responder una conversación. Si el espacio no usa subprocesos, se ignora este campo.
En el siguiente código, se muestra un ejemplo de cómo una app de chat puede enviar un mensaje publicado como la app de chat que contiene texto, una tarjeta y un botón en el que se puede hacer clic en la parte inferior del mensaje:
Node.js
Python
Java
Apps Script
Para ejecutar este ejemplo, reemplaza SPACE_NAME
por el ID del campo name
del espacio. Para obtener el ID, llama al método ListSpaces()
o desde la URL del espacio.
Cómo agregar widgets interactivos en la parte inferior de un mensaje
En la primera muestra de código de esta guía, el mensaje de la app de chat muestra un botón en el que se puede hacer clic en la parte inferior del mensaje, conocido como widget de accesorio. Los widgets de accesorios aparecen después de cualquier texto o tarjeta en un mensaje. Puedes usar estos widgets para solicitar a los usuarios que interactúen con tu mensaje de muchas maneras, incluidas las siguientes:
- Calificar la exactitud 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.
- Anular o posponer mensajes similares de la app de Chat durante un período específico
Para agregar widgets de accesorios, incluye el campo
accessoryWidgets[]
en el cuerpo de la solicitud y especifica uno o más widgets que desees
incluir.
En la siguiente imagen, se muestra una app de Chat que agrega un mensaje de texto con widgets de accesorios para que los usuarios puedan calificar su experiencia con la app de Chat.
A continuación, se muestra el cuerpo de la solicitud que crea un mensaje de texto con dos botones de accesorios. Cuando un usuario hace clic en un botón, la función correspondiente (como doUpvote
) procesa la interacción:
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
Cómo enviar un mensaje de forma privada
Las apps de Chat pueden enviar mensajes de forma privada para que solo un usuario específico del espacio pueda verlos. Cuando una app de chat envía un mensaje privado, este muestra una etiqueta que notifica al usuario que solo él puede verlo.
Para enviar un mensaje de forma privada con la API de Chat, especifica el campo
privateMessageViewer
en el cuerpo de la solicitud. Para especificar al usuario, debes establecer el valor en el recurso User
que representa al usuario de Chat. También puedes usar el campo name
del recurso User
, como se muestra en el siguiente ejemplo:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Para usar este ejemplo, reemplaza USER_ID
por un ID único para el usuario, como 12345678987654321
o hao@cymbalgroup.com
. Para obtener más información sobre cómo especificar usuarios, consulta Cómo identificar y especificar usuarios de Google Chat.
Para enviar un mensaje de forma privada, debes omitir lo siguiente en tu solicitud:
Cómo enviar un mensaje de texto en nombre de un usuario
En esta sección, se explica cómo enviar mensajes en nombre de un usuario mediante la autenticación de usuario. Con la autenticación del usuario, el contenido del mensaje solo puede contener texto y debe omitir las funciones de mensajería que solo están disponibles para las apps de Chat, incluidas las interfaces de tarjetas y los widgets interactivos.
Para llamar al método CreateMessage()
con la autenticación del usuario, debes especificar
los siguientes campos en la solicitud:
- Un alcance de autorización que admita la autenticación de usuarios para este método En el siguiente ejemplo, se usa el alcance
chat.messages.create
. - El recurso
Space
en el que deseas publicar el mensaje. El usuario autenticado debe ser miembro del espacio. - El recurso
Message
que se creará. Para definir el contenido del mensaje, debes incluir el campotext
.
De manera opcional, puedes incluir lo siguiente:
- El campo
messageId
, que te permite asignar un nombre al mensaje para usarlo en otras solicitudes a la API. - Los campos
thread.threadKey
ymessageReplyOption
para iniciar o responder una conversación Si el espacio no usa subprocesos, se ignora este campo.
En el siguiente código, se muestra un ejemplo de cómo una app de chat puede enviar un mensaje de texto en un espacio determinado en nombre de un usuario autenticado:
Node.js
Python
Java
Apps Script
Para ejecutar este ejemplo, reemplaza SPACE_NAME
por el ID del campo name
del espacio. Para obtener el ID, llama al método ListSpaces()
o desde la URL del espacio.
Cómo iniciar o responder en un hilo
En el caso de los espacios que usan conversaciones, puedes especificar si un mensaje nuevo inicia una conversación o responde a una existente.
De forma predeterminada, los mensajes que creas con la API de Chat inician una conversación nueva. Para ayudarte a identificar la conversación y responderla más adelante, puedes especificar una clave de conversación en tu solicitud:
- En el cuerpo de la solicitud, especifica el campo
thread.threadKey
. - Especifica el parámetro de consulta
messageReplyOption
para determinar qué sucede si la clave ya existe.
Para crear un mensaje que responda a una conversación existente, sigue estos pasos:
- En el cuerpo de la solicitud, incluye el campo
thread
. Si se establece, puedes especificar elthreadKey
que creaste. De lo contrario, debes usar elname
del subproceso. - Especifica el parámetro de consulta
messageReplyOption
.
En el siguiente código, se muestra un ejemplo de cómo una app de Chat puede enviar un mensaje de texto que inicia o responde una conversación determinada identificada por la clave de un espacio determinado en nombre de un usuario autenticado:
Node.js
Python
Java
Apps Script
Para ejecutar esta muestra, reemplaza lo siguiente:
THREAD_KEY
: Una clave de subproceso existente en el espacio o, para crear un subproceso nuevo, un nombre único para el subproceso.SPACE_NAME
: Es el ID del camponame
del espacio. Para obtener el ID, llama al métodoListSpaces()
o desde la URL del espacio.
Cómo asignar un nombre a un mensaje
Para recuperar o especificar un mensaje en llamadas a la API futuras, puedes asignarle un nombre. Para ello, configura el campo messageId
en tu solicitud.
Asignar un nombre al mensaje te permite especificarlo sin necesidad de almacenar el ID asignado por el sistema desde el nombre del recurso del mensaje (representado en el campo name
).
Por ejemplo, para recuperar un mensaje con el método get()
, 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 o el nombre personalizado que estableciste cuando creaste el mensaje.
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 asignar un nombre a un mensaje cuando lo creas. No puedes asignar un nombre ni modificarlo 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 diferentes mensajes.
En el siguiente código, se muestra un ejemplo de cómo una app de chat puede enviar un mensaje de texto con un ID a un espacio determinado en nombre de un usuario autenticado:
Node.js
Python
Java
Apps Script
Para ejecutar esta muestra, reemplaza lo siguiente:
SPACE_NAME
: Es el ID del camponame
del espacio. Para obtener el ID, llama al métodoListSpaces()
o desde la URL del espacio.MESSAGE-ID
: Es un nombre para el mensaje que comienza concustom-
. Debe ser único entre cualquier otro nombre de mensaje que cree la app de Chat en el espacio especificado.
Solucionar problemas
Cuando una app de Google Chat o una tarjeta muestran un error, la interfaz de Chat muestra un mensaje que dice "Se produjo un error". o "No se puede procesar tu solicitud". A veces, la IU de Chat no muestra ningún mensaje de error, pero la app o la tarjeta de Chat producen un resultado inesperado. Por ejemplo, es posible que no aparezca un mensaje de la tarjeta.
Aunque es posible que no se muestre un mensaje de error en la IU de Chat, los mensajes de error descriptivos y los datos de registro están 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 problemas y corregir errores de Google Chat.
Temas relacionados
- Usa el compilador de tarjetas para diseñar y obtener una vista previa de los mensajes de tarjetas JSON para apps de chat.
- Dar formato a los mensajes
- Obtén detalles sobre un mensaje.
- Hacer una lista de mensajes en un espacio
- Actualiza un mensaje.
- Borrar un mensaje.
- Identifica a los usuarios en los mensajes de Google Chat.
- Envía mensajes a Google Chat con webhooks entrantes.