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 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, ela só vai ficar visível para o usuário e o app do 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 do app Chat como comandos de barra, comandos rápidos ou ações de mensagem. 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 um 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
/searchque é executado depois que o usuário digita 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 de chat. Para usar um comando, clique em Adicionar
e selecione um comando no menu.
Crie uma resposta automática rápida 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 mensagem: os usuários usam as ações de mensagem 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.
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, além das ações de mensagem:
Pré-requisitos
HTTP
Um app do Google Chat que recebe e responde a interações do usuário. Para criar um, conclua o guia de início rápido de HTTP.
Apps Script
Um app do Google Chat que recebe e responde a interações do usuário. Para criar um, conclua o guia de início rápido do Apps Script.
Configurar o comando
Nesta seção, explicamos como concluir as seguintes etapas para configurar um comando:
- Crie um nome e uma descrição para o comando.
- Configure o comando no console do Google Cloud.
- Opcional: mapear comandos para comandos iniciais.
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 orientar os usuários sobre como usar o comando:
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 que os comandos fiquem 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 descreve 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 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 houver requisitos de formatação para o comando. Por exemplo, se você
criar um comando de barra que exija um 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
em particular ao usuário que invoca o comando. Por exemplo, para o comando rápido
About, você pode descrevê-lo comoLearn 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
Clique em Configuração.
Em Configurações de conexão, acesse Gatilhos e especifique os detalhes do endpoint. Use esse gatilho na seção a seguir para responder ao comando.
- URL do endpoint HTTP: é possível especificar um URL de endpoint HTTP comum aqui. Como alternativa, para usar endpoints HTTP diferentes para gatilhos diferentes, especifique o endpoint diretamente no campo Comando do app.
- Apps Script: digite o ID de implantação do Apps Script. Por padrão,
a função
onAppCommandserá invocada. Para usar uma função diferente do Apps Script, especifique o nome da função personalizada no campo Comando do app.
Em Comandos, clique em Adicionar um comando.
Insira as seguintes informações sobre 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 como usar e formatar o comando. As descrições podem ter até 50 caracteres.
- 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
pode ter até 50 caracteres. Por exemplo,
/remindMe. - Nome da ação de mensagem: 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.
- 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,
Opcional: Mensagem de notificação de carregamento: uma mensagem de notificação de aviso para mostrar ao usuário enquanto a ação da mensagem está sendo executada. Disponível apenas para ações de mensagem que não abrem caixas de diálogo.
Opcional: se você quiser que o app do 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 do Chat.
Associar comandos a comandos iniciais
Você pode destacar seus comandos como comandos iniciais para que os usuários os vejam como ícones interativos ao iniciar uma mensagem direta individual vazia com seu app do Chat.
Para mapear um comando para um comando inicial:
- Verifique se o comando é de barra ou rápido. As ações de mensagem não podem ser mapeadas para comandos iniciais.
- No console do Google Cloud, acesse a página Configuração da API Chat.
- Em Recursos interativos > Comandos iniciais, clique em Adicionar comando padrão.
- Defina a Classificação (1 a 3) para a ordem de exibição. Cada comando configurado precisa ter uma classificação exclusiva.
- Em Seleção de tipo, selecione Comando.
- No menu ID do comando, selecione seu comando.
- Clique em Concluído e, depois, em Salvar.
Responder a um comando
Quando os usuários usam um comando, seu app do Chat
recebe um
objeto de evento.
O payload do evento (event.chat.appCommandPayload) 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 para o endpoint HTTP ou a função do Apps Script
que você especificou ao
configurar o gatilho do comando do app.
/help para explicar como receber suporte.Responder a um comando de barra ou comando rápido
O código a seguir mostra um exemplo de um app do Chat
que responde ao comando de barra /about com uma mensagem de texto. Para responder a
comandos de barra ou rápidos, o app do Chat processa
objetos de evento (event.chat.appCommandPayload) de um gatilho de comando de app.
Quando o payload de um objeto de evento contém um ID de comando correspondente, o
app do Chat retorna a ação DataActions com um objeto
createMessageAction
(hostAppDataAction.chatDataAction.createMessageAction):
Node.js
Python
Java
Apps Script
Para usar este exemplo de código, substitua ABOUT_COMMAND_ID pelo
ID do comando que você especificou ao
configurar o comando na API Chat.
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 Lembrar-me com uma mensagem de texto. Para responder
às ações de mensagem, o app do Chat processa objetos de evento
de um gatilho de comando do app. Quando o payload de um objeto de evento contém um
ID de comando de ação de mensagem, o app do Chat retorna a
ação DataActions com um
objeto createMessageAction:
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 onAppCommand(event, res) {
// Collect the command ID and type from the event metadata.
const {appCommandId, appCommandType} =
event.chat.appCommandPayload.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.chat.appCommandPayload.message.text;
// Return a response that includes details from the original message.
return res.json({
"hostAppDataAction": {
"chatDataAction": {
"createMessageAction": {
"message": {
"text": `Setting a reminder for message: "${messageText}"`
}
}
}
}
});
}
}
Python
def on_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.
payload = event.get('chat', {}).get('appCommandPayload', {})
metadata = payload.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 = payload.get('message', {}).get('text')
# Return a response that includes details from the original message.
return {
"hostAppDataAction": {
"chatDataAction": {
"createMessageAction": {
"message": {
"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 onAppCommand(JsonObject event, HttpResponse response) throws Exception {
// Collect the command ID and type from the event metadata.
JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
JsonObject metadata = payload.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 = payload.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);
JsonObject createMessageAction = new JsonObject();
createMessageAction.add("message", responseMessage);
JsonObject chatDataAction = new JsonObject();
chatDataAction.add("createMessageAction", createMessageAction);
JsonObject hostAppDataAction = new JsonObject();
hostAppDataAction.add("chatDataAction", chatDataAction);
JsonObject finalResponse = new JsonObject();
finalResponse.add("hostAppDataAction", hostAppDataAction);
response.getWriter().write(finalResponse.toString());
}
}
}
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.chat.appCommandPayload.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.chat.appCommandPayload.message.text;
// Return a response that includes details from the original message.
return CardService.newChatResponseBuilder()
.setText("Setting a reminder for message: " + messageText)
.build();
}
}
Para usar esse exemplo de código, substitua REMIND_ME_COMMAND_ID pelo
ID do comando que você especificou ao
configurar o comando na API Chat.
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 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
Apps do Chat que não são complementos: respondem a comandos
A documentação a seguir se aplica a apps do Chat que não são complementos do Google Workspace. Para migrar um app do Chat que não é um complemento, consulte Converter um app do Google Chat em um complemento do Google Workspace.
Quando os usuários usam um comando, um app do Chat que não é um
complemento recebe um
evento de interação
e pode responder retornando um objeto Message diretamente.
O payload do evento contém metadados com detalhes sobre o comando que foi
invocado (incluindo o ID e o tipo do comando) para que você possa retornar
uma resposta adequada.
Para responder a cada tipo de comando em um app do Chat que não é um complemento, você precisa processar diferentes tipos de evento e objetos de metadados no payload do evento:
| Tipo de comando | Tipo de evento | Metadados de comando |
|---|---|---|
| Comando de barra | MESSAGE |
message.slashCommand
ou message.annotation.slashCommand |
| Comando rápido | APP_COMMAND |
appCommandMetadata
|
| Mensagem de ação | APP_COMMAND |
appCommandMetadata
|
Responder a um comando de barra
O código a seguir mostra um exemplo de um app do Chat que
não é um complemento 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 um objeto Message particular:
Node.js
Apps Script
Python
Java
Substitua ABOUT_COMMAND_ID pelo ID do comando que você
especificou 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
não é um complemento 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 um objeto Message particular:
Node.js
Apps Script
Python
Java
Substitua HELP_COMMAND_ID pelo ID do comando que você
especificou 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
não é um complemento que responde à ação de mensagem
Lembrar-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 um objeto Message 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 que você
especificou ao configurar o comando no console do Google Cloud.