Répondre aux commandes à barre oblique dans Google Chat

Cette page explique comment configurer une application Google Chat pour qu'elle réponde aux commandes slash.

Dans Google Chat, les modules complémentaires apparaissent aux utilisateurs comme des applications Google Chat. Pour en savoir plus, consultez la présentation de l'extension Google Chat.

Une commande à barre oblique est un moyen courant d'appeler et d'interagir avec une application Chat. Les commandes à barre oblique aident également les utilisateurs à découvrir et à utiliser les principales fonctionnalités d'une application Chat. Pour décider si vous devez configurer des commandes à barre oblique et pour comprendre comment concevoir des interactions utilisateur, consultez la section Définir tous les parcours utilisateur dans la documentation de l'API Chat.

Comment les utilisateurs utilisent-ils les commandes à barre oblique ?

Pour utiliser une commande à barre oblique, les utilisateurs doivent saisir une barre oblique (/), puis une courte commande textuelle, comme /about pour obtenir des informations sur l'application Chat. Les utilisateurs peuvent découvrir les commandes à barre oblique disponibles en saisissant une barre oblique dans Google Chat, ce qui affiche une fenêtre listant les commandes disponibles pour l'application Chat:

Lorsqu'un utilisateur envoie un message contenant une commande à barre oblique, il n'est visible que par l'utilisateur et l'application Chat. Si vous avez configuré votre application Chat pour qu'elle soit ajoutée à des espaces avec plusieurs personnes, vous pouvez envisager de répondre à la commande à barre oblique en privé, afin de préserver la confidentialité de l'interaction entre l'utilisateur et l'application Chat.

Par exemple, pour en savoir plus sur une application Chat découverte dans un espace, les utilisateurs peuvent utiliser des commandes telles que /about ou /help. Pour éviter d'envoyer une notification à tous les autres membres de l'espace, l'application Chat peut répondre en privé avec des informations sur l'utilisation de l'application Chat et sur l'assistance.

Prérequis

Configurer une commande à barre oblique

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

1. Attribuez un nom à votre commande slash.
2. Configurez la commande à barre oblique dans l'API Google Chat.

Nommez votre commande à barre oblique

Le nom d'une commande à barre oblique est ce que les utilisateurs saisissent dans un message Chat pour appeler l'application Chat. Une courte description s'affiche également sous le nom pour indiquer aux utilisateurs comment utiliser la commande:

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

• Pour nommer votre commande à barre oblique:

  • Utilisez des mots ou des expressions courts, descriptifs et pratiques pour rendre les commandes claires et simples pour l'utilisateur. Par exemple, au lieu de /createAReminder, utilisez /remindMe.
  • Si votre commande contient plusieurs mots, aidez les utilisateurs à la lire en utilisant des minuscules pour le premier mot, puis en mettant la première lettre des mots supplémentaires en majuscule. Par exemple, au lieu de /updatecontact, utilisez /updateContact.
  • Déterminez si vous souhaitez 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 commande 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 votre commande à barre oblique:

  • Réduisez la description à quelques mots clairs pour que les utilisateurs sachent à quoi s'attendre lorsqu'ils appellent la commande.
  • Indiquez aux utilisateurs si des exigences de mise en forme s'appliquent à la commande. Par exemple, si vous créez une commande /remindMe qui nécessite du 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 en privé à l'utilisateur qui appelle la commande. Par exemple, pour la commande slash /about, vous pouvez la décrire comme Learn about this app (Only visible to you).

Configurer votre commande à barre oblique dans l'API Google Chat

Pour créer une commande avec un slash, 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 avec un slash 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 Paramètres avancés, accédez à Déclencheurs et vérifiez que le champ MESSAGE 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 slash.

4. Sous Commandes à barre oblique, cliquez sur Ajouter une commande à barre oblique.

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

   1. Nom:nom à afficher pour la commande et ce que les utilisateurs saisissent pour appeler votre application. Doit commencer par une barre oblique, ne contenir que du texte et comporter jusqu'à 50 caractères.
   2. Description:texte qui décrit comment utiliser et mettre en forme la commande. Les descriptions peuvent comporter jusqu'à 50 caractères.
   3. ID de commande:nombre compris entre 1 et 1 000 utilisé par votre application Chat pour reconnaître la commande à barre oblique et renvoyer une réponse.

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 à barre oblique est maintenant configurée pour l'application Chat.

Répondre à une commande à barre oblique

Lorsque les utilisateurs créent un message Chat, votre application Chat reçoit un objet d'événement contenant des informations sur le message. L'objet d'événement contient une charge utile avec des informations sur la commande utilisée dans le message (y compris l'ID de commande), afin que vous puissiez renvoyer une réponse appropriée.

Pour répondre à une commande slash, vous devez implémenter le déclencheur de message afin que votre application Chat puisse gérer tous les objets d'événement contenant des métadonnées de commande slash.

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 slash, l'application Chat gère les objets d'événement à partir d'un déclencheur Message. 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:

// 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 messages 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 chatMessage = req.body.chat.messagePayload.message;

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

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

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

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

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 slash dans l'API Chat.