Répondre aux commandes de l'application Google Chat

Cette page explique comment configurer des commandes et y répondre en tant qu'application Google Chat.

Les commandes aident les utilisateurs à découvrir et à utiliser les principales fonctionnalités d'une application Chat. Seules les applications Chat peuvent voir le contenu d'une commande. Par exemple, si un utilisateur envoie un message avec une commande à barre oblique, le message n'est visible que par l'utilisateur et l'application Chat.

Pour déterminer si vous devez créer des commandes et comprendre comment concevoir les interactions utilisateur, consultez Définir tous les parcours utilisateur.

Types de commandes de l'application Chat

1. Commandes à barre oblique : les utilisateurs peuvent sélectionner une commande à barre oblique dans le menu ou saisir une barre oblique (/), puis un texte prédéfini, tel que /about. Les applications de chat nécessitent généralement un texte d'argument pour la commande à barre oblique.

   Créez une commande à barre oblique si votre application Chat nécessite une saisie supplémentaire de la part de l'utilisateur. Par exemple, vous pouvez créer une commande à barre oblique appelée /search qui s'exécute après que l'utilisateur a saisi une expression à rechercher, comme /search receipts.

2. Commandes rapides : les utilisateurs utilisent les commandes en ouvrant le menu depuis la zone de réponse d'un message Chat. Pour utiliser une commande, il doit cliquer sur Ajouter et sélectionner une commande dans le menu.

   Créez une commande rapide si votre application Chat peut répondre immédiatement à l'utilisateur, sans attendre d'autres informations. Par exemple, vous pouvez créer une commande rapide appelée Image aléatoire qui répond immédiatement avec une image.

3. Actions sur les messages : (science Aperçu développeur) Pour effectuer des actions sur les messages, les utilisateurs doivent pointer sur un message et cliquer sur le menu à trois points. Pour utiliser une commande, il ouvre le menu à trois points et en sélectionne une.

   Créez une action de message si votre application Chat peut effectuer des actions en fonction du contexte d'un message.

Les images suivantes montrent comment les utilisateurs découvrent le menu des commandes à barre oblique et rapides, ainsi que les actions sur les messages :

Prérequis

Configurer la commande

Cette section explique comment effectuer les étapes suivantes pour configurer la commande :

1. Donnez un nom et une description à la commande.
2. Configurez la commande dans la console Google Cloud.

Nommez et décrivez la commande

Le nom d'une commande est ce que les utilisateurs saisissent ou sélectionnent pour appeler l'application Chat. Une brève description s'affiche également sous le nom pour inciter les utilisateurs à utiliser la commande :

Lorsque vous choisissez un nom et une description pour votre commande, tenez compte des recommandations suivantes :

Pour nommer une commande :

• Utilisez des mots ou expressions courts, descriptifs et pratiques pour que les commandes soient claires pour l'utilisateur. Par exemple, au lieu du nom Create a reminder, utilisez Remind me.
• Envisagez d'utiliser un nom unique ou commun pour votre commande. Si votre commande décrit une interaction ou une fonctionnalité typique, vous pouvez utiliser un nom commun que les utilisateurs reconnaissent et attendent, comme Settings ou Feedback. Sinon, essayez d'utiliser des noms de commandes uniques, car si le nom de votre commande est le même que celui d'autres applications Chat, l'utilisateur devra filtrer les commandes similaires pour trouver et utiliser la vôtre.

Pour décrire une commande :

• Veillez à ce que la description soit courte et claire pour que les utilisateurs sachent à quoi s'attendre lorsqu'ils utilisent la commande.
• Indiquez aux utilisateurs si la commande doit respecter des exigences de mise en forme. Par exemple, si vous créez une commande à barre oblique qui nécessite un texte d'argument, définissez la description sur Remind me to do [something] at [time].
• Indiquez aux utilisateurs si l'application Chat répond à tous les membres de l'espace ou privément à l'utilisateur qui appelle la commande. Par exemple, pour la commande rapide About, vous pouvez la décrire comme suit : Learn about this app (Only visible to you).

Configurer la commande dans la console Google Cloud

Pour créer une commande à barre oblique, une commande rapide ou une action sur un message, vous devez spécifier des informations sur la commande ou l'action dans la configuration de votre application Chat pour l'API Google Chat.

Pour configurer une commande dans l'API Google Chat, procédez comme suit :

1. Dans la console Google Cloud, cliquez sur Menu menu > API et services > API et services activés > API Google Chat.

   Accéder à la page de l'API Google Chat

2. Cliquez sur Configuration

3. Sous Commandes, cliquez sur Ajouter une commande.

4. Saisissez un ID de commande, une description, un type de commande et un nom pour la commande :

   • ID de la commande : nombre compris entre 1 et 1 000 que votre application Chat utilise pour reconnaître la commande et renvoyer une réponse.
   • Description : texte décrivant l'action de la commande. Les descriptions peuvent comporter jusqu'à 50 caractères et inclure des caractères spéciaux.
   • Type de commande : sélectionnez Commande rapide, Commande à barre oblique ou Action de message.
   • Spécifiez un nom pour la commande :
     • Nom de la commande rapide : nom à afficher que les utilisateurs sélectionnent dans le menu pour appeler la commande. Il peut contenir jusqu'à 50 caractères et inclure des caractères spéciaux. Exemple :Remind me
     • Nom de la commande à barre oblique : texte que les utilisateurs saisissent pour appeler la commande dans un message. Doit commencer par une barre oblique, ne contenir que du texte et ne pas dépasser 50 caractères. Exemple :/remindMe
     • Nom de l'action du message : (science Preview développeur) Nom à afficher que les utilisateurs sélectionnent dans le menu pour appeler l'action du message. Il peut contenir jusqu'à 50 caractères et inclure des caractères spéciaux. Par exemple, Remind me.

5. Facultatif : Message de notification de chargement : (science Preview développeur) Message de notification toast à afficher à l'utilisateur pendant l'exécution de l'action de message. Disponible uniquement pour les actions de message qui n'ouvrent pas de boîtes de dialogue.

6. Facultatif : Si vous souhaitez que votre application Chat réponde à la commande avec une boîte de dialogue, cochez la case Ouvrir une boîte de dialogue.

7. Cliquez sur Enregistrer.

La commande est maintenant configurée pour l'application Chat.

Répondre à une commande

Lorsque les utilisateurs utilisent une commande, votre application Chat reçoit un événement d'interaction. La charge utile de l'événement contient des métadonnées avec des informations sur la commande qui a été appelée (y compris l'ID et le type de commande), afin que vous puissiez renvoyer une réponse appropriée.

Pour répondre à chaque type de commande, vous devez gérer différents types d'événements et d'objets de métadonnées dans la charge utile de l'événement :

Pour savoir comment répondre à une commande avec un message, consultez les sections suivantes.

Répondre à une commande à barre oblique

Le code suivant montre un exemple d'application Chat qui répond à la commande à barre oblique /about. L'application Chat gère les événements d'interaction MESSAGE, détecte si l'événement d'interaction contient l'ID de commande correspondant et renvoie un message privé :

/**
 * 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;
  }
}

Remplacez ABOUT_COMMAND_ID par l'ID de commande que vous avez spécifié lorsque vous avez configuré la commande dans la console Google Cloud.

Répondre à une commande rapide

Le code suivant montre un exemple d'application Chat qui répond à la commande rapide Help (Aide). L'application Chat gère les événements d'interaction APP_COMMAND, détecte si l'événement d'interaction contient l'ID de commande correspondant et renvoie un message privé :

/**
 * 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.'
      });
  }
}

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_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;
  }
}

Remplacez HELP_COMMAND_ID par l'ID de commande que vous avez spécifié lorsque vous avez configuré la commande dans la console Google Cloud.

Répondre à une action de message

Le code suivant montre un exemple d'application Chat qui répond à l'action de message Me rappeler. L'application Chat gère les événements d'interaction APP_COMMAND, détecte si l'événement d'interaction contient l'ID de commande correspondant et renvoie un message privé :

/**
 * 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}"`
    });
  }
}

/**
 * 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 };
  }
}

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}"'
        }

/**
 * 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());
    }
  }
}

Remplacez REMIND_ME_COMMAND_ID par l'ID de commande que vous avez spécifié lorsque vous avez configuré la commande dans la console Google Cloud.

Tester la commande

Pour tester la commande et le code, consultez Tester les fonctionnalités interactives des applications Google Chat.

Pour savoir comment tester et utiliser la commande dans l'interface utilisateur Chat, consultez Utiliser des applications dans Google Chat dans la documentation d'aide de Google Chat.

Articles associés

• Afficher des exemples d'applications Chat qui utilisent des commandes
• Envoyer un message
• Ouvrir des boîtes de dialogue interactives