Envie uma mensagem com o cartão

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Além de mensagens de texto, os apps de chat podem enviar mensagens de card em espaços e para os usuários. Os cards são compatíveis com um layout definido, 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 darem um próximo passo

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

Python

Apps Script

Anatomia de uma mensagem do card

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. Uma cardId, usada para identificar o cartão e o escopo de uma determinada mensagem. Os cards 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 em estilo avatar.
    • Um ou mais objetos section, cada um com 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 são compatíveis com mensagens de card e caixas de diálogo:

      • TextParagraph: mostra um parágrafo de texto com formatação HTML simples opcional.
      • Image: exibe 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 com caixas de diálogo (em breve, mensagens para cartões):

      • 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, chaves ou um menu suspenso.

      • Divider: exibe uma linha horizontal que atravessa a largura de um cartão entre widgets empilhados, atuando como um divisor visual.

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

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

      • DateTimePicker: permite que os usuários especifiquem uma data, um horário ou ambos.

Por exemplo, observe os objetos header, section e widget na seguinte mensagem do card:

Um app de chat executando uma enquete em um espaço do Chat usando 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íncrono

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

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

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 completas sobre como criar e implantar um app de chat em Criar um app 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]
        }]
    };
}

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 de chat é adicionado, como o mostrado abaixo:

Uma mensagem de card criada com a API REST do Chat.
Figura 1: uma mensagem de 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=
        {
          '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. No código, substitua SPACE por um nome de espaço, que pode ser obtido no método spaces.list() na API Chat ou no URL de um espaço.

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

    python3 chat_create_card_message.py
    

Para saber mais sobre como trabalhar com mensagens na API REST do Chat, consulte Criar, ler, atualizar e excluir mensagens.

Abrir uma caixa de diálogo

As caixas de diálogo são interfaces baseadas em janelas em janelas que os apps de chat abrem para interagir com os usuários. Para ajudar os usuários a concluir processos em 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 card ou em resposta a um comando de barra.

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

  • Coleta de informações dos usuários
  • Como autenticar usuários com serviços da Web
  • Ajuste das 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 a agenda 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

Nos cards, a maioria dos campos de texto é compatível com a formatação básica de texto por meio de 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": "TREINAR", . . . }

A tabela a seguir lista os ícones integrados disponíveis para mensagens de cartão:

PLANO AÉREO MARCA EM Livro
Ônibus CAR
RELÓGIO CONFIRMATION_NUMBER_ICON
DESCRIÇÃO MOEDA
E-MAIL EVENTO_SEAT
Voo_Entrada Voo_DE_OUTRO
HOTÉIS HOTEL_ROOM_TYPE
CONVITE PIN_PIN
ASSINATURA MULTIPLE_ pessoas
PESSOA TELEFONE
RESTAURANT_ICON (link em inglês) SHOPPING_CART (em inglês)
ESTRELA LOJA
FILMAGEM TREINAMENTO
VIDEO_CAMERA (em inglês) VIDEO_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

Quando você se preparar para enviar mensagens do cartão, anote esses limites e considerações.

  • Os seguintes widgets não são compatíveis com as mensagens do cartão, mas o suporte será 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, chaves ou um menu suspenso.
    • DateTimePicker, que permite aos usuários especificar uma data, hora ou ambos.
    • Grid, que exibe um conjunto de itens em uma grade simples.