Responder a comandos de barra no Google Chat

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

No Google Chat, os complementos aparecem para os usuários como apps do Google Chat. Para saber mais, consulte a Visão geral do Extend 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 decidir se você precisa configurar comandos de barra e entender como projetar interações com o usuário, consulte Definir todas as jornadas do usuário na documentação da API Chat.

Como os usuários usam os comandos de barra

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:

Janela de comando de barra
Figura 1: a janela que aparece quando os usuários digitam uma barra no Google Chat.

Quando um usuário envia uma mensagem que contém um comando de barra, ela só fica visível para o usuário e o app do Chat. Se você configurou o 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 entre o usuário e o app do 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 de forma particular com informações sobre como usar o app e receber suporte.

Pré-requisitos

Node.js

Um complemento do Google Workspace que estende o Google Chat. Para criar um, conclua o Guia de início rápido do HTTP.

Apps Script

Um complemento do Google Workspace que estende o Google Chat. Para criar um, conclua o Guia de início rápido do Apps Script.

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.

Nomear o 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:

Nome e descrição do comando de barra
Figura 2: o nome e a descrição de um comando de barra.

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

  • Para nomear o comando de barra:

    • Use palavras ou frases curtas, descritivas e práticas para tornar os 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 todas as 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 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 comandos 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 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 exija texto de argumento, defina a descrição como Remind me to do [something] at [time].
    • Informe aos usuários se o app Chat responde a todos no espaço ou de forma privada ao usuário que invoca o comando. Por exemplo, para o comando de barra /about, você pode descrever 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 na configuração do app de chat para a API Google Chat.

Para configurar um comando de barra 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 Configurações avançadas, acesse Gatilhos e verifique se o campo MESSAGE contém um gatilho, como um endpoint HTTP ou uma função do Apps Script. Use esse acionador na próxima seção para responder ao comando de barra.

  4. Em Comandos de barra, clique em Adicionar um comando de barra.

  5. Insira um nome, um ID 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 o app. Precisa começar com um caractere de barra e conter apenas texto, podendo 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 o app de chat usa para reconhecer o comando de barra e retornar uma resposta.

  6. 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.

  7. 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, o app recebe um objeto de evento que contém informações sobre a mensagem. O objeto de evento contém um payload com detalhes sobre o comando usado na mensagem (incluindo o ID do comando), para que você possa retornar uma resposta adequada.

Para responder a um comando de barra, implemente o gatilho Message para que o app do Chat possa processar todos os objetos de evento que contêm metadados de comando de barra.

Mensagem particular para o app Cymbal Labs Chat. A mensagem informa que o app de chat foi criado pela 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 privada ao comando de barra /help para explicar como receber suporte.

O código a seguir mostra um exemplo de um app de chat que responde ao comando de barra /about com uma mensagem de texto. Para responder a comandos de barra, o app Chat processa objetos de evento de um acionador de mensagem. Quando o payload de um objeto de evento contém um ID de comando de barra oculta, o app Chat retorna a ação DataActions com um objeto createMessageAction:

Node.js 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to messages sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }

    // Stores the Google Chat event as a variable.
    const chatMessage = req.body.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}});
        }
    }

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}});
};

Apps Script 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    if (chatMessage.slashCommand) {
        // Executes the slash command logic based on its ID.
        // Slash command IDs are set in the Google Chat API configuration.
        switch (chatMessage.slashCommand.commandId) {
            case ABOUT_COMMAND_ID:
                return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                    text: 'The Avatar app replies to Google Chat messages.'
                }}}}};
        }
    }

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

Para usar este exemplo de código, substitua ABOUT_COMMAND_ID pelo ID de comando especificado ao configurar o comando de barra na API Chat.