Répondre aux commandes de l'application Google Chat

Cette page explique comment configurer et répondre aux commandes 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 slash, il n'est visible que par l'utilisateur et l'application Chat.

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

Types de commandes d'application Chat

Vous pouvez créer des commandes d'application Chat sous forme de commandes à barre oblique ou de commandes rapides. Pour découvrir et utiliser chaque type de commande, les utilisateurs procèdent comme suit :
  1. Commandes à barre oblique:les utilisateurs envoient des commandes sous forme de messages en saisissant une barre oblique (/), puis un texte prédéfini, tel que /about. Les applications de chat peuvent également nécessiter un texte d'argument pour la commande à barre oblique. Par exemple, la commande slash /search peut nécessiter un texte d'argument utilisé pour une requête de recherche.
  2. Commandes rapides:les utilisateurs utilisent des commandes en ouvrant le menu depuis la zone de réponse d'un message Chat. Pour utiliser une commande, il doit cliquer sur Ajouter , puis sélectionner une commande dans le menu.
Les images suivantes montrent comment les utilisateurs découvrent un menu de commandes avec barre oblique et de commandes rapides:
  • Un utilisateur découvre les commandes à barre oblique.
    Figure 1. Les utilisateurs découvrent et utilisent les commandes à barre oblique en saisissant une barre oblique / dans la zone de réponse, suivie du nom de la commande.
  • Un utilisateur consulte les commandes rapides dans le menu.
    Figure 2 Les utilisateurs découvrent et utilisent les commandes rapides dans le menu de la zone de réponse d'un message Chat.

Prérequis

Node.js

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.

Apps Script

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive dans Apps Script, suivez ce guide de démarrage rapide.

Python

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.

Java

Une application Google Chat pour laquelle les fonctionnalités interactives sont activées. Pour créer une application Chat interactive à l'aide d'un service HTTP, suivez ce guide de démarrage rapide.

Configurer la commande

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

  1. Créez un nom et une description pour 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 courte description s'affiche également sous le nom pour inviter les utilisateurs à en savoir plus sur l'utilisation de la commande:

Nom et description de la commande à barre oblique
Figure 3: Nom et description d'une commande à barre oblique.

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

Pour nommer une commande:

  • Utilisez des mots ou des 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 pour d'autres applications Chat, l'utilisateur doit filtrer les commandes similaires pour trouver et utiliser la vôtre.

Pour décrire une commande:

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

Configurer la commande dans la console Google Cloud

Pour créer une commande à barre oblique ou rapide, vous devez spécifier des informations sur la commande 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  > > 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, un nom, une description et un type de commande pour la commande:

    • ID de commande:nombre compris entre 1 et 1 000 utilisé par votre application Chat pour reconnaître la commande et renvoyer une réponse.
    • Nom:nom à afficher pour la commande. Les noms peuvent comporter jusqu'à 50 caractères et peuvent inclure des caractères spéciaux.
    • 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 ou Commande à barre oblique.
    • Si vous configurez une commande avec une barre oblique, saisissez une valeur pour le champ Nom de la commande avec barre oblique afin de spécifier ce que les utilisateurs doivent saisir pour appeler la commande. Doit commencer par une barre oblique, ne contenir que du texte et comporter au maximum 50 caractères. Exemple :/remindMe

  5. Facultatif: Si vous souhaitez que votre application Chat réponde à la commande par le biais d'une boîte de dialogue, cochez la case Ouvrir une boîte de dialogue.

  6. 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 de commande et le type de commande), afin que vous puissiez renvoyer une réponse appropriée.

Message privé concernant l'application Chat de Cymbal Labs. Le message indique que l'application Chat a été créée par Cymbal Labs et partage un lien vers la documentation et un lien permettant de contacter l'équipe d'assistance.
Une application Chat répond en privé à la commande à barre oblique /help pour expliquer comment obtenir de l'aide.

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:

Type de commande Type d'événement Métadonnées de commande
Commande à barre oblique MESSAGE message.slashCommand ou message.annotation.slashCommand
Commande rapide APP_COMMAND appCommandMetadata

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

Répondre à une commande à barre oblique

Le code suivant présente un exemple d'application Chat qui répond à la commande slash /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é:

Node.js

node/avatar-app/index.js
/**
 * 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.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs
// 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.'
      };
  }
}

Python

python/avatar-app/main.py
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 {}

Java

java/avatar-app/src/main/java/AvatarApp.java
/**
 * 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é lors de la configuration de 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 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é:

Node.js

node/avatar-app/index.js
/**
 * 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.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs
// 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.'
      };
  }
}

Python

python/avatar-app/main.py
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 {}

Java

java/avatar-app/src/main/java/AvatarApp.java
/**
 * 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é lors de la configuration de la commande dans la console Google Cloud.

Tester la commande

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

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