Responder a comandos do app Google Chat

Esta página explica 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 do Chat. Somente os apps do Chat podem ver o conteúdo de um comando. Por exemplo, se um usuário enviar uma mensagem com um comando de barra, a mensagem só vai ficar visível para o usuário e o app do Chat.

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

Tipos de comandos do app do Chat

É possível criar comandos de app do Chat como comandos de barra, comandos rápidos ou ações de mensagens. Para usar cada tipo de comando, os usuários podem fazer o seguinte:

Comandos de barra: os usuários podem selecionar um comando de barra no menu ou digitar uma barra (/) e um texto predefinido, como /about. Os apps do Chat geralmente exigem texto de argumento para o comando de barra.

Crie um comando de barra se o app do Chat exigir mais informações do usuário. Por exemplo, é possível criar um comando de barra chamado /search que é executado depois que o usuário insere uma frase para pesquisar, como /search receipts.
Comandos rápidos:os usuários usam comandos abrindo o menu na área de resposta de uma mensagem do Chat. Para usar um comando, eles clicam em Adicionar e selecionam um comando no menu.

Crie um comando rápido se o app do Chat puder responder ao usuário imediatamente, sem esperar por mais informações. Por exemplo, é possível criar um comando rápido chamado Imagem aleatória que responde imediatamente com uma imagem.
Ações de mensagens: ( versão prévia para desenvolvedores) os usuários usam ações de mensagens passando o cursor sobre uma mensagem e clicando no menu de três pontos. Para usar um comando, eles abrem o menu de três pontos e selecionam um comando no menu.

Crie uma ação de mensagem se o app do Chat puder realizar ações com base no contexto de uma mensagem.

As imagens a seguir mostram como os usuários descobrem o menu de comandos de barra e rápidos e ações de mensagens:

Um usuário descobre um menu de comandos de barra e comandos rápidos. — Os usuários descobrem um menu de comandos de barra e comandos rápidos.

Um usuário descobre um menu de contexto de mensagem que contém uma ação de mensagem. — Os usuários descobrem um menu de contexto de mensagem que contém uma "Lembre-me" ação de mensagem.

Pré-requisitos

Node.js

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat usando um serviço HTTP, conclua este guia de início rápido.

Apps Script

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat no Apps Script, conclua este guia de início rápido.

Python

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat usando um serviço HTTP, conclua este guia de início rápido.

Java

Um app do Google Chat que recebe e responde a eventos de interação. Para criar um app interativo do Chat 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:

Crie um nome e uma descrição para o comando.
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 do Chat. Uma breve descrição também aparece abaixo do nome para incentivar os usuários a usar o comando:

Nome e descrição do comando de barra — O nome e a descrição de um comando de barra.

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

Para nomear um comando:

Use palavras ou frases curtas, descritivas e acionáveis para deixar os comandos claros para o usuário. Por exemplo, em vez do nome Create a reminder, use Remind me.
Considere usar um nome exclusivo ou comum para o comando. Se o comando descrever uma interação ou um recurso típico, você poderá usar um nome comum que os usuários reconheçam e esperem, como Settings ou Feedback. Caso contrário, tente usar nomes de comandos exclusivos . Se o nome do comando for o mesmo para outros apps do Chat, o usuário precisará 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 exige 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 de forma particular ao usuário que invoca o comando. Por exemplo, para o comando rápido About, você pode descrevê-lo como Learn about this app (Only visible to you).

Configurar o comando no console do Google Cloud

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

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

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

Acessar a página da API Google Chat
Clique em Configuração.
Em Comandos, clique em Adicionar um comando.
Insira um ID, uma descrição, um tipo e um nome para o comando:
- ID do comando:um número de 1 a 1000 que o app do Chat usa para reconhecer o comando e retornar uma resposta.
- 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, Comando de barra ou Ação de mensagem.
- Especifique um nome para o comando:
  - Nome do comando rápido:o nome de exibição que os usuários selecionam no menu para invocar o comando. Pode ter até 50 caracteres e incluir caracteres especiais. Por exemplo, Remind me.
  - Nome do comando de barra:o texto que os usuários digitam para invocar o comando em uma mensagem. Precisa começar com uma barra, conter apenas texto e ter até 50 caracteres. Por exemplo, /remindMe.
  - Nome da ação de mensagem ( versão prévia para desenvolvedores) o nome de exibição que os usuários selecionam no menu para invocar a ação de mensagem. Pode ter até 50 caracteres e incluir caracteres especiais. Por exemplo, Remind me.
Opcional: Mensagem de notificação de carregamento: ( versão prévia para desenvolvedores) uma mensagem de notificação pop-up a ser exibida ao usuário enquanto a ação de mensagem está sendo executada. Disponível apenas para ações de mensagens que não abrem caixas de diálogo.
Opcional: se você quiser que o app do Chat responda a o comando com uma caixa de diálogo, marque a Abrir uma caixa de diálogo caixa de seleção.
Clique em Salvar.

O comando agora está configurado para o app do Chat.

Responder a um comando

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

Mensagem privada para o
app de chat do Cymbal Labs. A mensagem diz que o
app de chat foi criado pelo Cymbal Labs e compartilha um link
para a documentação e um link para entrar em contato com a equipe de suporte. — Um app do Chat responde de forma particular ao comando de barra `/help` para explicar como receber suporte.

Para responder a cada tipo de comando, é necessário processar diferentes tipos de eventos 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`
Ação de mensagem	`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 do Chat que responde ao comando de barra /about. O app do Chat processa eventos de interação MESSAGE, detecta se o evento de interação contém o ID do comando correspondente e retorna uma mensagem particular:

Node.js

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

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

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

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 do Chat que responde ao comando rápido Ajuda. O app do Chat processa eventos de interação APP_COMMAND, detecta se o evento de interação contém o ID do comando correspondente e retorna uma mensagem particular:

Node.js

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

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

Ver no GitHub

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

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

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.

Responder a uma ação de mensagem

O código a seguir mostra um exemplo de um app do Chat que responde à ação de mensagem Lembre-me. O app do Chat processa eventos de interação APP_COMMAND, detecta se o evento de interação contém o ID do comando correspondente e retorna uma mensagem particular:

Node.js

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

Apps Script

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

Python

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

Java

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

Substitua REMIND_ME_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 para 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 da Ajuda do Google Chat.

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

Responder a comandos do app Google Chat Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Tipos de comandos do app do Chat

Pré-requisitos

Node.js

Apps Script

Python

Java

Configurar o comando

Nomear e descrever o comando

Para nomear um comando:

Para descrever um comando:

Configurar o comando no console do Google Cloud

Responder a um comando

Responder a um comando de barra

Node.js

Apps Script

Python

Java

Responder a um comando rápido

Node.js

Apps Script

Python

Java

Responder a uma ação de mensagem

Node.js

Apps Script

Python

Java

Testar o comando

Temas relacionados

Responder a comandos do app Google Chat