Envía un mensaje con la API de Google Chat

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.

Llamar al método messages.create() con autenticación de app
Figura 1: Con la autenticación de la app, la app de Chat envía el mensaje. Para indicar que el remitente no es una persona, Chat muestra 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

Llamar al método messages.create() con autenticación de usuario
Figura 2: Con la autenticación del usuario, el usuario envía el mensaje y Chat muestra Nombre de la app de Chat junto al nombre del usuario.

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

  • Python 3.6 o superior
  • La herramienta de administración de paquetes pip
  • Las bibliotecas cliente de Google más recientes. 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-oauthlib

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

Mensaje enviado con la autenticación del usuario
Figura 3. Una app de Chat envía un mensaje de texto en nombre de un usuario.

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 el text .

De manera opcional, puedes incluir lo siguiente:

Para enviar un mensaje de texto en nombre de un usuario, sigue estos pasos:

Python

  1. En tu directorio de trabajo, crea un archivo llamado chat_create_message_user.py

  2. 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étodo spaces.list() o desde la URL del espacio.

  3. En tu directorio de trabajo, compila y ejecuta la muestra:

    python3 chat_create_message_user.py

  4. 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.

Mensaje enviado con la autenticación de la app
Figura 4: Una app de Chat envía un mensaje con texto, una tarjeta y un botón de accesorio.

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 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

  1. En tu directorio de trabajo, crea un archivo llamado chat_create_message_app.py

  2. 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étodo spaces.list() o desde la URL del espacio.

  3. 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
Figura 5: Un mensaje de la app de Chat con widgets de texto y accesorios.

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 el threadKey que creaste. De lo contrario, debes usar el name 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, pero custom-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.