Cómo crear un mensaje de tarjeta

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

Usa mensajes de tarjetas para hacer lo siguiente:

  • Presenta información detallada
  • Recopilar información de los usuarios
  • Guía a los usuarios para que realicen el siguiente paso

En esta guía, se describe cómo crear mensajes de tarjetas de forma síncrona (una respuesta en tiempo real a un evento de Google 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 a un usuario sin un mensaje mediante la API de Google Chat).

Requisitos previos

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

Node.js

Nota: Las muestras de código de Node.js de esta guía se escriben para ejecutarse como una función de Google Cloud Functions.

Python

Nota: Las muestras de código de Python de esta guía se escriben para ejecutarse como una Google Cloud Function con Python 3.9.

Apps Script

Anatomía del mensaje de una tarjeta

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

El objeto JSON de la tarjeta consta de lo siguiente:

  1. Es un array llamado cardsV2[] que contiene uno o más objetos CardWithId.
  2. Una cardId, que se usa para identificar la tarjeta y su alcance dentro de un mensaje determinado. (Las tarjetas en mensajes diferentes pueden tener el mismo ID).

  3. Un objeto card, que consta de lo siguiente:

    • Un objeto header que especifica títulos, como un subtítulo y una imagen de estilo avatar
    • Uno o más objetos section que contengan 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.

A modo de 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",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Cómo crear un mensaje de tarjeta síncrono

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

Una app de chat que responde con una tarjeta que muestra el nombre visible y la imagen de 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 app de chat, consulta Cómo compilar una app de chat.

Node.js

node/avatar-bot/index.js.
/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts 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 Hangouts 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 {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-bot/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 = {
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

Apps Script

apps-script/avatar-bot/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 {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Crea un mensaje asíncrono de las tarjetas con la API de Chat

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

Un mensaje de tarjeta creado con la API de Google Chat.
Figura 1: Un mensaje de tarjeta creado con la API 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=
    {
      'cardsV2': [{
        'cardId': '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

Si quieres obtener más información para trabajar con mensajes en la API de Chat, consulta los siguientes vínculos:

Abrir un diálogo

Los diálogos son interfaces basadas en tarjetas y con 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 en un mensaje de tarjeta o en respuesta a un comando de barra.

Los diálogos son útiles para muchos tipos de interacciones del usuario, entre las que se incluyen las siguientes:

  • Recopilación de información de los usuarios
  • Autentica usuarios con servicios web
  • Configura la app de Chat

En este ejemplo, una app de chat abre un diálogo con el fin de ayudar a un usuario a crear un contacto nuevo para su libreta de direcciones:

Un diálogo con una variedad de widgets diferentes.

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

Formato de las tarjetas

Existen varias formas de darle formato a la apariencia de las tarjetas.

Formato de texto para tarjetas

Dentro de las tarjetas, la mayoría de los campos de texto admiten el formato de texto básico mediante un pequeño subconjunto de etiquetas HTML.

En la siguiente tabla, se muestran las etiquetas compatibles y su propósito:

Formato Ejemplo Resultado renderizado
Negrita "This is <b>bold</b>." Este texto es negrita.
Cursiva "This is <i>italics</i>." Se trata de cursiva.
Subrayado "This is <u>underline</u>." Esto es subrayado.
Tachado "This is <s>strikethrough</s>." Esto es tachado.
Color de fuente "This is <font color=\"#FF0000\">red font</text>." Esta es la fuente roja.
Hipervínculo "This is a <a href=\"https://www.google.com\">hyperlink</a>." Este es un hipervínculo.
Tiempo "This is a time format: <time>2023-02-16 15:00</time>." Este es un formato de hora: .
Nueva línea "This is the first line. <br> This is a new line." Esta es la primera línea.
Esta es una línea nueva.

Ten en cuenta que el cuerpo del texto de un mensaje básico se analiza con una sintaxis de lenguaje de marcado diferente que está optimizada para usuarios humanos. Para obtener más información, consulta Cómo crear 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 MARCADOR DE MARCADOR
Autobús AUTO
RELOJ CONFIRMACIÓN_NUMBER_ICON
DESCRIPTION MONEDA
CORREO ELECTRÓNICO ASENO_EVENTO
Vuelo_VALOR Vuelo_DE
HOTEL HOTEL_ROOM_TYPE
INVITACIÓN MAP_PIN
MEMBRESÍA MULTIPLE_PEOPLE
PERSONA TELÉFONO
RESTAURANT_ICON SHOPPING_CART
STAR TIENDA
BOLETO ENTRENAMIENTO
CÁMARA DE VIDEO VIDEO_PLAY

Íconos personalizados

Los widgets de DecoratedText y ButtonList te permiten usar los íconos integrados 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" . . . }