En esta guía, se explica cómo llamar a las APIs de Google Chat
messages.create()
para realizar cualquiera de las siguientes acciones:
- Envía mensajes que contengan texto, tarjetas y widgets interactivos.
- Envía 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 otra API de Chat solicitudes.
El tamaño máximo de los mensajes (incluidos los mensajes de texto o las tarjetas) es de 32,000 bytes. Para enviar un mensaje que exceda este tamaño, tu app de Chat debes enviar varios mensajes.
Además de llamar al método messages.create()
, las apps de Chat
pueden crear y enviar mensajes para responder a interacciones de usuarios, como publicar un
mensaje de bienvenida después de que un usuario agrega la app de Chat a una
espacio. Para responder a interacciones, las apps de Chat pueden usar otras
tipos de funciones de mensajería, incluidos los diálogos interactivos y la vista previa de vínculos
interfaces. Para responderle a un usuario, la app de Chat
de forma síncrona, sin llamar a la API de Chat. Para aprender
sobre el envío de mensajes para responder a interacciones, consulta
Recibe y responde las interacciones con tu app de Google Chat.
Cómo se muestran y atribuyen mensajes en Chat creados con la API de Chat
Puedes llamar al método messages.create()
con
autenticación de apps
y la autenticación de usuarios.
Chat atribuye diferentes atributos al remitente del mensaje
según el tipo de autenticación que uses.
Cuando te autenticas como app de Chat, la app de Chat envía el mensaje.
Cuando te autenticas como usuario, la app de Chat envía el mensaje en nombre del usuario. Chat también atribuye de Chat al mensaje mostrando su nombre.
El tipo de autenticación también determina qué interfaces y funciones de mensajería que puedes incluir en el mensaje. Con la autenticación de apps, Las apps de chat pueden enviar mensajes que contengan texto enriquecido, interfaces basadas en tarjetas y widgets interactivos. Dado que los usuarios de Chat solo pueden enviar texto en sus mensajes, puedes hacer lo siguiente: solo incluya texto cuando cree mensajes con la autenticación de usuario. Para obtener más información sobre los mensajes 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 dos tipos de autenticación para enviar un mensaje con la API de Chat.
Requisitos previos
Node.js
- Una empresa o empresa de Google Workspace 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. y la descripción de tu app de Chat.
- Instala el Node.js Biblioteca cliente de Cloud.
- Crea credenciales de acceso según cómo quieras autenticarte en tu API de Google Chat
solicitud:
- Sigue estos pasos para autenticarte como usuario de Chat:
crear un ID de cliente de OAuth
credenciales y las guarda como un archivo JSON llamado
client_secrets.json
a tu directorio local. - Para autenticarte como la app de Chat, sigue estos pasos:
crear cuenta de servicio
credenciales y las guarda como un archivo JSON llamado
credentials.json
- Sigue estos pasos para autenticarte como usuario de Chat:
crear un ID de cliente de OAuth
credenciales y las guarda como un archivo JSON llamado
- Elige un alcance de autorización en función de si deseas autenticarte como usuario o App de Chat
- Un espacio de Google Chat en el que el usuario autenticado o que llamar a la app de Chat es miembro. Para autenticarse como App de Chat, agrega el de la app de Chat al espacio.
Python
- Una empresa o empresa de Google Workspace 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. y la descripción de tu app de Chat.
- Instala el Python Biblioteca cliente de Cloud.
- Crea credenciales de acceso según cómo quieras autenticarte en tu API de Google Chat
solicitud:
- Sigue estos pasos para autenticarte como usuario de Chat:
crear un ID de cliente de OAuth
credenciales y las guarda como un archivo JSON llamado
client_secrets.json
a tu directorio local. - Para autenticarte como la app de Chat, sigue estos pasos:
crear cuenta de servicio
credenciales y las guarda como un archivo JSON llamado
credentials.json
- Sigue estos pasos para autenticarte como usuario de Chat:
crear un ID de cliente de OAuth
credenciales y las guarda como un archivo JSON llamado
- Elige un alcance de autorización en función de si deseas autenticarte como usuario o App de Chat
- Un espacio de Google Chat en el que el usuario autenticado o que llamar a la app de Chat es miembro. Para autenticarse como App de Chat, agrega el de la app de Chat al espacio.
Java
- Una empresa o empresa de Google Workspace 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. y la descripción de tu app de Chat.
- Instala el Java Biblioteca cliente de Cloud.
- Crea credenciales de acceso según cómo quieras autenticarte en tu API de Google Chat
solicitud:
- Sigue estos pasos para autenticarte como usuario de Chat:
crear un ID de cliente de OAuth
credenciales y las guarda como un archivo JSON llamado
client_secrets.json
a tu directorio local. - Para autenticarte como la app de Chat, sigue estos pasos:
crear cuenta de servicio
credenciales y las guarda como un archivo JSON llamado
credentials.json
- Sigue estos pasos para autenticarte como usuario de Chat:
crear un ID de cliente de OAuth
credenciales y las guarda como un archivo JSON llamado
- Elige un alcance de autorización en función de si deseas autenticarte como usuario o App de Chat
- Un espacio de Google Chat en el que el usuario autenticado o que llamar a la app de Chat es miembro. Para autenticarse como App de Chat, agrega el App de Chat al espacio
Apps Script
- Una empresa o empresa de Google Workspace 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. y la descripción de tu app de Chat.
- Crear un proyecto independiente de Apps Script, y activa el Servicio de chat avanzado.
- En esta guía, debes usar las funciones o autenticación de apps. Para autenticarte como la app de Chat, crea las credenciales de la cuenta de servicio. Para ver los pasos, consulta Autentícate y autoriza app de Google Chat
- Elige un alcance de autorización en función de si deseas autenticarte como usuario o App de Chat
- Un espacio de Google Chat en el que el usuario autenticado o que llamar a la app de Chat es miembro. Para autenticarse como App de Chat, agrega el de la app de Chat 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 interactivos de accesorios con autenticación de la app.
Para llamar a messages.create()
con la autenticación de la app, debes especificar la
siguientes campos en la solicitud:
- El permiso de la autorización de
chat.bot
. - El recurso
Space
en el que deseas publicar el mensaje. La app de Chat debe estar a un miembro del espacio. - El
Message
recurso para crear. Para definir el contenido del mensaje, puedes incluir texto enriquecido (text
), una o más interfaces de tarjeta (cardsV2
), o ambas.
De manera opcional, puedes incluir lo siguiente:
- El campo
accessoryWidgets
que se debe incluir botones interactivos en la parte inferior del mensaje. - El campo
privateMessageViewer
envía el mensaje de forma privada a un usuario específico. - El campo
messageId
, que te permite Asigna 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 usar subprocesos, este campo se ignora.
En el siguiente código, se muestra un ejemplo de cómo una app de Chat puedes enviar un mensaje publicado como la app de Chat que contenga 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 esta muestra, reemplaza SPACE_NAME
por el ID de
el espacio
name
.
Para obtener el ID, llama al
Método spaces.list()
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. Widgets accesorios aparecer después de cualquier texto o tarjeta en un mensaje. Puedes usar estos widgets para indicarle que los usuarios interactúen con tu mensaje de muchas 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.
- 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[]
en el cuerpo de la solicitud y especificar uno o más widgets
para incluirlos.
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.
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 página de
(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 privado
Las apps de Chat pueden enviar mensajes de forma privada para que la mensaje solo es visible para un usuario específico en el espacio. Cuando un elemento Chat envía un mensaje privado, muestra una etiqueta que notifica al usuario que el mensaje solo es visible para él.
Para enviar un mensaje privado con la API de Chat, especifica la
privateMessageViewer
en el cuerpo de la solicitud. Para especificar el usuario, establece el valor en
el recurso User
que
representa al usuario de Chat. También puedes usar
Campo name
del
User
, como se muestra en el siguiente ejemplo:
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
Para usar esta muestra, reemplaza USER_ID
con un ID único para el usuario, como 12345678987654321
o
hao@cymbalgroup.com
Para obtener más información sobre la especificación de usuarios, consulta
Identifica y especifica usuarios de Google Chat.
Para enviar un mensaje de forma privada, debes omitir lo siguiente en la solicitud:
Envía un mensaje de texto en nombre de un usuario
Esta sección explica cómo enviar mensajes en nombre de un usuario utilizando autenticación de usuarios. Con la autenticación del usuario, el contenido del mensaje solo puede tener texto y debe omitir las funciones de mensajería que solo están disponibles para Apps de Chat, incluidas interfaces de tarjetas y widgets interactivos
Para llamar a messages.create()
con la autenticación de usuario, debes especificar el
siguientes campos en la solicitud:
- Un permiso de autorización
que admita la autenticación de usuarios para este método. En el siguiente ejemplo, se usa
el alcance de
chat.messages.create
. - El recurso
Space
en el que deseas publicar el mensaje. El usuario autenticado debe ser miembro del espacio. - El
Message
recurso para crear. Para definir el contenido del mensaje, debes incluir eltext
.
De manera opcional, puedes incluir lo siguiente:
- El campo
messageId
, que te permite Asigna 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 usar subprocesos, este campo se ignora.
En el siguiente código, se muestra un ejemplo de cómo una app de Chat pueden enviar un mensaje de texto en un espacio determinado en nombre de un usuario autenticado:
Node.js
Python
Java
Apps Script
Para ejecutar esta muestra, reemplaza SPACE_NAME
por el ID de
el espacio
name
. Para obtener el ID, llama al
Método spaces.list()
o desde la URL del espacio.
Iniciar o responder en una conversación
En los espacios que usan subprocesos, puedes especificar si un mensaje nuevo inicia una conversación o si responde un subproceso existente.
De forma predeterminada, los mensajes que creas con la API de Chat inician un nuevo conversación. Para identificar el hilo y responderlo más tarde, puedes especificar Thread en tu solicitud:
- En el cuerpo de tu solicitud, especifica la
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 tu solicitud, incluye el campo
thread
. Si está configurada, puedes especifica 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 se inicie o responda a una conversación determinada, identificada por 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
: Es una clave de subproceso existente en el espacio. para crear un subproceso nuevo, un nombre único para ese subproceso.SPACE_NAME
: Es el ID del espacio.name
. Para obtener el ID, llama al Métodospaces.list()
o desde la URL del espacio.
Escribe un nombre para el mensaje
Para recuperar o especificar un mensaje en futuras llamadas a la API, puedes asignarle el nombre
estableciendo el campo messageId
en tu solicitud messages.create()
.
Asignarle un nombre al mensaje te permite especificarlo sin necesidad de almacenar
ID asignado por el sistema del nombre del recurso del mensaje (representado en el
name
).
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 o el nombre personalizado que estableciste cuando creaste la
mensaje.
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.
En el siguiente código, se muestra un ejemplo de cómo una app de Chat puedes 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 espacio.name
. Para obtener el ID, llama al Métodospaces.list()
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 creado por el App de Chat en el espacio especificado.
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
- Usa el Creador de tarjetas para diseña y obtén una vista previa de mensajes de tarjetas JSON para apps de Chat.
- Da formato a los mensajes.
- 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.