Responder a comandos rápidos como um app do Google Chat

Nesta página, explicamos como configurar e responder a comandos rápidos no app Google Chat.

Um comando rápido é uma maneira de os usuários invocarem e interagirem com um app de chat. Para usar um comando rápido, abra o menu de integração clicando em Ferramentas do Google Workspace em um espaço ou conversa do Chat e selecione um comando de app com um nome que não comece com um caractere de barra (/). Ao selecionar um comando rápido, o app Chat é invocado diretamente sem outras entradas do usuário, permitindo interações rápidas.

Os usuários também podem invocar um app de chat usando um comando de barra. Para conferir as etapas, consulte Responder a comandos de barra. Em comparação com os comandos de barra, os comandos rápidos são formatados com um nome mais fácil de usar na interface do Chat, são invocados imediatamente após a seleção e não exigem que o usuário se lembre ou digite o nome do comando de barra.

Menu de integração com comandos rápidos
Figura 1: o menu de integração com comandos rápidos para um app de chat.

Configurar um comando rápido na API Google Chat

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

Para configurar um comando rápido 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.
      • Use palavras ou frases curtas, descritivas e práticas para deixar os comandos claros para o usuário. Por exemplo, use Atualizar contato para um comando que modifique um registro de contato.
    • Descrição:o texto que descreve o que o comando faz. As descrições podem ter até 50 caracteres e incluir caracteres especiais.
      • Mantenha a descrição curta e clara para que os usuários saibam o que esperar ao invocar o comando.
      • Informe aos usuários se o app de chat responde a todos no espaço ou de forma privada ao usuário que invoca o comando. Por exemplo, para o comando rápido Sobre, você pode descrever como Saiba mais sobre este app (visível apenas para você).
    • Tipo de comando:selecione Comando rápido.

  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 rápido agora está configurado para o app Chat.

Responder a um comando rápido

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

O código a seguir mostra um exemplo de um app de chat que responde ao comando Help processando eventos de interação APP_COMMAND e detectando se o payload do evento contém o ID de comando correspondente. Se o payload do evento contiver o ID do comando, o app Chat vai retornar uma mensagem particular:

Apps Script 

// Handle the APP_COMMAND event type.
function onAppCommand(event) {
  // Executes the 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.'
      };
  }
}

Defina HELP_COMMAND_ID com o ID do comando especificado quando você configurou o comando rápido na API Chat. Para testar esse código, consulte Testar recursos interativos em apps do Google Chat. Para testar um comando rápido no Chat, abra o menu de integração clicando em Ferramentas do Google Workspace e selecionando o comando rápido.

Transformar comandos de barra em comandos rápidos

Para transformar um comando de barra em um comando rápido, edite o comando de barra na API Google Chat mudando o Tipo de comando de Comando de barra para Comando rápido.

Quando os usuários invocam um comando rápido, o app de chat recebe um evento de interação APP_COMMAND, em vez de um evento de interação MESSAGE enviado para comandos de barra. Atualize seu app de chat para processar esse tipo de evento de interação lendo o payload do evento que contém o objeto appCommandMetadata com detalhes sobre o comando rápido invocado. Consulte Responder a um comando rápido.