Responder a comandos do app Google Chat

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 ele e para o app Chat.

Para decidir se você deve 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 de chat geralmente exigem um texto de argumento para o comando de barra.

Crie um comando de barra se o app do Chat precisar de mais informações do usuário. Por exemplo, é possível criar um comando de barra chamado /search que é executado depois que o usuário insere uma frase para pesquisar, como /search receipts.
Comandos rápidos:os usuários abrem o menu na área de resposta de uma mensagem do Chat para usar os comandos. Para usar um comando, clique em Adicionar e selecione um comando no menu.

Crie um comando rápido 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:( prévia para desenvolvedores) Para usar as ações de mensagem, os usuários precisam passar o cursor sobre uma mensagem e clicar no menu de três pontos. Para usar um comando, eles abrem o menu de três pontos e selecionam uma opção.

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 e ações de mensagens:

Um usuário descobre um menu de comandos de barra e comandos rápidos. — Os usuários descobrem um menu de comandos de barra e comandos rápidos.

Um usuário descobre um menu de contexto de mensagem que contém uma ação de mensagem. — Os usuários descobrem um menu de contexto de mensagens com uma ação de mensagem "Lembre-me".

Pré-requisitos

HTTP

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

Apps Script

Um complemento do Google Workspace que amplia o Google Chat. 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.

Nomeie e descreva 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 orientar os usuários sobre como usar o comando:

Nome e descrição do comando de barra — O nome e a descrição de um comando de barra.

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

Para nomear um comando:

Use palavras ou frases curtas, descritivas e práticas para deixar os comandos claros para o usuário. Por exemplo, em vez do nome Create a reminder, use Remind 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 Settings ou Feedback. Caso contrário, tente usar nomes de comandos exclusivos. Se o nome do comando for o mesmo de outros apps de 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 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 Chat responde a todos no espaço ou de forma particular ao usuário que invoca o comando. Por exemplo, para o comando rápido About, você pode descrever como Learn 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

Acessar a página da API Google Chat
Clique em Configuração.
Em Configurações de conexão, acesse Gatilhos e especifique os detalhes do endpoint. Você precisa usar esse gatilho na seção a seguir para responder ao comando.
1. URL do endpoint HTTP: você pode especificar um URL de endpoint HTTP comum aqui. Como alternativa, para usar endpoints HTTP diferentes para acionadores diferentes, especifique o endpoint diretamente no campo Comando do app.
2. Apps Script: insira o ID de implantação do Apps Script. Por padrão, a função onAppCommand será invocada. Para usar outra função 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:
1. ID do comando:um número de 1 a 1.000 que seu app de chat usa para reconhecer o comando e retornar uma resposta.
2. Descrição:o texto que descreve como usar e formatar o comando. As descrições podem ter até 50 caracteres.
3. Tipo de comando:selecione Comando rápido, Comando de barra ou Ação de mensagem.
4. 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 ter até 50 caracteres. Por exemplo, /remindMe.
  - Nome da ação da mensagem:(prévia para desenvolvedores do ) O nome de exibição que os usuários selecionam no menu para invocar a ação da mensagem. Pode ter até 50 caracteres e incluir caracteres especiais. Por exemplo, Remind me.
Opcional: Mensagem de notificação de carregamento: (prévia para desenvolvedores do ) Uma mensagem de notificação de toast para mostrar ao usuário enquanto a ação da mensagem está sendo executada. Disponível apenas para ações de mensagens que não abrem caixas de diálogo.
Opcional: se 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, seu app Chat recebe um objeto de evento. O payload do evento contém um objeto appCommandPayload com detalhes sobre o comando 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 especificada ao configurar o gatilho do comando do app.

Mensagem privada para o
app de chat do Cymbal Labs. A mensagem diz que o
app de chat foi criado pelo 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 particular 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 do Chat processa objetos de evento de um gatilho Comando do app. Quando o payload de um objeto de evento contém um ID de comando de barra, o app Chat retorna a ação DataActions com um objeto createMessageAction:

Node.js

node/chat/avatar-app/index.js

Ver no GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/chat/avatar-app/main.py

Ver no GitHub

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

Ver no GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

Apps Script

apps-script/chat/avatar-app/Code.gs

Ver no GitHub

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.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.

Responder a uma ação de mensagem

O código a seguir mostra um exemplo de um app de chat que responde à ação de mensagem Me lembre com uma mensagem de texto. Para responder a ações de mensagens, 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 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 este exemplo de código, substitua REMIND_ME_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 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.

Conferir exemplos do app Chat que usam comandos
Enviar uma mensagem
Abrir caixas de diálogo interativas

Responder a comandos do app Google Chat Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Tipos de comandos do app Chat

Pré-requisitos

HTTP

Apps Script

Configurar o comando

Nomeie e descreva o comando

Para nomear um comando:

Para descrever um comando:

Configurar o comando no console do Google Cloud

Responder a um comando

Node.js

Python

Java

Apps Script

Responder a uma ação de mensagem

Node.js

Python

Java

Apps Script

Testar o comando

Temas relacionados

Responder a comandos do app Google Chat