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 sur les messages. Pour utiliser chaque type de commande, les utilisateurs peuvent procéder comme suit :

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

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

  3. Actions sur les messages ( Preview développeur) les utilisateurs utilisent des actions sur les messages en plaçant le curseur sur un message et en 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 sur les 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 sur les 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 sur les messages "Me le rappeler".

Prérequis

HTTP

Module complémentaire Google Workspace qui étend Google Chat. Pour en créer un, suivez le guide de démarrage rapide HTTP.

Apps Script

Module complémentaire Google Workspace qui étend Google Chat. Pour en créer un, suivez le guide de démarrage rapide Apps Script.

Configurer la commande

Cette section explique comment procéder comme suit pour configurer une commande :

  1. Créez un nom et une description pour la commande.
  2. 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 si la commande est soumise à des exigences de mise en forme. 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 sur les 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 :

  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 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 du point de terminaison HTTP : vous pouvez spécifier une URL de point de terminaison HTTP commune ici. Vous pouvez également spécifier le point de terminaison directement dans le champ Commande d'application pour utiliser différents points de terminaison HTTP pour différents déclencheurs.
    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 sur 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 décrivant comment utiliser et mettre en forme la commande. Les descriptions peuvent comporter jusqu'à 50 caractères.
    3. Type de commande : sélectionnez Commande rapide, Commande à barre oblique ou Action sur les messages.
    4. 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 sur les messages ( Preview développeur) nom à afficher que les utilisateurs sélectionnent dans le menu pour appeler l'action sur les messages. Peut comporter jusqu'à 50 caractères et inclure des caractères spéciaux. Par exemple, Remind me.

  6. Facultatif : Message de notification de chargement: ( Preview développeur) message de notification toast à afficher à l'utilisateur pendant l'exécution de l'action sur les messages. Disponible uniquement pour les actions sur les messages qui n'ouvrent pas de boîtes de dialogue.

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

  8. 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 appCommandPayload objet 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 d'événement est envoyé au point de terminaison HTTP ou à la fonction Apps Script que vous avez spécifiés lors de la configuration du déclencheur Commande d'application.

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.

Le code suivant montre un exemple d'application Chat qui répond à la commande à barre oblique /about avec 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 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

node/chat/avatar-app/index.js
// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/chat/avatar-app/main.py
# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java
// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

Apps Script

apps-script/chat/avatar-app/Code.gs
// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.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.

Répondre à une action sur les messages

Le code suivant montre un exemple d'application Chat qui répond à l'action sur les messages Me le rappeler avec un message texte. Pour répondre aux actions sur les messages, l'application Chat gère les objets d'événement à partir d'un déclencheur Commande d'application. Lorsque la charge utile d'un objet d'événement contient un ID de commande d'action sur les messages, l'application Chat renvoie l'action DataActions avec un createMessageAction objet :

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 onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return res.json({
      "hostAppDataAction": {
        "chatDataAction": {
          "createMessageAction": {
            "message": {
              "text": `Setting a reminder for message: "${messageText}"`
            }
          }
        }
      }
    });
  }
}

Python

def on_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.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.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 = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "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 onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.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 = payload.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);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

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.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

Pour utiliser cet exemple de code, remplacez REMIND_ME_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 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 de l'aide Google Chat.