Enviar un mensaje de tarjeta

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Además de los mensajes de texto, las apps de Chat pueden enviar mensajes de tarjetas en espacios y a usuarios. Las tarjetas admiten un diseño definido, elementos de IU interactivos, como botones, y rich media, como imágenes.

Usa mensajes de tarjetas para lo siguiente:

  • Presenta información detallada
  • Recopile información de los usuarios
  • Guía a los usuarios para dar el siguiente paso

En esta guía, se describe cómo enviar mensajes de tarjeta de forma síncrona (una respuesta en tiempo real a un evento de Chat, como recibir un mensaje de un usuario o que se agregue a un espacio) y de forma asíncrona (enviar un mensaje desde la app a un espacio o usuario sin un mensaje mediante la API de REST de Chat).

Requisitos previos

Para enviar los mensajes de tarjeta de esta guía, necesitas lo siguiente:

Node.js

Python

Apps Script

Anatomía de un mensaje de tarjeta

Cada tarjeta, ya sea un diálogo o un mensaje, es un objeto JSON en el recurso spaces.messages en la API de Chat.

El objeto JSON de la tarjeta consta de lo siguiente:

  1. Un arreglo llamado cardsV2[] que contiene uno o más objetos CardWithId.
  2. Un cardId, que se usa para identificar la tarjeta y el alcance de un mensaje determinado. (Las tarjetas en diferentes mensajes pueden tener el mismo ID).
  3. Un objeto card, que consta de lo siguiente:

    • Un objeto header que especifica elementos como un título, un subtítulo y una imagen al estilo de un avatar.
    • Uno o más objetos section, cada uno con al menos un widget.
    • Uno o más objetos widget Cada widget es un objeto compuesto que puede representar texto, imágenes, botones y otros tipos de objetos.

      Los siguientes widgets son compatibles con los mensajes de tarjeta y con los diálogos:

      • TextParagraph: Muestra un párrafo de texto con formato HTML opcional opcional.
      • Image: Muestra una imagen .PNG o .JPG en la que se puede hacer clic o estática, alojada en una URL HTTPS.
      • DecoratedText: Muestra texto con funciones de diseño y funcionalidad opcionales, como íconos y botones.
      • ButtonList: Muestra un conjunto de botones.

      Los siguientes widgets son compatibles con los diálogos (próximamente se admitirán los mensajes de tarjeta):

      • TextInput: campo en el que los usuarios pueden ingresar texto.
      • SelectionInput: Proporciona un conjunto de elementos seleccionables, como una lista de casillas de verificación, botones de selección, botones o un menú desplegable.

      • Divider: muestra una línea horizontal que abarca el ancho de una tarjeta entre widgets apilados y actúa como un divisor visual.

      • Grid: Ubica un conjunto de elementos en una cuadrícula simple.

      Pronto estará disponible la compatibilidad con el siguiente widget:

      • DateTimePicker: Permite que los usuarios especifiquen una fecha, una hora o ambas.

Como ejemplo, observa los objetos header, section y widget en el siguiente mensaje de tarjeta:

Una app de chat que ejecuta una encuesta en un espacio de Chat con un mensaje de tarjeta

El siguiente código representa el JSON del mensaje de la tarjeta:

JSON

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/chat/images/quickstart-app-avatar.png",
          "imageType": "CIRCLE",
          "imageAltText": "Avatar for Sasha",
        },
        "sections": [
          {
            "header": "Contact Info",
            "collapsible": true,
            "uncollapsibleWidgetsCount": 1,
            "widgets": [
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "EMAIL",
                  },
                  "text": "sasha@example.com",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "+1 (555) 555-1234",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Enviar un mensaje de tarjeta síncrono

En este ejemplo, un usuario envía un mensaje a la app de Chat en Google Chat y la app responde mediante un simple mensaje de tarjeta síncrona que muestra el nombre y la imagen del avatar del remitente:

App de chat que responde con una tarjeta que muestra el nombre visible y la imagen del avatar del remitente

En las siguientes muestras de código, las apps de Node.js y Python se alojan en Google Cloud Functions. El ejemplo de Apps Script se aloja en Google Apps Script.

Para obtener instrucciones completas sobre cómo compilar y, luego, implementar una aplicación de Chat, consulte Cómo compilar una aplicación de Chat.

Node.js

/**
  * 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.
  */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function must be called from Google Chat.');
  }

  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': imageURL},
  };

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

  return {
    'cards': [{
      'name': 'Avatar Card',
      'header': cardHeader,
      'sections': [avatarSection],
    }],
  };
}

Python

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):
  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 = {'cards': [{'name': 'Avatar Card',
                      'header': header, 'sections': [avatar_section]}]}

  return cards  

Apps Script

/**
* 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 {
        cards: [{
            name: 'Avatar Card',
            header: cardHeader,
            sections: [avatarSection]
        }]
    };
}

Envía un mensaje de tarjeta asíncrono con la API de Chat

En este ejemplo, se crea un mensaje de forma asíncrona con la API de Chat y se envía a un espacio al que se agrega la app de Chat, como se muestra a continuación:

Un mensaje de tarjeta creado con la API de REST de Chat.
Figura 1: Un mensaje de tarjeta creado con la API de REST de Chat.

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 httplib2 import Http
    from oauth2client.service_account import ServiceAccountCredentials
    from apiclient.discovery import build
    
    # Specify required scopes.
    SCOPES = ['https://www.googleapis.com/auth/chat.bot']
    
    # Specify service account details.
    CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
        'service_account.json', SCOPES)
    
    # Build the URI and authenticate with the service account.
    chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))
    
    # 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=
        {
          'cards_v2': [{
            'card_id': 'createCardMessage',
            'card': {
              'header': {
                'title': 'A Card Message!',
                'subtitle': 'Created with Chat REST 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 puedes obtener del método spaces.list() en la API de Chat o de la URL de un espacio.

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

    python3 chat_create_card_message.py
    

Para obtener más información sobre cómo trabajar con mensajes en la API de REST de Chat, consulte Cómo crear, leer, actualizar y borrar mensajes.

Abrir un diálogo

Los diálogos son interfaces basadas en tarjetas y basadas en ventanas que las apps de Chat abren para interactuar con los usuarios. Para ayudar a los usuarios a completar procesos de varios pasos, las apps pueden abrir diálogos secuenciales. Las apps pueden abrir diálogos en respuesta a un clic en un botón de un mensaje de tarjeta o en respuesta a un comando de barra.

Los diálogos son útiles para muchos tipos de interacciones del usuario, incluidas las siguientes:

  • Recopilar información de los usuarios
  • Autenticar usuarios con servicios web
  • Configura la app de Chat

En este ejemplo, una aplicación de chat abre un diálogo para ayudar al usuario a crear un nuevo contacto para su libreta de direcciones:

Un cuadro de diálogo con una variedad de widgets diferentes.

Para implementar diálogos, consulta Abrir diálogos.

Formato de las tarjetas

Formato del texto de la tarjeta

Dentro de las tarjetas, la mayoría de los campos de texto admiten el formato de texto básico a través de un pequeño subconjunto de etiquetas HTML. Las etiquetas admitidas y su propósito se muestran en la siguiente tabla:

Negrita <b> Cursiva <i>
Subrayado <>. Tachado <falta>
Color de fuente <font color=""> Hipervínculo <a href="">
Salto de línea <br>

Ten en cuenta que el cuerpo del texto de un mensaje básico se analiza mediante una sintaxis de lenguaje de marcado diferente que está optimizada para usuarios humanos. Para obtener más información, consulta Cómo enviar un mensaje de texto.

Íconos integrados

Los widgets DecoratedText y ButtonList admiten el elemento icon que se usa para especificar uno de los íconos integrados disponibles en Google Chat:

{ . . . "knownIcon": "TRAIN", . . . }

En la siguiente tabla, se enumeran los íconos integrados que están disponibles para los mensajes de tarjeta:

AVión MARCA DE LIBRO
BUS AUTO
RELOJ CONFIRMACIÓN_NUMBER_ICON
DESCRIPTION MONEDA
CORREO ELECTRÓNICO EVENT_SEAT
FLIGHT_ARRIVAL) FLIGHT_DEPARTURE
HOTEL HOTEL_ROOM_TYPE
INVITAR MAP_PIN
MEMBRESÍA MULTIPLE_PEOPLE
PERSONA TELÉFONO
RESTAURANT_ICON SHOPPING_CART
ESTRELLA ALMACENAMIENTO
BOLETO ENTRENAMIENTO
CÁMARA DE VIDEO VIDEO_PLAY

Íconos personalizados

Los widgets DecoratedText y ButtonList te permiten usar los íconos integrados que se mencionaron antes o definir tus propios íconos personalizados. Para especificar un ícono personalizado, usa el elemento iconUrl como se muestra a continuación:

{ . . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" . . }

Límites y consideraciones

Cuando te prepares para enviar mensajes de tarjeta, ten en cuenta estos límites y consideraciones.

  • Los siguientes widgets no son compatibles con los mensajes de tarjeta, pero pronto se admitirán:

    • TextInput, un campo en el que los usuarios pueden ingresar texto.
    • SelectionInput, que proporciona un conjunto de elementos seleccionables, como una lista de casillas de verificación, botones de selección, botones o un menú desplegable.
    • DateTimePicker, que permite a los usuarios especificar una fecha, una hora o ambas.
    • Grid, que establece un conjunto de elementos en una cuadrícula simple.