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 fonctionnalités clé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 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, de commandes rapides ou d'actions liées aux messages. Pour utiliser chaque type de commande, les utilisateurs peuvent procéder comme suit :

Commandes à barre oblique : les utilisateurs peuvent sélectionner une commande à barre oblique dans le menu ou saisir une barre oblique (/) suivie d'un texte prédéfini, tel que /about. Les applications 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 entrée supplémentaire 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.
Commandes rapides : les utilisateurs utilisent des commandes en ouvrant le menu dans la zone de réponse d'un message Chat. Pour utiliser une commande, ils cliquent sur Ajouter et sélectionnent une commande dans le menu.

Créez une commande rapide si votre application Chat peut répondre immédiatement à l'utilisateur, sans attendre d'entrée supplémentaire. Par exemple, vous pouvez créer une commande rapide appelée Image aléatoire qui répond immédiatement avec une image.
Actions liées aux messages ( aperçu pour les développeurs) les utilisateurs utilisent des actions liées aux messages en plaçant le curseur sur un message et cliquant sur le menu à trois points. Pour utiliser une commande, ils ouvrent le menu à trois points et sélectionnent une commande dans le menu.

Créez une action liée aux messages si votre application Chat peut effectuer des actions based on the context of a message.

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

Un utilisateur découvre un menu de commandes à barre oblique et de commandes rapides. — Les utilisateurs découvrent un menu de commandes à barre oblique et de commandes rapides.

Un utilisateur découvre un menu contextuel de message contenant une action de message. — Les utilisateurs découvrent un menu contextuel de message contenant une action liée au message "Me le rappeler".

Prérequis

Node.js

Une application Google Chat qui reçoit des événements d'interaction et y répond. 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 qui reçoit des événements d'interaction et y répond. Pour créer une application Chat interactive dans Apps Script, suivez ce guide de démarrage rapide.

Python

Une application Google Chat qui reçoit des événements d'interaction et y répond. 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 qui reçoit des événements d'interaction et y répond. 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 effectuer les étapes suivantes pour configurer la commande :

Créez un nom et une description pour la commande.
Configurez la commande dans la console Google Cloud.

Nommer et décrire 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 :

Nom et description de la commande à barre oblique — 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é typique, 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 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 afin 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 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 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 liée aux messages, vous spécifiez 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 :

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
Cliquez sur Configuration.
Sous Commandes, cliquez sur Ajouter une commande.
Saisissez un ID de commande, une description, un type de commande et un nom pour la commande :
- 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.
- Description : texte décrivant ce que fait 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 liée au 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. Peut comporter jusqu'à 50 caractères et inclure des caractères spéciaux. Par 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 comporter jusqu'à 50 caractères. Par exemple, /remindMe.
  - Nom de l'action liée au message (aperçu pour les développeurs ) nom à afficher que les utilisateurs sélectionnent dans le menu pour appeler l'action liée au message. Peut comporter jusqu'à 50 caractères et inclure des caractères spéciaux. Par exemple, Remind me.
Facultatif : Message de notification de chargement: ( aperçu pour les développeurs) message de notification toast à afficher à l'utilisateur pendant l'exécution de l'action liée au message. Disponible uniquement pour les actions liées aux messages qui n'ouvrent pas de boîtes de dialogue.
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.
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 appelée (y compris l'ID et le type de commande), afin que vous puissiez renvoyer une réponse appropriée.

Message privé pour l'application de chat Cymbal Labs. Le message indique que l'application de 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 expliquer comment obtenir de l'aide.

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

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

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é :

Node.js

node/avatar-app/index.js

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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

Afficher sur GitHub

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

Python

python/avatar-app/main.py

Afficher sur GitHub

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

Afficher sur GitHub

/**
 * 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.

Répondre à une action liée au message

Le code suivant montre un exemple d'application Chat qui répond à l'action liée au message Me le 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é :

Node.js

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

Apps Script

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

Python

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

Java

/**
 * 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é lors de la configuration de 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.

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

Répondre aux commandes de l'application Google Chat Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Types de commandes d'application Chat

Prérequis

Node.js

Apps Script

Python

Java

Configurer la commande

Nommer et décrire la commande

Pour nommer une commande :

Pour décrire une commande :

Configurer la commande dans la console Google Cloud

Répondre à une commande

Répondre à une commande à barre oblique

Node.js

Apps Script

Python

Java

Répondre à une commande rapide

Node.js

Apps Script

Python

Java

Répondre à une action liée au message

Node.js

Apps Script

Python

Java

Tester la commande

Articles associés

Répondre aux commandes de l'application Google Chat