Receber e responder a eventos de interação

Nesta página, descrevemos como seu app Google Chat pode receber e responder a interações do usuário, também conhecidas como eventos de interação do app Google Chat.

Esta página explica como fazer o seguinte:

• Configure seu app do Chat para receber eventos de interação.
• Processe o evento de interação na sua infraestrutura.
• Se for o caso, responda aos eventos de interação.

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 a API Google Chat.

Tipos de eventos de interação

Um evento de interação com um app do Google Chat representa qualquer ação que um usuário realiza para invocar ou interagir com um app do Chat, como @mencionar ou adicionar a um espaço.

Quando os usuários interagem com um app do Chat, o Google Chat envia ao app um evento de interação, representado como um tipo Event na API Chat. O app do Chat pode usar o evento para processar a interação e, opcionalmente, responder com uma mensagem.

Para cada tipo de interação do usuário, o Google Chat envia um tipo diferente de evento de interação, o que ajuda seu app Chat a processar cada tipo de evento de acordo com a situação. O tipo de evento de interação é representado usando o objeto eventType.

Por exemplo, o Google Chat usa o tipo de evento ADDED_TO_SPACE para qualquer interação em que um usuário adiciona o app Chat a um espaço. Assim, o app pode responder imediatamente com uma mensagem de boas-vindas no espaço.

A tabela a seguir mostra as interações comuns do usuário, o tipo de evento de interação que os apps do Chat recebem e como eles geralmente respondem:

Para conferir todos os eventos de interação compatíveis, consulte a documentação de referência do EventType.

Eventos de interação de caixas de diálogo

Se o app do Chat abrir caixas de diálogo, o evento de interação vai conter as seguintes informações adicionais que podem ser usadas para processar uma resposta:

• O elemento isDialogEvent é definido como true.
• O DialogEventType esclarece se a interação aciona a abertura, o envio de informações ou o fechamento de uma caixa de diálogo.

A tabela a seguir mostra as interações comuns com caixas de diálogo, os tipos de eventos de caixa de diálogo correspondentes e uma descrição de como os apps do Chat geralmente respondem:

Para mais informações, consulte Abrir caixas de diálogo interativas.

Receber eventos de interação do app Chat

Esta seção descreve como receber e processar eventos de interação para seu app de chat.

Configurar o app do Chat para receber eventos de interação

Nem todos os apps de chat são interativos. Por exemplo, os webhooks de entrada só podem enviar mensagens e não podem responder aos usuários. Se você estiver criando um app de chat interativo, escolha um endpoint que permita que ele receba, processe e responda a eventos de interação. Para saber mais sobre como projetar seu app do Chat, consulte Arquiteturas de implementação de apps do Chat.

Para cada um dos recursos interativos que você quer criar, atualize sua configuração na API Chat para que o Google Chat possa enviar eventos de interação relacionados ao seu app Chat:

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

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

2. Em Recursos interativos, analise as configurações e atualize com base nos recursos que você quer criar:

   Campo	Descrição
   Funcionalidade	Obrigatório. Um conjunto de campos que determinam como o app de chat pode interagir com os usuários. Por padrão, os usuários podem encontrar e enviar mensagens para o app Chat diretamente no Google Chat. Participar de espaços e conversas em grupo: os usuários podem adicionar o app Chat a espaços e conversas em grupo.
   Configurações de conexão	Obrigatório. O endpoint do app Chat, que é um dos seguintes: URL do endpoint HTTP: um endpoint HTTPS que hospeda a implementação do app Chat. Apps Script: um ID de implantação para um projeto do Apps Script que implementa um app do Chat. Nome do tópico do Cloud Pub/Sub: um tópico do Pub/Sub a que o app do Chat se inscreve como um endpoint. Dialogflow: registra o app Chat com uma integração do Dialogflow. Para mais informações, consulte Criar um app do Google Chat com o Dialogflow que entenda linguagem natural.
   Comandos	Opcional. Comandos de barra e comandos rápidos para o app Chat. Os comandos permitem que os usuários solicitem uma ação ou usem um recurso específico do app Chat. Para mais informações, consulte Responder a comandos do app Google Chat.
   Comandos iniciais	Opcional. (science prévia para desenvolvedores) Até três comandos iniciais que aparecem quando os usuários abrem uma mensagem direta individual vazia com o app Chat. Os comandos podem preencher texto na área de composição (com suporte à localização multilíngue) ou acionar um comando de barra/rápido diretamente. Para mais informações, consulte Configurar comandos iniciais.
   Visualizações de links	Opcional. Padrões de URL que o app Chat reconhece e fornece mais conteúdo para quando os usuários enviam links. Para mais informações, consulte Links de visualização.
   Visibilidade	Opcional. Até cinco pessoas ou um ou mais Grupos do Google que podem visualizar e instalar seu app do Chat. Use esse campo para testar ou compartilhar o app com sua equipe. Para mais informações, consulte Testar recursos interativos.

3. Clique em Salvar. Quando você salva a configuração do app Chat, ele fica disponível para os usuários especificados na sua organização do Google Workspace.

O app do Chat agora está configurado para receber eventos de interação do 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 a mesma mensagem algumas vezes em determinadas situações. Se a solicitação for concluída, mas retornar uma carga útil de mensagem inválida, o Google Chat não vai tentar de novo.

Processar ou responder a eventos de interação

Esta seção explica como os apps do Google Chat podem processar e responder a eventos de interação.

Depois que o app do Chat recebe um evento de interação do Google Chat, ele pode responder de várias maneiras. Em muitos casos, os apps de chat interativos respondem ao usuário com uma mensagem. O app Google Chat também pode pesquisar algumas informações em uma fonte de dados, registrar as informações do evento de interação ou fazer quase qualquer outra coisa. Esse comportamento de processamento é essencialmente o que define o app do Google Chat.

Para responder de forma síncrona, um app do Chat precisa responder em até 30 segundos, e a resposta precisa ser postada no espaço em que a interação ocorreu. Caso contrário, o app Chat pode responder de forma assíncrona.

Para cada evento de interação, os apps do Chat recebem um corpo da solicitação, que é o payload JSON que representa o evento. Você pode usar as informações para processar uma resposta. Para ver exemplos de payloads de eventos, consulte Tipos de eventos de interação do app Chat.

O diagrama a seguir demonstra como um app do Google Chat normalmente processa ou responde a diferentes tipos de eventos de interação:

Resposta em tempo real

Os eventos de interação permitem que os apps de chat respondam em tempo real ou de forma síncrona. As respostas síncronas não exigem autenticação.

Para responder em tempo real, o app Chat precisa retornar um objeto Message. Para responder com uma mensagem no espaço, o objeto Message pode conter objetos text, cardsV2 e accessoryWidgets. Para usar com outros tipos de respostas, consulte os seguintes guias:

• Abrir caixas de diálogo interativas
• Links de prévia
• Processar informações enviadas pelos usuários

Enviar uma mensagem

Neste exemplo, o app do Chat cria e envia uma mensagem de texto sempre que é adicionado a um espaço. Para saber mais sobre as práticas recomendadas de integração de usuários, consulte Apresentar seu app do Chat aos usuários.

Para enviar uma mensagem de texto quando um usuário adicionar seu app do Chat a um espaço, o app do Chat responde a um ADDED_TO_SPACE evento de interação. Para responder a eventos de interação ADDED_TO_SPACE com uma mensagem de texto, use o seguinte código:

/**
 * 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`.'
  }
}

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

Responder de forma assíncrona

Às vezes, os apps do Chat precisam responder a um evento de interação após 30 segundos ou realizar tarefas fora do espaço em que o evento de interação foi gerado. Por exemplo, um app de chat pode precisar responder ao usuário depois de concluir uma tarefa de longa duração. Nesse caso, os apps do Chat podem responder de forma assíncrona chamando a API Google Chat.

Para criar uma mensagem usando a API do Chat, consulte Criar uma mensagem. Para guias sobre como usar outros métodos da API Chat, consulte a visão geral da API Chat.

Temas relacionados

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