Enviar mensagens do Google Chat

Esta página explica como os apps do Google Chat podem enviar mensagens para responder às interações do usuário.

No Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Para saber mais, consulte a Visão geral do Extend Google Chat.

  • Formulário de contato do comando de barra.
    Figura 1. Um app de chat responde a um comando de barra com uma mensagem de texto e um botão.
  • Formulário de contato em uma caixa de diálogo.
    Figura 2. Um app de chat abre uma caixa de diálogo em que os usuários podem inserir informações.
  • Mensagem de card com widgets de entrada de formulário.
    Figura 5. Um app de chat envia uma mensagem com texto e um card interativo.

Pré-requisitos

Node.js

Um complemento do Google Workspace que estende o Google Chat. Para criar um, conclua o Guia de início rápido do HTTP.

Apps Script

Um complemento do Google Workspace que estende o Google Chat. Para criar um, conclua o Guia de início rápido do Apps Script.

Criar a mensagem

Os apps de chat podem incluir qualquer um dos seguintes itens em uma mensagem:

  • Texto com hiperlinks, menções (@) e emojis.
  • Um ou mais cards, que podem aparecer em uma mensagem ou abrir em uma nova janela como uma caixa de diálogo.
  • Um ou mais widgets acessórios, que são botões que aparecem após qualquer texto ou cartão em uma mensagem.

Para saber como projetar mensagens, consulte a seguinte documentação da API Google Chat:

Enviar uma mensagem

Os apps de chat podem responder com uma mensagem a qualquer um dos seguintes acionadores ou interações:

  • Acionadores de mensagem, como quando os usuários @mencionam ou enviam uma mensagem direta a um app do Chat.
  • Gatilhos adicionados ao espaço, como quando os usuários instalam o app Chat do Google Workspace Marketplace ou o adicionam a um espaço.
  • Cliques em botões de cards em mensagens ou caixas de diálogo. Por exemplo, quando os usuários digitam informações e clicam em "Enviar".

Caso contrário, os apps de chat podem enviar mensagens de forma proativa chamando a API Google Chat.

Para responder com uma mensagem, retorne a ação DataActions com um objeto CreateMessageAction:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
  "message": MESSAGE
}}}

Substitua MESSAGE por um recurso Message da API Chat. Para saber mais sobre como as ações funcionam, consulte Ações no Chat.

No exemplo abaixo, um app de chat cria e envia uma mensagem de texto sempre que é adicionado a um espaço. Para enviar uma mensagem de texto quando um usuário adiciona o app do Chat a um espaço, o app do Chat responde ao acionador Adicionado ao espaço retornando a ação DataActions:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Workspace Add-on.
 * @param {Object} res The response object from the Chat app. An onboarding message that
 *                     introduces the app and helps people get started with it.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      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 onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    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`.'
  }}}}};
}

O exemplo de código retorna a seguinte mensagem de texto:

Exemplo de mensagem de integração.

Para mais exemplos de como responder com uma mensagem, consulte estes guias:

Atualizar uma mensagem

Os apps de chat também podem atualizar as mensagens que enviam. Por exemplo, para atualizar uma mensagem depois que um usuário enviou uma caixa de diálogo ou clicou em um botão em uma mensagem.

Para atualizar uma mensagem do app Chat, retorne a ação DataActions com um UpdateMessageAction, conforme mostrado neste exemplo:

{ "hostAppDataAction": { "chatDataAction": { "updateMessageAction": {
  "message": MESSAGE
}}}}

Substitua MESSAGE por um recurso Message da API Chat.

Para saber mais sobre como as ações funcionam, consulte Ações no Chat.

Os apps de chat também podem atualizar uma mensagem de um usuário para retornar uma visualização de um link que ele enviou. Saiba mais em Visualizar links em mensagens do Google Chat.

Responder a interações ou enviar mensagens proativas usando a API Google Chat

Em vez de retornar uma ação de complemento, os apps de chat talvez precisem usar a API Google Chat para responder a uma interação. Por exemplo, os apps de chat precisam chamar a API Google Chat para fazer o seguinte:

  • Enviar mensagens em uma programação ou sobre mudanças em recursos externos. Por exemplo, notificações sobre um novo problema ou caso.
  • Responder mais de 30 segundos após a interação. Por exemplo, para responder com uma mensagem após concluir uma tarefa de longa duração.
  • Enviar uma mensagem fora do espaço em que a interação ocorreu.
  • Enviar uma mensagem em nome de um usuário do Chat.

Para enviar uma mensagem usando a API Chat, você precisa configurar a autenticação e chamar o método create() no recurso Message. Para conferir as etapas, consulte Enviar uma mensagem usando a API Google Chat.