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éterminer si vous devez créer des commandes et comprendre comment concevoir les interactions utilisateur, consultez Définir tous les parcours utilisateur.

Types de commandes de l'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 (/), puis un texte prédéfini, tel que /about. Les applications de 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 saisie supplémentaire de la part 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 les commandes en ouvrant le menu depuis la zone de réponse d'un message Chat. Pour utiliser une commande, il doit cliquer sur Ajouter et sélectionner une commande dans le menu.

    Créez une commande rapide si votre application Chat peut répondre immédiatement à l'utilisateur, sans attendre d'autres informations. 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 : ( Aperçu développeur) Pour effectuer des actions sur les messages, les utilisateurs doivent pointer sur un message et cliquer sur le menu à trois points. Pour utiliser une commande, il ouvre le menu à trois points et en sélectionne une.

    Créez une action de message si votre application Chat peut effectuer des actions en fonction du contexte d'un 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 de message "Me rappeler".

Prérequis

HTTP

Module complémentaire Google Workspace qui étend Google Chat. Pour en créer un, suivez le 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 effectuer les étapes suivantes pour configurer une commande :

  1. Donnez un nom et une description à 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 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 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 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 pour que les utilisateurs sachent à quoi s'attendre lorsqu'ils utilisent la commande.
  • Indiquez aux utilisateurs si la commande doit respecter 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 Remind me to do [something] at [time].
  • Indiquez aux utilisateurs si l'application Chat répond à tous les membres de l'espace ou privément à 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 un message, vous devez spécifier 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 utiliser différents points de terminaison HTTP pour différents déclencheurs. Pour ce faire, 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 sera 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 la 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 de message.
    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. Il peut contenir jusqu'à 50 caractères et inclure des caractères spéciaux. 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 ne pas dépasser 50 caractères. Exemple :/remindMe
      • Nom de l'action du message : ( Preview développeur) Nom à afficher que les utilisateurs sélectionnent dans le menu pour appeler l'action du message. Il peut contenir 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 de message. Disponible uniquement pour les actions de message 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

Lorsqu'un utilisateur utilise 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 qui a été 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 lorsque vous avez configuré le déclencheur decommande 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.

L'exemple de code suivant montre une 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 slash, 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é lorsque vous avez configuré la commande dans l'API Chat.

Répondre à une action de message

Le code suivant montre un exemple d'application Chat qui répond à l'action de message Me 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 de message, l'application Chat renvoie l'action DataActions avec un objet createMessageAction :

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é lorsque vous avez configuré 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 d'aide de Google Chat.