Rispondere ai comandi dell'app Google Chat

Questa pagina spiega come configurare e rispondere ai comandi come app Google Chat.

I comandi aiutano gli utenti a scoprire e utilizzare le funzionalità chiave di un'app di chat. Solo le app di chat possono vedere i contenuti di un comando. Ad esempio, se un utente invia un messaggio con un comando barra, il messaggio è visibile solo all'utente e all'app Chat.

Per decidere se creare comandi e per capire come progettare le interazioni degli utenti, consulta Definire tutti i percorsi degli utenti.

Tipi di comandi dell'app Chat

1. Comandi slash: gli utenti inviano comandi come messaggi digitando una barra (/) e poi un testo predefinito, ad esempio /about. Le app di chat possono anche richiedere il testo dell'argomento per il comando slash. Ad esempio, il comando barra /search può richiedere il testo dell'argomento utilizzato per una query di ricerca.
2. Comandi rapidi:gli utenti utilizzano i comandi aprendo il menu dall'area di risposta di un messaggio di Chat. Per utilizzare un comando, fa clic su Aggiungi e seleziona un comando dal menu.

Prerequisiti

Configura il comando

Questa sezione spiega come completare i seguenti passaggi per configurare il comando:

1. Crea un nome e una descrizione per il comando.
2. Configura il comando nella console Google Cloud.

Assegna un nome e una descrizione al comando

Il nome di un comando è ciò che gli utenti digitano o selezionano per richiamare l'app Chat. Sotto il nome viene visualizzata anche una breve descrizione per fornire agli utenti ulteriori informazioni su come utilizzare il comando:

Quando scegli un nome e una descrizione per il comando, tieni presente i seguenti consigli:

Per assegnare un nome a un comando:

• Utilizza parole o frasi brevi, descrittive e strategiche per rendere i comandi chiari per l'utente. Ad esempio, anziché il nome Create a reminder, utilizza Remind me.
• Valuta la possibilità di utilizzare un nome univoco o comune per il comando. Se il comando descrive una funzionalità o un'interazione tipica, puoi utilizzare un nome comune riconosciuto e previsto dagli utenti, ad esempio Settings o Feedback. In caso contrario, prova a utilizzare nomi di comandi unici, perché se il nome del comando è lo stesso per altre app di chat, l'utente deve filtrare i comandi simili per trovare e utilizzare il tuo.

Per descrivere un comando:

• Mantieni la descrizione breve e chiara in modo che gli utenti sappiano cosa aspettarsi quando utilizzano il comando.
• Comunica agli utenti se sono previsti requisiti di formattazione per il comando. Ad esempio, se crei un comando slash che richiede il testo dell'argomento, imposta la descrizione su qualcosa come Remind me to do [something] at [time].
• Comunica agli utenti se l'app Chat risponde a tutti gli utenti nello spazio o in privato all'utente che richiama il comando. Ad esempio, per il comando rapido About, puoi descriverlo come Learn about this app (Only visible to you).

Configura il comando nella console Google Cloud

Per creare un comando rapido o con barra, specifica le informazioni sul comando nella configurazione dell'app Chat per l'API Google Chat.

Per configurare un comando nell'API Google Chat:

1. Nella console Google Cloud, fai clic su Menu menu > API e servizi > API e servizi abilitati > API Google Chat

   Vai alla pagina dell'API Google Chat

2. Fai clic su Configurazione.

3. In Comandi, fai clic su Aggiungi un comando.

4. Inserisci un ID comando, un nome, una descrizione e un tipo di comando per il comando:

   • ID comando:un numero compreso tra 1 e 1000 utilizzato dalla tua app Chat per riconoscere il comando e restituire una risposta.
   • Nome:il nome visualizzato del comando. I nomi possono contenere fino a 50 caratteri e possono includere caratteri speciali.
   • Descrizione: il testo che descrive cosa fa il comando. Le descrizioni possono contenere fino a 50 caratteri e possono includere caratteri speciali.
   • Tipo di comando:seleziona Comando rapido o Comando slash.
   • Se stai configurando un comando slash, inserisci un valore per il campo Nome comando slash per specificare cosa devono digitare gli utenti per richiamare il comando. Deve iniziare con una barra, contenere solo testo e può avere fino a 50 caratteri. Ad esempio, /remindMe.

5. (Facoltativo) Se vuoi che l'app Chat risponda al comando con una finestra di dialogo, seleziona la casella di controllo Apri una finestra di dialogo.

6. Fai clic su Salva.

Il comando è ora configurato per l'app Chat.

Rispondere a un comando

Quando gli utenti utilizzano un comando, l'app Chat riceve un evento di interazione. Il payload dell'evento contiene metadati con dettagli sul comando invocato (incluso l'ID e il tipo di comando), in modo da poter restituire una risposta appropriata.

Per rispondere a ogni tipo di comando, devi gestire diversi tipi di eventi e oggetti di metadati nel payload dell'evento:

Per scoprire come rispondere a un comando con un messaggio, consulta le sezioni seguenti.

Rispondere a un comando slash

Il seguente codice mostra un esempio di app di chat che risponde al comando barra /about. L'app Chat gestice gli eventi di interazione MESSAGE, rileva se l'evento di interazione contiene l'ID comando corrispondente e restituisce un messaggio privato:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Sostituisci ABOUT_COMMAND_ID con l'ID comando specificato quando hai configurato il comando nella console Google Cloud.

Rispondere a un comando rapido

Il seguente codice mostra un esempio di app Chat che risponde al comando rapido Help. L'app Chat gestice gli eventi di interazione APP_COMMAND, rileva se l'evento di interazione contiene l'ID comando corrispondente e restituisce un messaggio privato:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Sostituisci HELP_COMMAND_ID con l'ID comando specificato quando hai configurato il comando nella console Google Cloud.

Testa il comando

Per testare il comando e il codice, consulta Testare le funzionalità interattive per le app Google Chat.

Per scoprire come testare e utilizzare il comando nell'interfaccia utente di Chat, consulta Utilizzare le app in Google Chat nella documentazione della guida di Google Chat.

Argomenti correlati

• Visualizza esempi di app Chat che utilizzano i comandi
• Invia un messaggio
• Aprire finestre di dialogo interattive