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:-
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/searchpode exigir um texto de argumento usado para uma consulta de pesquisa. -
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.
-
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
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
- Crie um projeto do Google Cloud.
- Configure a tela de consentimento OAuth.
- Ative as seguintes APIs do Google Workspace:
- API Google Chat
- API Google Workspace Add-ons
- Um endpoint HTTP que hospeda a arquitetura de serviço do seu app de chat.
- Uma conta do Google Workspace para empresas ou empresas com acesso ao Google Chat.
- Crie um projeto do Google Cloud.
- Configure a tela de consentimento OAuth.
- Ative a API Google Chat.
- Crie um projeto independente do Apps Script e ative o Serviço avançado de chat.
- Configure o Chat no manifesto,
adicionando o objeto
addons.chate todos os escopos necessários (oauthScopes) ou prefixos de URL HTTPS (urlFetchWhitelist).
Configurar o comando
Esta seção explica como concluir as etapas a seguir para configurar um 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 Chat. Uma breve descrição também aparece abaixo do nome para informar aos usuários como usar o comando:
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, useRemind me. - Use um nome exclusivo ou comum para o comando. Se o comando descrever uma
interação ou um recurso típico, use um nome comum que os usuários reconheçam e esperem,
como
SettingsouFeedback. 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 comoLearn 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: o configure um comando de barra na API Google Chat, siga estas etapas:
No console do Google Cloud, clique em Menu > APIs e serviços > Ativar APIs e serviços > API Google Chat
Clique em Configuração.
Em Configurações avançadas, acesse Gatilhos e verifique se o campo Comando do app contém um acionador, como um endpoint HTTP ou uma função do Apps Script. Use esse acionador na seção a seguir para responder ao comando.
Em Comandos, clique em Adicionar um comando.
Digite as seguintes informações sobre o 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.
- 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. - Nome:o nome fácil de usar do comando. Os nomes podem ter até 50 caracteres e podem incluir caracteres especiais.
- Descrição:o texto que descreve como usar e formatar o comando. As descrições podem ter até 50 caracteres.
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.
Clique em Salvar.
O comando agora está configurado para o app Chat.
Responder a um comando
Quando os usuários usam um comando, o app Chat
recebe um objeto de evento.
O payload do evento contém um objeto
appCommandPayload
com detalhes sobre o comando que foi
invocado (incluindo o ID e o tipo do comando), para que você possa retornar
uma resposta adequada. O objeto de evento é enviado ao endpoint HTTP ou à função do Apps Script que você especificou ao configurar o acionador comando do app.
/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 comando do app. 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:
// 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 events 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 chatEvent = req.body.chat;
// Handles events that contain payloads about commands
if (chatEvent.appCommandPayload) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;
// Executes the slash command logic based on its ID.
// Slash command IDs are set in the Google Chat API configuration.
switch (appCommandMetadata.appCommandId) {
case ABOUT_COMMAND_ID :
return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'The Avatar app replies to Google Chat messages.'
}}}}});
}
// Handles MESSAGE events
} else if (chatEvent.messagePayload) {
// Stores the Google Chat event as a variable.
const chatMessage = chatEvent.messagePayload.message;
// 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 }
}]
}]
}
}]
}}}}});
}
};
// 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;
// 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 }
}]
}]
}
}]
}}}}};
}
/**
* Responds to an APP_COMMAND event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onAppCommand(event) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;
// Executes the slash command logic based on its ID.
// Slash command IDs are set in the Google Chat API configuration.
switch (appCommandMetadata.appCommandId) {
case ABOUT_COMMAND_ID :
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'The Avatar app replies to Google Chat messages.'
}}}}};
}
}
Para usar este exemplo de código, substitua ABOUT_COMMAND_ID pelo
ID do comando especificado ao
configurar o comando na API Chat.
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