Responder a comandos do app Google Chat

Nesta página, explicamos como configurar e responder a comandos como um app do Google Chat.

Os comandos ajudam os usuários a descobrir e usar os principais recursos de um app de chat. Somente os apps de chat podem acessar o conteúdo de um comando. Por exemplo, se um usuário enviar uma mensagem com um comando de barra oblíqua, ela só vai ficar visível para o usuário e o app Chat.

Para decidir se você precisa criar comandos e entender como projetar interações do usuário, consulte Definir todas as jornadas do usuário.

Tipos de comandos do app Chat

Você pode criar comandos de app do Chat como comandos de barra ou rápidos. Para descobrir e usar cada tipo de comando, os usuários fazem o seguinte:

1. Comandos de barra:os usuários enviam comandos como mensagens digitando uma barra (/) e um texto predefinido, como /about. Os apps de chat também podem exigir texto de argumento para o comando de barra. Por exemplo, o comando de barra /search pode exigir um texto de argumento usado para uma consulta de pesquisa.
2. Comandos rápidos:os usuários usam comandos abrindo o menu na área de resposta de uma mensagem do Chat. Para usar um comando, o usuário clica em Adicionar e seleciona um comando no menu.

As imagens a seguir mostram como os usuários descobrem um menu de comandos de barra e comandos rápidos:

• 

  Figura 1. Os usuários descobrem e usam os comandos de barra digitando uma barra / na área de resposta, seguida pelo nome do comando.

• 
  Figura 2. Os usuários descobrem e usam comandos rápidos no menu da área de resposta de uma mensagem do Chat.

Pré-requisitos

Observação: os exemplos de código neste guia foram escritos para serem executados como uma função do Google Cloud para Node.js, Python e Java.

Node.jsApps ScriptPythonJava

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app de chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app do Chat interativo no Apps Script, conclua este guia de início rápido.

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app de chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Um app do Google Chat que tenha recursos interativos ativados. Para criar um app de chat interativo usando um serviço HTTP, conclua este guia de início rápido.

Configurar o comando

Esta seção explica como concluir as etapas a seguir para configurar o comando:

1. Crie um nome e uma descrição para o comando.
2. Configure o comando no console do Google Cloud.

Nomear e descrever o comando

O nome de um comando é o que os usuários digitam ou selecionam para invocar o app Chat. Uma breve descrição também aparece abaixo do nome para informar aos usuários como usar o comando:

Figura 3: o nome e a descrição de um comando de barra.

Ao escolher um nome e uma descrição para o comando, considere estas recomendações:

Para nomear um comando:

• Use palavras ou frases curtas, descritivas e úteis para deixar os comandos claros para o usuário. Por exemplo, em vez do nome Create a reminder, use Remind me.
• Use um nome exclusivo ou comum para o comando. Se o comando descrever uma interação ou recurso típico, use um nome comum que os usuários reconheçam e esperem, como Settings ou Feedback. Caso contrário, tente usar nomes de comando exclusivos, porque se o nome do comando for o mesmo de outros apps de chat, o usuário terá que filtrar comandos semelhantes para encontrar e usar o seu.

Para descrever um comando:

• Mantenha a descrição curta e clara para que os usuários saibam o que esperar ao usar o comando.
• Informe aos usuários se há requisitos de formatação para o comando. Por exemplo, se você criar um comando de barra que exija texto de argumento, defina a descrição como algo como Remind me to do [something] at [time].
• Informe aos usuários se o app do Chat responde a todos no espaço ou apenas ao usuário que invocou o comando. Por exemplo, para o comando rápido About, você pode descrever como Learn about this app (Only visible to you).

Configurar o comando no console do Google Cloud

Para criar um comando de barra ou rápido, especifique informações sobre ele na configuração do app do Chat para a API Google Chat.

Para configurar um comando na API Google Chat, siga estas etapas:

1. No console do Google Cloud, clique em Menu > APIs e serviços > Ativar APIs e serviços > API Google Chat

   Acessar a página da API Google Chat

2. Clique em Configuração.

3. Em Comandos, clique em Adicionar um comando.

4. Insira um ID, nome, descrição e tipo de comando:

   • ID do comando:um número de 1 a 1.000 que o app de chat usa para reconhecer o comando e retornar uma resposta.
   • Nome:o nome de exibição do comando. Os nomes podem ter até 50 caracteres e podem incluir caracteres especiais.
   • Descrição:o texto que descreve o que o comando faz. As descrições podem ter até 50 caracteres e incluir caracteres especiais.
   • Tipo de comando:selecione Comando rápido ou Comando de barra.
   • Se você estiver configurando um comando de barra, insira um valor no campo Nome do comando de barra para especificar o que os usuários digitam para invocar o comando. Precisa começar com um caractere de barra, conter apenas texto e pode ter até 50 caracteres. Por exemplo, /remindMe.

5. Opcional: se você quiser que o app de chat responda ao comando com uma caixa de diálogo, marque a caixa de seleção Abrir uma caixa de diálogo.

6. Clique em Salvar.

O comando agora está configurado para o app Chat.

Responder a um comando

Para mais exemplos, consulte Exemplos de apps do Google Chat.

Quando os usuários usam um comando, o app Chat recebe um evento de interação. O payload do evento contém metadados com detalhes sobre o comando que foi invocado (incluindo o ID e o tipo do comando), para que você possa retornar uma resposta adequada.

Um app do Chat responde de forma privada ao comando de barra /help para explicar como receber suporte.

Para responder a cada tipo de comando, é necessário processar diferentes tipos de evento e objetos de metadados no payload do evento:

Tipo de comando	Tipo de evento	Metadados do comando
Comando de barra	MESSAGE	message.slashCommand ou message.annotation.slashCommand
Comando rápido	APP_COMMAND	appCommandMetadata

Para saber como responder a um comando com uma mensagem, consulte as seções a seguir.

Responder a um comando de barra

O código a seguir mostra um exemplo de um app de chat que responde ao comando de barra /about. O app Chat processa eventos de interação MESSAGE, detecta se o evento de interação contém o ID de comando correspondente e retorna uma mensagem particular:

Node.js Apps Script Python Java

node/avatar-app/index.js

Ver no GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

Ver no GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

python/avatar-app/main.py

Ver no GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

Ver no GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Substitua ABOUT_COMMAND_ID pelo ID do comando especificado ao configurar o comando no console do Google Cloud.

Responder a um comando rápido

O código a seguir mostra um exemplo de um app de chat que responde ao comando rápido Help. O app Chat processa eventos de interação APP_COMMAND, detecta se o evento de interação contém o ID de comando correspondente e retorna uma mensagem particular:

Node.js Apps Script Python Java

node/avatar-app/index.js

Ver no GitHub

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

apps-script/avatar-app/avatar-app.gs

Ver no GitHub

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

python/avatar-app/main.py

Ver no GitHub

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

java/avatar-app/src/main/java/AvatarApp.java

Ver no GitHub

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Substitua HELP_COMMAND_ID pelo ID do comando especificado ao configurar o comando no console do Google Cloud.

Testar o comando

Para testar o comando e o código, consulte Testar recursos interativos em apps do Google Chat.

Para saber como testar e usar o comando na interface do Chat, consulte Usar apps no Google Chat na documentação de ajuda do Google Chat.

Temas relacionados

• Confira exemplos de apps do Chat que usam comandos.
• Enviar uma mensagem
• Abrir caixas de diálogo interativas