Receber e responder a interações do usuário

Nesta página, descrevemos como seu app do Google Chat pode receber e responder às interações dos usuários no Google Chat.

Para criar interfaces interativas para apps de chat, use os seguintes componentes:

• Gatilhos: as maneiras como os usuários do Google Chat podem invocar um app do Chat, como adicionar a um espaço ou enviar uma mensagem.
• Objetos de evento: os dados que os apps de chat recebem de acionadores ou interações da interface.
• Ações: as maneiras como os apps de chat podem responder a interações, como enviar mensagens ou retornar uma interface do usuário baseada em cards.

Os apps de chat podem criar e mostrar interfaces das seguintes maneiras:

• Mensagens que podem conter texto, cards estáticos ou interativos e botões de acessórios.
• Páginas iniciais (página inicial do app) que aparecem na guia Início das mensagens diretas individuais com o app Chat.
• Caixas de diálogo, que são cards abertos em uma nova janela e geralmente pedem que os usuários enviem informações.
• Prévia de links, que são cards que mostram informações sobre um serviço externo.

Pré-requisitos

• Uma conta do Google Workspace Business ou Enterprise com acesso ao Google Chat.
• Crie um projeto do Google Cloud.
• Configure a tela de permissão OAuth.
• Ative e configure a API Google Chat.

Como funcionam as interações do usuário

Quando um usuário interage com um app do Chat, o Google Chat invoca um gatilho configurado e envia um objeto de evento ao endpoint ou função do app do Chat. O app Chat processa o objeto de evento e pode retornar uma ação de forma síncrona em até 30 segundos ou responder de forma assíncrona usando a API do Chat.

O diagrama a seguir demonstra como os apps do Google Chat processam e respondem às interações do usuário:

Gatilhos

Os gatilhos são as maneiras específicas que os usuários invocam um app do Chat usando a interface do Chat, como @menções ou comandos de apps.

A tabela a seguir mostra os gatilhos do Chat, uma descrição e como os apps do Chat normalmente respondem:

Configure os endpoints ou as funções de callback desses gatilhos no console do Google Cloud, na página Configuração da API Chat. Para instruções detalhadas, consulte Configurar a API Google Chat.

Configurar comandos iniciais

Os comandos iniciais ajudam os usuários a descobrir a funcionalidade do seu app Chat quando eles abrem uma mensagem direta individual vazia com o app. É possível configurar até três comandos iniciais.

Para adicionar e configurar comandos de ativação:

1. No console do Google Cloud, acesse a página Configuração da API Chat:

   Acessar a página de configuração da API Chat

2. Em Recursos interativos, encontre Comandos iniciais e clique em Adicionar um comando.

3. No campo Classificação (1 a 3), insira um número de 1 a 3 para especificar a ordem de exibição.

4. Em Seleção de tipo, escolha como o comando vai se comportar:

   • Comando de texto: preenche a barra de criação com texto predefinido quando o usuário clica no ícone de comando.
   • Prompt de comando: executa um comando de barra ou rápido registrado quando clicado. Não é possível selecionar comandos que exigem argumentos adicionais.

5. Configure o comando com base na sua seleção de tipo:

   • Se você selecionou "Comando de texto":

     1. Em Título, insira o título do comando exibido no ícone (até 30 caracteres).
     2. Em Texto do comando, insira o texto preenchido na barra de escrita (até 60 caracteres).
     3. Opcional: adicione títulos e textos localizados para usuários em outros idiomas:
     4. Em Comandos localizados, clique em Adicionar um idioma.
     5. Em Idioma, selecione uma opção no menu suspenso.
     6. Em Título localizado, insira o título localizado (até 30 caracteres).
     7. Em Texto do comando localizado, insira o texto do comando localizado (até 60 caracteres).
     8. Repita para adicionar mais idiomas conforme necessário.

   • Se você selecionou "Prompt de comando":

     1. Em Comando de barra / Comando rápido, selecione o comando no menu suspenso.

6. Clique em Concluído e depois em Salvar na parte de baixo da página.

Processar novas tentativas de chamadas HTTP para seu serviço

Se uma solicitação HTTPS para seu serviço falhar (como um tempo limite, uma falha temporária de rede ou um código de status HTTPS não 2xx), o Google Chat poderá tentar fazer a entrega algumas vezes em alguns minutos, mas isso não é garantido. Como resultado, um app de chat pode receber o mesmo evento algumas vezes em determinadas situações. Se a solicitação for concluída, mas retornar uma carga útil de resposta inválida, o Google Chat não vai tentar de novo.

Objetos de evento

Os apps de chat recebem objetos de evento quando um acionador do Chat é executado ou quando os usuários do Chat interagem com uma interface do app (por exemplo, clicando em um botão ou enviando uma caixa de diálogo). O objeto de evento permite usar dados de interação para responder ou atualizar uma interface.

Payloads de objetos de evento

Cada objeto de evento do Chat inclui um commonEventObject com detalhes do host e da plataforma (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters e formInputs) e um objeto chat que contém contexto específico do Chat:

• Para um gatilho de página inicial do app (quando um usuário abre a guia Início em uma mensagem direta individual com o app Chat), o objeto chat contém chat.user e chat.eventTime sem um campo de união payload. Quando um usuário clica em um botão no card da página inicial, o objeto de evento inclui chat.buttonClickedPayload junto com commonEventObject.parameters (e commonEventObject.formInputs se o card tiver entradas de formulário).
• Para interações de espaço e mensagem (Adicionado ao espaço, Mensagem, Removido do espaço, Comando do app ou interações de botão e widget), o objeto chat inclui chat.user, chat.space, chat.eventTime e o payload de interação correspondente:
  • messagePayload: contém o space, message e configCompleteRedirectUri quando um usuário envia uma mensagem.
  • addedToSpacePayload: contém space, interactionAdd e configCompleteRedirectUri quando o app do Chat é adicionado a um espaço.
  • removedFromSpacePayload: contém o space quando o app do Chat é removido de um espaço.
  • buttonClickedPayload: contém space, message, isDialogEvent e dialogEventType quando um usuário clica em um botão em um card ou caixa de diálogo.
  • widgetUpdatedPayload: contém o space quando um usuário interage com um widget, como digitar em um menu de seleção múltipla com uma fonte de dados externa.
  • appCommandPayload: contém space, message, appCommandMetadata, isDialogEvent, dialogEventType e configCompleteRedirectUri quando um usuário invoca um comando de app.

Para saber mais sobre objetos de evento de complementos no Chat e em outros aplicativos do Google Workspace, consulte Objetos de evento.

Entregar uma resposta

Esta seção explica como os apps do Chat usam ações para responder de forma síncrona às interações do usuário.

Para responder com uma ação, um app do Chat precisa responder em até 30 segundos, e a resposta precisa ser aplicada ao espaço em que a interação ocorreu. Essas respostas síncronas não exigem autenticação. Se o app do Chat precisar de mais de 30 segundos ou agir fora do espaço, configure a autenticação e responda de forma assíncrona usando a API Google Chat.

Para responder às interações do usuário de forma síncrona, seu app de chat processa o objeto de evento recebido e retorna um dos seguintes objetos JSON:

• DataActions: cria ou atualiza mensagens de chat (CreateMessageAction, UpdateMessageAction) ou anexa prévias de link (UpdateInlinePreviewAction) usando chatDataActionMarkup.
• RenderActions: cria, atualiza ou fecha uma página inicial ou caixa de diálogo (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") ou fornece sugestões de entrada dinâmicas para um menu de seleção múltipla (modifyCard).
• AuthorizationError: solicita que os usuários façam login ou se autentiquem em um serviço externo com um cartão de autorização básico (basic_authorization_prompt).

A tabela a seguir mostra como os apps do Chat podem responder com ações. Os apps do Chat podem retornar objetos JSON diretamente ou criar a resposta usando AddOnResponseService e CardService do Apps Script.

Enviar uma mensagem

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

• Gatilhos demensagens, como quando os usuários mencionam com @ou enviam mensagens diretas para um app do Chat.
• Acionadores de "Adicionado ao espaço", como quando os usuários instalam o app Chat no Google Workspace Marketplace ou o adicionam a um espaço.
• Comandos de app acionam, por exemplo, quando os usuários invocam um comando de barra ou um comando rápido.
• Cliques em botões de cards em mensagens ou caixas de diálogo. Por exemplo, quando os usuários inserem informações e clicam em "Enviar".

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

• Texto que contém hiperlinks, @menções e emojis. Consulte Formatar mensagens.
• Um ou mais cards, que podem aparecer em uma mensagem ou abrir em uma nova janela como uma caixa de diálogo. Consulte Criar cards para apps do Google Chat.
• Um ou mais widgets de acessórios, que são botões que aparecem depois de qualquer texto ou cards em uma mensagem.

Para responder com uma mensagem, retorne DataActions com um objeto CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Substitua MESSAGE por um recurso Message da API Chat.

No exemplo a seguir, um app do Chat cria e envia uma mensagem de texto de integração sempre que é adicionado a um espaço respondendo ao gatilho Adicionado ao espaço com DataActions:

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
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`.'
    }}}}});
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "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`.'
      }}
    }}})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "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`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
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:

Atualizar uma mensagem

Os apps de chat também podem atualizar as mensagens enviadas. Por exemplo, um app do Chat pode atualizar uma mensagem depois que um usuário envia uma caixa de diálogo ou clica em um botão em um card em uma mensagem.

Para atualizar uma mensagem do app do Chat em resposta a uma interação, retorne DataActions com um UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Substitua MESSAGE por um recurso Message da API Chat.

Os apps do Chat também podem atualizar uma mensagem enviada por um usuário para anexar um card de prévia de link usando updateInlinePreviewAction. Para mais detalhes, consulte Links de visualização.

Responder de forma assíncrona usando a API Google Chat

Em vez de retornar uma ação de forma síncrona, os apps do Chat podem precisar chamar a API Google Chat para responder a uma interação ou enviar mensagens proativas. Por exemplo, os apps do Chat precisam chamar a API Google Chat para fazer o seguinte:

• Responder a uma interação após 30 segundos (por exemplo, depois de concluir uma tarefa de longa duração).
• Enviar mensagens em uma programação ou notificações sobre mudanças em recursos externos.
• Realizar tarefas fora do espaço em que a interação ocorreu.
• Realizar tarefas no Chat que não estão disponíveis como ações síncronas, como listar espaços ou adicionar participantes a um espaço.
• Realizar tarefas em nome de um usuário do Chat (o que exige autenticação do usuário).

Ao responder a uma interação após 30 segundos, para evitar uma mensagem de erro voltada ao usuário informando que o app Chat não está respondendo, você precisa confirmar o recebimento do objeto de evento em até 30 segundos retornando uma resposta vazia:

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Para enviar uma mensagem usando a API Chat, configure a autenticação e chame o método spaces.messages.create. Para ver as etapas, consulte Enviar uma mensagem. Para guias sobre como usar outros métodos da API Chat, consulte a visão geral da API Chat.

Temas relacionados

• Configurar a API Google Chat
• Enviar uma mensagem
• Responder a comandos
• Abrir caixas de diálogo interativas
• Ler dados de formulários inseridos pelos usuários em cards
• Links de prévia
• Criar uma página inicial para um app do Chat
• Verificar solicitações do Chat
• Testar recursos interativos para apps do Google Chat

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      '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`.'
    });
  }
};

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      '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`.'
    })
  return json.jsonify({})

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "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`.");
      default:
        return new Message();
    }
  }
}

/**
 * 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.
 */
function onAddToSpace(event) {
  return {
    '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`.'
  };
}