Esta página explica como configurar e responder a comandos de barra para seu app Google Chat.
Um comando de barra é uma forma comum de os usuários invocarem e interagirem com uma App Chat. Os comandos de barra também ajudam os usuários a descobrir e usar os principais recursos de um app do Chat.
Para usar um comando de barra, os usuários digitam uma barra (/) e, em seguida, um comando de texto curto:
como /about para saber informações sobre o app do Chat.
Os usuários podem descobrir os comandos de barra disponíveis digitando uma
O Google Chat, que mostra uma janela listando os comandos disponíveis para o
App do Chat:
Quando um usuário envia uma mensagem que contém um comando de barra, a mensagem é visível para o usuário e o app do Chat.
Para decidir se você deve configurar comandos de barra e entender como projetar interações do usuário, consulte Definir todas as jornadas do usuário.
Pré-requisitos
Node.js
Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.
Apps Script
Um app do Google Chat com recursos interativos ativados. Para criar um interativo com o app Chat no Apps Script, conclua este guia de início rápido.
Python
Um app do Google Chat com recursos interativos ativados. Para criar um interativo do Chat que usa um serviço HTTP, conclua este guia de início rápido.
Configurar um comando de barra
Esta seção explica como concluir as etapas a seguir para configurar uma barra comando:
- Crie um nome para o comando de barra.
- 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 do Chat. Uma breve descrição também abaixo do nome, para solicitar mais informações aos 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 todas as letras minúsculas na primeira palavra e colocando em maiúscula a primeira
uma carta de palavras adicionais. 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.
- 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
Para descrever seu comando de barra:
- Mantenha a descrição breve e clara para que os usuários saibam o que esperar quando invocam o comando.
- Informe aos usuários se há requisitos de formatação para o comando.
Por exemplo, se você criar um comando
/remindMeque requer argumento defina a descrição comoRemind me to do [something] at [time]. - Informe aos usuários se o app do Chat responder a
todos no espaço ou de forma particular para o usuário que invoca o comando.
Por exemplo, para o comando de barra
/about, é possível descrevê-lo comoLearn about this app (Only visible to you). Para responder de forma particular a uma , consulte a seção Responder com uma mensagem privada.
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:
No console do Google Cloud, clique em Menu > APIs e Serviços > APIs ativadas e Serviços > API Google Chat
Clique em Configuração.
Em Comandos de barra, clique em Adicionar um comando de barra.
Digite um nome, um ID de comando e uma descrição para o comando:
- 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.
- Descrição:o texto que descreve como usar e formatar o comando. As descrições podem ter até 50 caracteres.
- 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.
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.
Clique em Salvar.
O comando de barra agora está configurado para o app do 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 informações sobre o comando de barra,
incluindo o slashCommand
e slashCommandMetadata
campos. Use esses campos para identificar o ID de comando e retornar uma solicitação
resposta.
O exemplo a seguir mostra o payload JSON para um evento de interação MESSAGE.
que inclua o comando de barra /vote:
{
...
"message": {
...
"text": "/vote yes",
"argumentText": " yes",
"slashCommand": {
"commandId": 2
},
"annotations": [
{
"length": 5,
"startIndex": 0,
"type": "SLASH_COMMAND",
"slashCommand": {
"commandName":"/vote",
"commandId":1,
"type": "INVOKE",
"bot": {
"avatarUrl": "https://www.example.com/images/vote-app-icon.png",
"displayName": "Voter Chat App",
"name": "users/1234567890987654321",
"type": "BOT"
}
}
}
]
}
}
Para responder a um comando de barra, detecte se o campo slashCommand
está presente na carga do evento e, em caso afirmativo, retorna uma resposta ao comando.
O exemplo de código a seguir mostra como responder a um evento de interação MESSAGE.
que contém um comando de barra:
Node.js
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} function in response to a slash command.
*/
exports.onMessage = function onMessage(req, res) {
// Stores the Google Chat event as a variable.
var event = req.body;
// Checks for the presence of event.message.slashCommand.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
res.json(runFunction); // The response to the slash command.
}
}
Apps Script
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} function in response to a slash command.
*/
function onMessage(event) {
// Checks for the presence of event.message.slashCommand
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case ID: // The ID for your slash command
return runFunction; // The response to the slash command.
}
}
}
Python
from typing import Any, Mapping
import flask
import functions_framework
@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
"""Responds to a MESSAGE event in Google Chat that includes a slash command.
Args:
req (flask.Request): the event object from Chat API.
Returns:
Mapping[str, Any]: function in response to a slash command.
"""
if req.method == 'GET':
return 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if slash_command := request.get('message', dict()).get('slashCommand'):
command_id = slash_command['commandId']
if command_id == ID:
return runFunction
Para usar o código, substitua o seguinte:
ID: o ID de comando especificado quando você Configure o comando de barra na API Google Chat.runFunction: uma função que cria uma resposta para o comando de barra.
Opcional: responder com uma mensagem particular
As mensagens que contêm comandos de barra são visíveis apenas para o usuário que enviou o e o app do Chat que recebe o comando. 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, se uma equipe estiver usando um app do Chat que gerencia
um serviço de suporte ao cliente, os usuários podem invocar um comando de barra como
/myCases para acessar os casos de suporte atribuídos. Se a equipe adicionar o
App do Chat para um espaço, um usuário que usa este comando de barra
no espaço talvez queira que o app do Chat responda apenas
para resolvê-los com rapidez. Para evitar postar os casos de suporte do usuário para todos no espaço, o
O app do Chat pode responder com privacidade.
Para responder a um comando de barra de maneira particular, consulte Enviar mensagens privadas para usuários do Google Chat.
Exemplo completo: configurar contatos usando o app Rolodex Chat
O exemplo a seguir mostra um app do Chat que responde estes comandos de barra:
- O comando
/helpretorna uma mensagem de texto que explica como receber com o app Chat. O ID do comando está definido para1. - O comando
/createContactabre uma caixa de diálogo em que os usuários podem inserir detalhes sobre um contato. O ID do comando está definido como2.
Antes de executar este exemplo, siga as etapas para Configure os comandos de barra na API Google Chat.
Node.js
/**
* Responds to messages that have links whose URLs
* match URL patterns configured for link previews.
*
* @param {Object} event The event object from Chat
* API.
*
* @return {Object} Response from the Chat app
* attached to the message with the previewed link.
*/
exports.onMessage = function onMessage(req, res) {
// Store the Google Chat event as a variable.
const event = req.body;
if (req.method === "GET" || !event.message) {
res.send("Hello! This function is meant to be used in a Google Chat " +
"Space.");
}
// Checks for the presence of event.message.slashCommand.
// If the slash command is "/help", responds with a text message.
// If the slash command is "/createContact", opens a dialog.
if (event.message.slashCommand) {
switch (event.message.slashCommand.commandId) {
case 1: // /help
res.json({"text": "Contact bot helps you update your address book!"});
case 2: // /createContact
res.json(openDialog(event));
}
}
// If the Chat app doesn"t detect a slash command, it responds
// with a card that prompts the user to add a contact
else {
res.json({
"cardsV2": [{
"cardId": "addContact",
"card": {
"header": {
"title": "Rolodex",
"subtitle": "Manage your contacts!",
"imageUrl": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"imageType": "CIRCLE"
},
"sections": [
{
"widgets": [
{
"buttonList": {
"buttons": [
{
"text": "Add Contact",
"onClick": {
"action": {
"function": "openDialog",
"interaction": "OPEN_DIALOG"
}
}
}
]
}
}
]
}
]
}
}]
});
}
// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {
if (event.common.invokedFunction === "openDialog") {
res.json(openDialog(event));
}
if (event.common.invokedFunction === "openSequentialDialog") {
res.json(openSequentialDialog(event));
}
if (event.common.invokedFunction === "confirmDialogSuccess") {
res.json(confirmDialogSuccess(event));
}
}
};
/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
return {
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"textInput": {
"label": "Name",
"type": "SINGLE_LINE",
"name": "name"
}
},
{
"textInput": {
"label": "Address",
"type": "MULTIPLE_LINE",
"name": "address"
}
},
{
"decoratedText": {
"text": "Add to favorites",
"switchControl": {
"controlType": "SWITCH",
"name": "saveFavorite"
}
}
},
{
"decoratedText": {
"text": "Merge with existing contacts",
"switchControl": {
"controlType": "SWITCH",
"name": "mergeContact",
"selected": true
}
}
},
{
"buttonList": {
"buttons": [
{
"text": "Next",
"onClick": {
"action": {
"function": "openSequentialDialog"
}
}
}
]
}
}
]
}
]
}
}
}
}
};
};
/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openSequentialDialog(event) {
return {
"action_response": {
"type": "DIALOG",
"dialog_action": {
"dialog": {
"body": {
"sections": [
{
"header": "Add new contact",
"widgets": [
{
"textInput": {
"label": "Notes",
"type": "MULTIPLE_LINE",
"name": "notes"
}
},
{
"selectionInput": {
"type": "RADIO_BUTTON",
"label": "Contact type",
"name": "contactType",
"items": [
{
"text": "Work",
"value": "Work",
"selected": false
},
{
"text": "Personal",
"value": "Personal",
"selected": false
}
]
}
},
{
"buttonList": {
"buttons": [
{
"text": "Submit",
"onClick": {
"action": {
"function": "confirmDialogSuccess",
"parameters": [
{
"key": "confirmDialogSuccess",
"value": "confirmDialogSuccess"
}
]
}
}
}
]
},
"horizontalAlignment": "END"
}
]
}
]
}
}
}
}
};
}
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.contactName.stringInputs.value[0] === "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": {
"statusCode": "OK",
"userFacingMessage": "Don't forget to name your new contact!"
}
}
}
};
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
Apps Script
Este exemplo envia uma mensagem de card retornando JSON do cartão. Você também pode usar o Serviço de card do Apps Script.
Python
from typing import Any, Mapping
import flask
import functions_framework
@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
"""Responds to a MESSAGE event in Google Chat that includes the /createContact
slash command by opening a dialog.
Args:
req (flask.Request): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
if req.method == 'GET':
return 'Sorry, this function must be called from a Google Chat.'
request = req.get_json(silent=True)
if request.get('type') == 'CARD_CLICKED':
invoked_function = request.get('common', dict()).get('invokedFunction')
if invoked_function == 'open_dialog':
return open_dialog(request)
elif invoked_function == 'open_sequential_dialog':
return open_dialog(request)
elif invoked_function == "receive_dialog":
return receive_dialog(request)
else:
return {
'cardsV2': [{
'cardId': 'addContact',
'card': {
'header': {
'title': 'Rolodex',
'subtitle': 'Manage your contacts!',
'imageUrl': 'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
'imageType': 'CIRCLE'
},
'sections': [
{
'widgets': [
{
'buttonList': {
'buttons': [
{
'text': 'Add Contact',
'onClick': {
'action': {
'function': 'open_dialog',
'interaction': 'OPEN_DIALOG'
}
}
}
]
}
}
]
}
]
}
}]
}
def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a dialog in Google Chat.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return {
'action_response': {
'type': 'DIALOG',
'dialog_action': {
'dialog': {
'body': {
'sections': [
{
'header': 'Add new contact',
'widgets': [
{
'textInput': {
'label': 'Name',
'type': 'SINGLE_LINE',
'name': 'name'
}
},
{
'textInput': {
'label': 'Address',
'type': 'MULTIPLE_LINE',
'name': 'address'
}
},
{
'decoratedText': {
'text': 'Add to favorites',
'switchControl': {
'controlType': 'SWITCH',
'name': 'saveFavorite'
}
}
},
{
'decoratedText': {
'text': 'Merge with existing contacts',
'switchControl': {
'controlType': 'SWITCH',
'name': 'mergeContact',
'selected': True
}
}
},
{
'buttonList': {
'buttons': [
{
'text': 'Next',
'onClick': {
'action': {
'function': 'open_sequential_dialog'
}
}
}
]
}
}
]
}
]
}
}
}
}
}
def open_sequential_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
"""Opens a second dialog that lets users add more contact details.
Args:
request (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: open a Dialog in response to a card's button click.
"""
return {
'action_response': {
'type': 'DIALOG',
'dialog_action': {
'dialog': {
'body': {
'sections': [
{
'header': 'Add new contact',
'widgets': [
{
'textInput': {
'label': 'Notes',
'type': 'MULTIPLE_LINE',
'name': 'notes'
}
},
{
'selectionInput': {
'type': 'RADIO_BUTTON',
'label': 'Contact type',
'name': 'contactType',
'items': [
{
'text': 'Work',
'value': 'Work',
'selected': False
},
{
'text': 'Personal',
'value': 'Personal',
'selected': False
}
]
}
},
{
'buttonList': {
'buttons': [
{
'text': 'Submit',
'onClick': {
'action': {
'function': 'receive_dialog',
'parameters': [
{
'key': 'receiveDialog',
'value': 'receiveDialog'
}
]
}
}
}
]
},
'horizontalAlignment': 'END'
}
]
}
]
}
}
}
}
}
def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
"""Checks for a form input error, the absence of a "name" value, and returns
an error if absent. Otherwise, confirms successful receipt of a dialog.
Args:
event (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: the response.
"""
if event.get('common', dict()) \
.get('formInputs', dict()).get('contactName', dict()) \
.get('stringInputs').get('value', list()):
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'OK'
}
}
}
else:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': "Don't forget to name your new contact!"
}
}
}