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é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 dans l'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 exiger un texte d'argument pour la commande à barre oblique. Par exemple, la commande à barre oblique /search peut nécessiter un texte d'argument utilisé pour une requête de recherche.
  2. Commandes rapides:les utilisateurs peuvent utiliser les commandes en ouvrant le menu dans la zone de réponse d'un message Chat. Pour utiliser une commande, il clique sur Ajouter et sélectionne une commande dans le menu.
Les images suivantes montrent comment les utilisateurs découvrent un menu de commandes à 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 du menu situé dans la zone de réponse d'un message Chat.

Prérequis

HTTP

Apps Script

Configurer la commande

Cette section explique comment effectuer les étapes suivantes pour configurer une 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 correspond à ce que les utilisateurs saisissent ou sélectionnent pour appeler l'application Chat. Une brève description apparaît également sous le nom pour les inviter à 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 exploitables 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é type, vous pouvez utiliser un nom commun que les utilisateurs reconnaissent et attendent, tel que Settings ou Feedback. Sinon, essayez d'utiliser des noms de commande uniques. En effet, 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 le vôtre.

Pour décrire une commande:

  • La description doit être courte et claire pour que les utilisateurs sachent à quoi s'attendre lorsqu'ils utilisent la commande.
  • Indiquez aux utilisateurs s'il existe des exigences de mise en forme pour la commande. 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 en privé à 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 barre oblique ou une commande 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 : Pour configurer une commande à barre oblique 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 API Google Chat

  2. Cliquez sur Configuration

  3. Sous Paramètres de connexion, accédez à Déclencheurs et spécifiez les détails de votre point de terminaison. Vous devez utiliser ce déclencheur dans la section suivante pour répondre à la commande.

    1. URL de point de terminaison HTTP: vous pouvez spécifier une URL de point de terminaison HTTP courante ici. Pour utiliser différents points de terminaison HTTP pour différents déclencheurs, spécifiez le point de terminaison directement dans le champ Commande de l'application.
    2. Apps Script: saisissez l'ID de déploiement Apps Script. Par défaut, la fonction onAppCommand est appelée. Pour utiliser une autre fonction Apps Script, spécifiez le nom de la fonction personnalisée dans le champ Commande d'application.

  4. Sous Commandes, cliquez sur Ajouter une commande.

  5. Saisissez les informations suivantes concernant la commande:

    1. ID de commande:nombre compris entre 1 et 1 000 que votre application Chat utilise pour reconnaître la commande et renvoyer une réponse.
    2. Description:texte qui décrit comment utiliser et mettre en forme la commande. Les descriptions peuvent comporter jusqu'à 50 caractères.
    3. Type de commande:sélectionnez Commande rapide ou Commande à barre oblique.
    4. Spécifiez un nom pour la commande rapide ou la commande à barre oblique :
      • Quick command name (Nom de la commande rapide) : nom à afficher que les utilisateurs sélectionnent dans le menu pour appeler la commande. Il peut comporter jusqu'à 50 caractères et inclure des caractères spéciaux. Exemple :Remind me
      • Nom de la commande à barre oblique:texte que l'utilisateur saisit pour appeler la commande dans un message. Doit commencer par une barre oblique, ne contenir que du texte et comporter jusqu'à 50 caractères. Exemple :/remindMe

  6. Facultatif: Si vous souhaitez que votre application Chat répond à la commande avec une boîte de dialogue, cochez la case Open a dialog (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 objet événement. La charge utile de l'événement contient un objet appCommandPayload avec des détails sur la commande appelée (y compris l'ID et le type de commande) afin que vous puissiez renvoyer une réponse appropriée. L'objet événement est envoyé au point de terminaison HTTP ou à la fonction Apps Script que vous avez spécifié lors de la configuration du déclencheur de commande d'application.

Message privé pour 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 pour contacter l'équipe d'assistance.
Une application Chat répond en privé à la commande à barre oblique /help pour vous expliquer comment obtenir de l'aide.

Le code suivant montre un exemple d'application Chat qui répond à la commande à barre oblique /about par un message textuel. Pour répondre aux commandes à barre oblique, l'application Chat gère les objets d'événement à partir d'un déclencheur de commande d'application. Lorsque la charge utile d'un objet événement contient un ID de commande à barre oblique, l'application Chat renvoie l'action DataActions avec un objet createMessageAction:

Node.js 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

Apps Script 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

Pour utiliser cet exemple de code, remplacez ABOUT_COMMAND_ID par l'ID de commande que vous avez spécifié lors de la configuration de la commande dans l'API Chat.

Tester la commande

Pour tester la commande et le code, consultez Tester les fonctionnalités interactives pour les 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.