Cómo enviar un mensaje

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 recurso Message.
  • 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

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.

Apps Script

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:

Ejemplo de mensaje de integración.

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 de chat.messages.create.
  • Llama al Método create en la Recurso Message.

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

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

  2. 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)

  3. En el código, reemplaza SPACE por un nombre de espacio, que que puedes obtener de la Método spaces.list() en la API de Chat o desde la URL de un espacio.

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

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

  2. 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()

  3. En el código, reemplaza SPACE por un nombre de espacio, que que puedes obtener de la Método spaces.list() en desde la API de Chat o desde la URL de un espacio.

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

Una app de Chat responde con una tarjeta que muestra el nombre visible y el avatar del remitente imagen.

Node.js

node/avatar-app/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat room.
 *
 * @param {Object} req Request sent from Google Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Google Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-app/main.py
from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "text": "Here's your avatar",
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

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.

apps-script/avatar-app/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    text: 'Here\'s your avatar',
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

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 Recurso Message.

El siguiente es un ejemplo de un mensaje de tarjeta:

Un mensaje de tarjeta que se envía con la API de Chat

A continuación, te mostramos cómo enviar un mensaje de tarjeta con autenticación de app:

Python

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

  2. 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)

  3. En el código, reemplaza SPACE por un nombre de espacio, que que puedes obtener de la Método spaces.list en la API de Chat o desde la URL de un espacio.

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

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

  2. 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)

  3. En el código, reemplaza SPACE por un nombre de espacio, que que puedes obtener de la Método spaces.list en la API de Chat o desde la URL de un espacio.

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

A continuación, te indicamos cómo enviar un mensaje con un ID personalizado:

Python

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

  2. 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)

  3. 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étodo spaces.list en la API de Chat o desde la URL de un espacio.
    • NAME: Es el nombre personalizado del mensaje.

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

Ejemplos de widgets de accesorios

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.