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

HTTP Apps Script

Configurer la commande

Cette section explique comment suivre 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 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 : o Pour configurer une commande avec un slash 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 Paramètres avancés, accédez à Déclencheurs et vérifiez que le champ Commande de l'application contient un déclencheur, tel qu'un point de terminaison HTTP ou une fonction Apps Script. Vous devez utiliser ce déclencheur dans la section suivante pour répondre à la commande.

  4. Sous Commandes, cliquez sur Ajouter une commande.

  5. Saisissez les informations suivantes sur la commande:

    1. 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.
    2. Type de commande:sélectionnez Commande rapide ou Commande à barre oblique.
    3. 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
    4. Nom:nom convivial de la commande. Les noms peuvent comporter jusqu'à 50 caractères et peuvent inclure des caractères spéciaux.
    5. Description:texte qui décrit comment utiliser et mettre en forme la commande. Les descriptions peuvent comporter jusqu'à 50 caractères.

  6. 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.

  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 d'événement. La charge utile de l'événement contient un objet appCommandPayload avec des informations sur la commande appelée (y compris l'ID de commande et le type de commande), afin que vous puissiez renvoyer une réponse appropriée. L'objet d'événement est envoyé au point de terminaison HTTP ou à la fonction Apps Script que vous avez spécifiés lorsque vous avez configuré le déclencheur Commande de l'application.

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.

Le code suivant montre un exemple d'application Chat qui répond à la commande slash /about par un message texte. 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 d'événement contient un ID de commande à barre oblique, l'application Chat renvoie l'action DataActions avec un objet createMessageAction:

Node.js 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;

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

// 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é lorsque vous avez configuré la commande dans l'API Chat.

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.