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.
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.
App
junto a su nombre.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
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 las APIs de Google
- 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.
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. - La
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.
Para enviar un mensaje de texto en nombre de un usuario, sigue estos pasos:
Python
- En tu directorio de trabajo, crea un archivo llamado
chat_create_message_user.py
Incluye el siguiente código en
chat_create_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', # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstusermessage', # The text message to create. body={ 'text': '👋 🌎Hello world! Text messages can contain things like:\n\n' + '* Hyperlinks 🔗\n' + '* Emojis 😄🎉\n' + '* Mentions of other Chat users `@` \n\n' 'For details, see the <https://developers.google.com/workspace/chat/format-messages|Chat API developer documentation>.' } ).execute() # Prints details about the created message. print(result) if __name__ == '__main__': main()
Reemplaza
SPACE
por el ID del espacio.name
. Para obtener el ID, llama al Métodospaces.list()
o desde la URL del espacio.En tu directorio de trabajo, compila y ejecuta la muestra:
python3 chat_create_message_user.py
Si se te solicita una URL, ábrela para autorizar la URL. de Google Chat según el alcance que usaste para cada solicitud.
La app de Chat crea el mensaje y se autentica
el usuario publica el mensaje en el espacio. En tu interfaz de línea de comandos, la
La API de Chat muestra la instancia del nuevo
Message
recurso.
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. - La
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.
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.
Para 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. sigue estos pasos:
Python
- En tu directorio de trabajo, crea un archivo llamado
chat_create_message_app.py
Incluye el siguiente código en
chat_create_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) # Specify the Chat space where the message is posted. Obtain the ID # from the resource name, or from the space's URL. SPACE = 'spaces/SPACE' # Create a Chat message. result = chat.spaces().messages().create( # The Chat space. parent=SPACE, # Optional. Sets custom ID for the message to use in other requests. messageId='client-myfirstappmessage', # The message to create with text, a card, and a button at the # bottom of the message. body= { 'text': '👋 🌎Hello world! I created this message by calling the Chat API\'s `messages.create()` method.', 'cardsV2': [{ 'cardId': 'myCardId', 'card': { 'header': { 'title': 'About this message', 'imageUrl': 'https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/info/default/24px.svg', 'imageType': 'CIRCLE' }, "sections": [ { "header": "Contents", "widgets": [ { "textParagraph": { "text": "🔡 <b>Text</b> which can include hyperlinks 🔗, emojis 😄🎉, and @mentions 🗣️." }}, { "textParagraph": { "text": "🖼️ A <b>card</b> to display visual elements and request information such as text 🔤, dates and times 📅, and selections ☑️." }}, { "textParagraph": { "text": "👉🔘 An <b>accessory widget</b> which adds a button to the bottom of a message." }}, ] }, { "header": "What's next", "collapsible": True, "widgets": [ { "textParagraph": { "text": "❤️ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.reactions/create'>Add a reaction</a>." }}, { "textParagraph": { "text": "🔄 <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/patch'>Update</a> or ❌ <a href='https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/delete'>delete</a> the message." }}, { "textParagraph": { "text": '💡 <b>Pro tip</b>: To specify the message in other API requests, use its custom name: <i>' + SPACE + '/messages/client-myfirstappmessage</i>.' }} ] } ]} }], "accessoryWidgets": [ { "buttonList": { "buttons": [ { "text": "View documentation", "altText": "Opens a new browser tab and navigates to the Google Chat developer documentation website.", "icon": { "material_icon": { "name": "link" } }, "onClick": { "openLink": { "url": "https://developers.google.com/workspace/chat/create-messages" } } } ] } } ] } ).execute() print(result)
Reemplaza
SPACE
por el ID del espacio.name
. Para obtener el ID, llama al Métodospaces.list()
o desde la URL del espacio.En tu directorio de trabajo, compila y ejecuta la muestra:
python3 chat_create_message_app.py
La app de Chat crea y publica el mensaje en la
espacio. En tu interfaz de línea de comandos, la API de Chat
instancia de la nueva
Message
recurso.
Cómo agregar widgets interactivos en la parte inferior de un mensaje
En la muestra de código de la sección anterior, 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.
![Widget de accesorio](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/message-accessory-widgets-reference.png?authuser=3&hl=es-419)
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"
}
}
Reemplazar 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:
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 lo estableces, puedes especifica elthreadKey
que creaste. De lo contrario, debes usar elname
del subproceso. - Especifica el parámetro de consulta
messageReplyOption
.
El siguiente JSON muestra un ejemplo del cuerpo de la solicitud de un mensaje de texto que
inicia un subproceso con la clave helloWorldThread
o responde a uno:
{
'thread': {
'threadKey': 'helloWorldThread',
},
'text': '👋 🌎Hello world!'
}
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 la 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.
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.