Envie uma mensagem com o cartão

Além de mensagens de texto, os apps de chat podem enviar mensagens de card em espaços e usuários. Os cards oferecem suporte a layouts definidos, elementos interativos da IU, como botões, e rich media, como imagens.

Use as mensagens do cartão para:

  • Apresentar informações detalhadas
  • Coletar informações dos usuários
  • Oriente os usuários a seguir para uma próxima etapa

Este guia descreve como enviar mensagens de cartão de forma síncrona (uma resposta em tempo real para um evento do Chat, como receber uma mensagem de um usuário ou ser adicionada a um espaço) e de forma assíncrona (enviar uma mensagem do app para um espaço ou usuário sem uma solicitação usando a API REST do Chat).

Pré-requisitos

Para enviar as mensagens do cartão neste guia, você precisa do seguinte:

Node.js

Observação: as amostras de código Node.js neste guia foram escritas para serem executadas como uma função do Google Cloud.

Python

Observação: as amostras de código Python neste guia são escritas para serem executadas como uma função do Google Cloud usando o Python 3.9.

Apps Script

Anatomia da mensagem de um cartão

Cada card, seja uma caixa de diálogo ou uma mensagem, é um objeto JSON no recurso spaces.messages na API Chat.

O objeto JSON do cartão consiste no seguinte:

  1. Uma matriz chamada cardsV2[], que contém um ou mais objetos CardWithId.
  2. Um cardId, usado para identificar o cartão e o escopo de uma determinada mensagem. Os cartões em mensagens diferentes podem ter o mesmo ID.

  3. Um objeto card, que consiste no seguinte:

    • Um objeto header que especifica itens como título, subtítulo e imagem no estilo avatar.
    • Um ou mais objetos section, cada um contendo pelo menos um widget.

    • Um ou mais objetos widget Cada widget é um objeto composto que pode representar textos, imagens, botões e outros tipos de objetos.

      Os seguintes widgets têm suporte em mensagens e caixas de diálogo de cards:

      • TextParagraph: exibe um parágrafo de texto com a formatação HTML simples opcional.
      • Image: mostra uma imagem .PNG ou .JPG clicável ou estática hospedada em um URL HTTPS.
      • DecoratedText: mostra texto com recursos opcionais de layout e funcionalidade, como ícones e botões.
      • ButtonList: mostra um conjunto de botões.

      Os seguintes widgets são compatíveis em caixas de diálogo (em breve, mensagens no cartão serão aceitas):

      • TextInput: campo em que os usuários podem inserir texto.

      • SelectionInput: mostra um conjunto de itens selecionáveis, como uma lista de caixas de seleção, botões de opção, interruptores ou um menu suspenso.

      • Divider: mostra uma linha horizontal que abrange a largura de um card entre widgets empilhados, agindo como um divisor visual.

      • Grid: mostra um conjunto de itens em uma grade simples.

      O suporte para o seguinte widget será disponibilizado em breve:

Por exemplo, observe os objetos header, section e widget na seguinte mensagem do cartão:

Um app de chat executando uma enquete em um espaço do Chat com uma mensagem de card

O código a seguir representa o JSON da mensagem do cartão:

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 uma mensagem de cartão síncrona

Neste exemplo, um usuário envia uma mensagem no app de chat, e o app responde com uma mensagem simples de cartão síncrono que mostra o nome do remetente e a imagem do avatar:

App de chat respondendo com um card com o nome de exibição do remetente e a imagem do avatar

Nas amostras de código a seguir, os apps Node.js e Python são hospedados no Google Cloud Functions. O exemplo do Apps Script está hospedado no Google Apps Script.

Veja instruções sobre como criar e implantar um app de chat em Criar um 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):
    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],
      }
    }],
  };
}

Enviar uma mensagem de cartão assíncrona com a API Chat

Este exemplo cria uma mensagem de forma assíncrona com a API Chat e a envia para um espaço ao qual o app Chat é adicionado, como mostrado abaixo:

Uma mensagem de cartão criada com a API REST do Chat.
Figura 1: uma mensagem do card criada com a API REST do Chat.

Python

  1. No diretório de trabalho, crie um arquivo chamado chat_create_card_message.py.

  2. Inclua o seguinte código em 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. No código, substitua SPACE por um nome de espaço, que pode ser acessado no método spaces.list() na API Chat ou no URL de um espaço.

  4. No diretório de trabalho, crie e execute o exemplo:

    python3 chat_create_card_message.py

Saiba mais sobre como trabalhar com mensagens na API REST do Chat em Criar, ler, atualizar e excluir mensagens.

Abrir uma caixa de diálogo

As caixas de diálogo são interfaces baseadas em janelas que os apps de chat abrem para interagir com os usuários. Para ajudar os usuários a realizar processos de várias etapas, os apps podem abrir caixas de diálogo sequenciais. Os apps podem abrir caixas de diálogo em resposta a um clique no botão em uma mensagem de cartão ou em resposta a um comando de barra.

As caixas de diálogo são úteis para muitos tipos de interação do usuário, incluindo:

  • Coleta de informações dos usuários
  • Como autenticar usuários com serviços da Web
  • Definir as configurações do app Chat

Neste exemplo, um app de chat abre uma caixa de diálogo para ajudar um usuário a criar um novo contato para o catálogo de endereços:

Uma caixa de diálogo com vários widgets diferentes.

Para implementar caixas de diálogo, consulte Abrir caixas de diálogo.

Formatação de cards

Formatação de texto dos cards

Dentro dos cards, a maioria dos campos de texto é compatível com a formatação básica de texto usando um pequeno subconjunto de tags HTML. As tags compatíveis e a finalidade delas são mostradas na tabela abaixo:

Negrito <b> Itálico <i>
Sublinhado <> Tachado <aviso>
Cor da fonte <font color=""> Hiperlink <a href="">
Quebra de linha <br>

O corpo do texto de uma mensagem básica é analisado com uma sintaxe de marcação diferente, otimizada para usuários humanos. Veja mais detalhes em Enviar uma mensagem de texto.

Ícones integrados

Os widgets DecoratedText e ButtonList são compatíveis com o elemento icon usado para especificar um dos ícones integrados disponíveis no Google Chat:

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

A tabela a seguir lista os ícones integrados disponíveis para mensagens de card:

PLANO DE AR MARCADORES
Ônibus CARRO
RELÓGIO CONFIRMATION_NUMBER_ICON (em inglês)
DESCRIÇÃO MOEDA
E-MAIL EVENTO_DE_EVENTO
Voo de chegada VOLTAR_DE_VOZ
HOTEL HOTEL_ROOM_TYPE
CONVITE MAP_PIN (em inglês)
ASSINATURA MULTIPLE_Pessoas
PESSOA TELEFONE
RESTAURANT_ÍCONE SHOPPING_CART (em inglês)
ESTRELA LOJA
INGRESSO TREINAR
VIDEO_CAMERA (em inglês) VÍDEO_PLAY

Ícones personalizados

Os widgets DecoratedText e ButtonList permitem usar os ícones integrados listados acima ou definir seus próprios ícones personalizados. Para especificar um ícone personalizado, use o elemento iconUrl, conforme mostrado aqui:

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

Limites e considerações

Ao se preparar para enviar mensagens de cartão, considere esses limites e considerações.

  • Os widgets a seguir não são compatíveis com mensagens de cartão, mas vão estar disponíveis em breve:

    • TextInput, um campo em que os usuários podem inserir texto.
    • SelectionInput, que fornece um conjunto de itens selecionáveis, como uma lista de caixas de seleção, botões de opção, interruptores ou um menu suspenso.
    • DateTimePicker, que permite aos usuários especificar uma data, hora ou ambos.
    • Grid, que mostra um conjunto de itens em uma grade simples.