Responder a comandos de barra como um app do Google Chat

Esta página explica como configurar e responder a comandos de barra para seu app Google Chat.

Um comando de barra é uma maneira comum de os usuários invocarem e interagirem com um app de chat. Os comandos de barra também ajudam os usuários a descobrir e usar os principais recursos de um app de chat.

Para usar um comando de barra, os usuários digitam uma barra (/) e um comando de texto curto, como /about, para receber informações sobre o app Chat. Os usuários podem descobrir os comandos de barra disponíveis digitando uma barra no Google Chat, que exibe uma janela com a lista de comandos disponíveis para o app Chat:

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

Comandos de barra com respostas particulares

Quando um usuário envia uma mensagem que contém um comando de barra, a mensagem só é visível para o usuário e o app do Chat. Se você configurou seu app do Chat para ser adicionado a espaços com várias pessoas, considere responder ao comando de barra de forma privada, para manter a interação privada entre o usuário e o App Chat.

Por exemplo, para saber mais sobre um app de chat que eles descobriram em um espaço, os usuários podem usar comandos como /about ou /help. Para evitar notificações a todos os outros participantes do espaço, o app de chat pode responder com informações sobre como usar o app e receber suporte.

Pré-requisitos

Configurar um comando de barra

Esta seção explica como concluir as etapas a seguir para configurar um comando de barra oblíqua:

1. Crie um nome para o comando de barra.
2. Configure o comando de barra na API Google Chat.

Nomeie seu comando de barra

O nome de um comando de barra é o que os usuários digitam em uma mensagem do Chat para invocar o app. Uma breve descrição também aparece abaixo do nome para orientar os usuários sobre como usar o comando:

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

• Para nomear o comando de barra:

  • Use palavras ou frases curtas, descritivas e acionáveis para tornar comandos claros e simples para o usuário. Por exemplo, em vez de dizer /createAReminder, use /remindMe.
  • Se o comando tiver mais de uma palavra, ajude os usuários a ler o comando usando letras minúsculas para a primeira palavra e, em seguida, capitalizando a primeira letra das outras palavras. Por exemplo, em vez de /updatecontact, use /updateContact.
  • Considere usar um nome exclusivo ou comum para o comando. Se seu comando descreve uma interação ou recurso típico, é possível usar nome comum que os usuários reconhecem e esperam, como /settingsou /feedback. Caso contrário, tente usar nomes de comandos exclusivos, porque se os seus nome do comando for o mesmo em outros apps de chat, o usuário precisará filtrar por comandos semelhantes para encontrar e usar o seu.

• Para descrever seu comando de barra:

  • 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 há requisitos de formatação para o comando. Por exemplo, se você criar um comando /remindMe que requer argumento defina a descrição como Remind me to do [something] at [time].
  • Informe aos usuários se o app de chat responde a todos no espaço ou de forma privada ao usuário que invocou o comando. Por exemplo, para o comando de barra /about, é possível descrevê-lo como Learn about this app (Only visible to you).

Configurar o comando de barra na API Google Chat

Para criar um comando de barra, você precisa especificar informações sobre ele em a configuração do seu app do Chat para a API Google Chat.

Para configurar um comando de barra na API Google Chat, faça o seguinte: etapas:

1. No console do Google Cloud, clique em Menu 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 de barra, clique em Adicionar um comando de barra.

4. Digite um nome, um ID de comando e uma descrição para o comando:

   1. Nome:o nome de exibição do comando e o que os usuários digitam para invocar seu app. Precisa começar com uma barra, conter apenas texto e pode ter até 50 caracteres.
   2. Descrição:o texto que descreve como usar e formatar o comando. As descrições podem ter até 50 caracteres.
   3. ID do comando:um número de 1 a 1.000 que seu O app do Chat usa para reconhecer o comando de barra e retornam uma resposta.

5. Opcional: se você quiser que o app do Chat responda a o comando com uma caixa de diálogo, selecione o Caixa de seleção Abrir uma caixa de diálogo.

6. Clique em Salvar.

O comando de barra agora está configurado para o app Chat.

Responder a um comando de barra

Quando os usuários criam uma mensagem do Chat que contém um comando de barra, seu app do Chat recebe um evento de interação MESSAGE. O payload do evento contém o slashCommand e slashCommandMetadata objetos. Esses objetos contêm detalhes sobre o comando usado na mensagem (incluindo o ID do comando), para que você possa retornar uma resposta adequada.

O código a seguir mostra um exemplo de app do Chat que responde ao comando de barra /about processando MESSAGE evento de interação e detectando se a mensagem contém o ID de comando correspondente. Se a mensagem contiver o ID do comando, o app do Chat retornará uma mensagem privada:

// 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 res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

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

# Checks for the presence of a slash command in the message.
if "slashCommand" in request_json["message"]:
  # Executes the slash command logic based on its ID.
  # Slash command IDs are set in the Google Chat API configuration.
  if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
    return {
      "privateMessageViewer": request_json["user"],
      "text": 'The Avatar app replies to Google Chat messages.'
    }

// Checks for the presence of a slash command in the message.
if (body.getAsJsonObject("message").has("slashCommand")) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
  switch (slashCommand.get("commandId").getAsString()) {
    case ABOUT_COMMAND_ID:
    JsonObject aboutMessage = new JsonObject();
    aboutMessage.addProperty("text", "The Avatar app replies to Google Chat messages.");
    aboutMessage.add("privateMessageViewer", body.getAsJsonObject("user"));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
  }
}

Defina ABOUT_COMMAND_ID com o ID de comando que você especificado quando você configurou o comando de barra na API Chat. Para testar esse código, consulte Testar recursos interativos em apps do Google Chat.

Temas relacionados

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