Créer des interfaces Google Chat

Cette page explique comment créer des interfaces utilisateur (UI) pour les modules complémentaires Google Workspace qui étendent Google Chat.

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.

Pour créer des interfaces pour les applications Chat, vous utilisez les composants complémentaires suivants:

  • Déclencheurs: façons dont les utilisateurs de Google Chat peuvent appeler une application Chat, par exemple en l'ajoutant à un espace ou en lui envoyant un message.
  • Objets d'événement: données que les applications Chat reçoivent à partir de déclencheurs ou d'interactions avec l'UI.
  • Actions: façons dont les applications Chat peuvent répondre aux interactions, comme envoyer des messages ou renvoyer une interface utilisateur basée sur des fiches.
L'application Chat reçoit un objet d'événement à partir d'un déclencheur "Ajout à un espace"
Figure 1: Lorsqu'un utilisateur ajoute une application Chat à un espace, le déclencheur Added to space (Ajout à l'espace) se déclenche et envoie un objet d'événement. Pour répondre par un message, l'application Chat gère l'objet d'événement et renvoie une action qui crée le message.

Les applications Chat peuvent créer et afficher des fiches dans les interfaces suivantes:

  • Messages pouvant contenir du texte, des fiches statiques ou interactives, et des boutons.
  • Boîtes de dialogue, qui sont des cartes qui s'ouvrent dans une nouvelle fenêtre et qui invitent généralement les utilisateurs à envoyer des informations.
  • Aperçus des liens, qui sont des fiches qui présentent des informations sur un service externe.

Déclencheurs

Cette section explique les déclencheurs utilisés par les modules complémentaires Google Workspace dans Chat.

Les déclencheurs sont les moyens spécifiques par lesquels les utilisateurs appellent une application Chat à l'aide de l'interface utilisateur de Chat, par exemple en utilisant des mentions @ou des commandes d'application.

Le tableau suivant présente les déclencheurs Chat, une description et la réponse habituelle des applications Chat:

Déclencheur Description Réponse type
Ajouté à l'espace

Un utilisateur ajoute l'application Chat à un espace, ou un administrateur Google Workspace installe l'application Chat dans des espaces de messages privés pour les utilisateurs de son organisation. Pour en savoir plus sur les applications Chat installées par les administrateurs, consultez Installer des applications Marketplace dans votre domaine dans la documentation d'aide Google Workspace pour les administrateurs.

 L'application Chat envoie un message d'intégration qui explique son fonctionnement et la façon dont les utilisateurs de l'espace peuvent interagir avec elle.
Message

Un utilisateur interagit avec l'application Chat dans un message de l'une des manières suivantes:

  • Envoyer un message dans un espace de message privé (MP) avec l'application Chat
  • @mentionne l'application Chat dans n'importe quel type d'espace.
  • Envoie un message contenant un lien correspondant au format d'URL pour les aperçus de liens.
  • Saisit du texte dans le menu de sélection multiple d'un widget selectionInput.
 L'application Chat répond en fonction du contenu du message. Par exemple, une application Chat répond à la commande /about avec un message expliquant les tâches que l'application Chat peut effectuer.
Exclu de l'espace

Un utilisateur supprime l'application Chat d'un espace ou un administrateur Google Workspace désinstalle l'application Chat pour un utilisateur de son organisation.

Les utilisateurs ne peuvent pas supprimer les applications Chat installées par leur administrateur. Si un utilisateur a déjà installé l'application Chat, elle reste installée, que l'administrateur Google Workspace tente de la désinstaller ou non.

 L'application Chat supprime toutes les notifications entrantes configurées pour l'espace (par exemple, la suppression d'un webhook) et libère tout espace de stockage interne. Les applications Chat ne peuvent pas répondre à ce déclencheur par message, car elles ne sont plus membres de l'espace.
Commande de l'application

Un utilisateur utilise une commande rapide ou une commande à barre oblique depuis l'application Chat.

 L'application Chat répond à la commande. (par exemple, répond avec un message ou ouvre une boîte de dialogue)

Contrairement aux autres modules complémentaires Google Workspace, vous devez configurer les fonctions de rappel pour ces déclencheurs à l'aide de l'API Google Chat. Pour obtenir des conseils, consultez Configurer une application Google Chat.

Pour répondre à un déclencheur, consultez les guides suivants:

Objets d'événement

Cette section définit et explique tous les éléments des objets d'événement Chat. Pour en savoir plus, consultez la section Objets d'événement.

Objet d'événement
commonEventObject object (CommonEventObject)
Objet contenant des informations communes à tous les objets d'événement, quelle que soit l'application hôte.
chat object (Chat)
Objet contenant toutes les informations sur les interactions Chat.

Chat

Chat
chat.user object (User)
Utilisateur Chat ayant interagi avec l'application Chat.
chat.space object (Space)
Espace Chat dans lequel un utilisateur a interagi avec l'application Chat.
chat.eventTime

string (Timestamp format)

Heure à laquelle l'interaction s'est produite.

Champ d'union payload.

payload ne peut être qu'un des éléments suivants :
chat.messagePayload

object (MessagePayload)

Charge utile que les applications Chat reçoivent d'un déclencheur de message.
chat.addedToSpacePayload

object (AddedToSpacePayload)

Charge utile que les applications Chat reçoivent d'un déclencheur Ajout à l'espace.
chat.removedFromSpacePayload

object (RemovedFromSpacePayload)

Charge utile que les applications Chat reçoivent d'un déclencheur Supprimé de l'espace.
chat.buttonClickedPayload

object (ButtonClickedPayload)

Charge utile que les applications Chat reçoivent lorsque les utilisateurs cliquent sur un bouton à partir d'un message ou d'une fiche. Si un utilisateur clique sur un bouton pour envoyer des informations, l'objet commonEventObject.formInputs contient les valeurs collectées auprès de l'utilisateur. Pour en savoir plus, consultez Collecter des informations auprès des utilisateurs de Google Chat.
chat.widgetUpdatedPayload

object (WidgetUpdatedPayload)

Charge utile que les applications Chat reçoivent lorsque les utilisateurs saisissent du texte dans le menu de sélection multiple d'un widget selectionInput. Les applications de chat peuvent utiliser cet objet d'événement pour renseigner les éléments suggérés à partir d'une source de données dynamique. Par exemple, pour renseigner des demandes d'assistance à partir d'une source de données externe, une application Chat peut interroger la source de données en fonction de ce que l'utilisateur saisit dans le menu, puis renvoyer les demandes d'assistance correspondantes en tant qu'éléments sélectionnables.

L'objet CommonEventObject.parameters['autocomplete_widget_query'] contient la valeur de chaîne que l'utilisateur saisit dans le menu.

chat.appCommandPayload

object (AppCommandPayload)

Charge utile que les applications Chat reçoivent lorsqu'un utilisateur utilise une commande de l'application Chat.

Charge utile

Selon le type d'interaction, l'événement contient une charge utile avec une ou plusieurs ressources de l'API Chat.

Charge utile du message
MessagePayload
chat.messagePayload.message object (Message)
Message Chat ayant déclenché l'événement.
chat.messagePayload.space object (Space)
Espace Chat dans lequel un utilisateur a envoyé le message ayant appelé l'application Chat.

Ajouté à la charge utile de l'espace
AddedToSpacePayload
chat.addedToSpacePayload.space object (Space)
Espace Chat auquel l'utilisateur a ajouté ou installé l'application Chat.

Lorsque les administrateurs installent des applications Chat, le champ space.adminInstalled est défini sur true.

chat.addedToSpacePayload.interactionAdd boolean
Indique si un utilisateur ajoute l'application Chat à un espace à l'aide d'un message. Par exemple, @mentionner l'application Chat ou utiliser une commande à barre oblique. Si la valeur est true, Chat envoie un autre objet d'événement avec un messagePayload contenant des informations sur le message.

Supprimé de la charge utile de l'espace
RemovedFromSpacePayload
chat.removedFromSpacePayload.space object (Space)
Espace Chat à partir duquel l'utilisateur a supprimé ou désinstallé l'application Chat.

Lorsque les administrateurs désinstallent des applications Chat, le champ space.adminInstalled est défini sur false.

Charge utile du clic sur un bouton
ButtonClickedPayload
chat.buttonClickedPayload.message object (Message)
Message Chat contenant le bouton sur lequel un utilisateur a cliqué.
chat.buttonClickedPayload.space object (Space)
Espace Chat dans lequel l'utilisateur a cliqué sur un bouton à partir d'un message de l'application Chat.
chat.buttonClickedPayload.isDialogEvent boolean
Indique si l'utilisateur a cliqué sur le bouton pour interagir avec une boîte de dialogue.
chat.buttonClickedPayload.dialogEventType enum (DialogEventType)
Si isDialogEvent est true, type d'interaction dans une boîte de dialogue.

Enum DialogEventType.

La valeur de dialogEventType ne peut être qu'une des valeurs suivantes:
TYPE_UNSPECIFIED Valeur par défaut. Non spécifié.
REQUEST_DIALOG Un utilisateur demande une boîte de dialogue. Par exemple, ils utilisent une commande avec une barre oblique ou cliquent sur un bouton dans un message.
SUBMIT_DIALOG Un utilisateur clique sur un élément interactif dans une boîte de dialogue. Par exemple, un utilisateur renseigne des informations dans une boîte de dialogue et clique sur un bouton pour les envoyer.

Charge utile de mise à jour du widget
WidgetUpdatedPayload
chat.widgetUpdatedPayload.space object (Space)
Salon Chat dans lequel l'interaction s'est produite.

Charge utile de la commande de l'application
AppCommandPayload
chat.appCommandPayload.appCommandMetadata object (AppCommandMetadata)
Métadonnées sur la commande utilisée par l'utilisateur et sur la façon dont il l'a déclenchée.
chat.appCommandPayload.space object (Space)
Espace Chat dans lequel un utilisateur a utilisé la commande.
chat.appCommandPayload.thread object (Thread)
Si l'interaction s'est produite dans un fil de discussion, le fil de discussion Chat dans lequel l'utilisateur a utilisé la commande.
chat.appCommandPayload.message object (Message)
Message envoyé par l'utilisateur avec la commande slash.
chat.appCommandPayload.configCompleteRedirectUri string
Si une autorisation ou une configuration est requise pour la commande, une URL vers laquelle rediriger l'utilisateur une fois qu'il a terminé le processus en dehors de Google Chat.
chat.appCommandPayload.isDialogEvent boolean
Indique si la commande ouvre une boîte de dialogue.
chat.appCommandPayload.dialogEventType enum (DialogEventType)
Le type d'interaction avec une boîte de dialogue.

Enum DialogEventType.

La valeur de dialogEventType ne peut être qu'une des valeurs suivantes:
TYPE_UNSPECIFIED Valeur par défaut. Non spécifié.
REQUEST_DIALOG Un utilisateur demande une boîte de dialogue. Par exemple, ils utilisent une commande avec une barre oblique ou cliquent sur un bouton dans un message.
SUBMIT_DIALOG Un utilisateur clique sur un élément interactif dans une boîte de dialogue. Par exemple, un utilisateur renseigne des informations dans une boîte de dialogue et clique sur un bouton pour les envoyer.
Métadonnées de commande d'application
AppCommandMetadata
chat.appCommandPayload.appCommandMetadata.appCommandId

string (int64 format)

ID de la commande.
chat.appCommandPayload.appCommandMetadata.appCommandType enum (AppCommandType)
Type de commande.

Enum AppCommandType.

La valeur de AppCommandType ne peut être qu'une des valeurs suivantes:
APP_COMMAND_TYPE_UNSPECIFIED Valeur par défaut. Non spécifié.
SLASH_COMMAND Un utilisateur utilise la commande en envoyant un message commençant par une barre oblique /.

Actions du chat

Cette section explique comment les applications Chat peuvent utiliser des actions de modules complémentaires pour répondre aux interactions des utilisateurs.

Pour répondre avec une action de module complémentaire, une application Chat doit répondre dans un délai de 30 secondes, et la réponse doit être publiée dans l'espace où l'interaction s'est produite. Sinon, l'application Chat doit configurer l'authentification et appeler l'API Google Chat pour répondre.

Les applications de chat peuvent gérer et répondre aux interactions de nombreuses manières. Dans de nombreux cas, les applications Chat répondent par un message. Les applications de chat peuvent également rechercher des informations dans une source de données, enregistrer les informations de l'objet de l'événement ou presque tout autre chose. C'est ce comportement de traitement qui définit essentiellement l'application Google Chat.

Pour répondre aux interactions utilisateur, les applications Chat doivent gérer l'objet d'événement correspondant et renvoyer l'un des objets JSON suivants:

Réponse souhaitée de l'application Chat Action requise pour effectuer un retour
Envoyer ou mettre à jour un message DataActions
Ouvrez, mettez à jour ou fermez une boîte de dialogue. RenderActions
Pour collecter des informations à partir d'une fiche ou d'une boîte de dialogue, suggérez des éléments de sélection en fonction de ce que les utilisateurs saisissent dans un menu à sélection multiple. RenderActions
Aperçu des liens dans les messages que les utilisateurs de Chat envoient dans un espace. DataActions

Répondre à l'aide de l'API Google Chat

Au lieu de renvoyer une action de module complémentaire, les applications Chat peuvent devoir utiliser l'API Google Chat pour répondre à une interaction. Par exemple, les applications Chat doivent appeler l'API Google Chat pour effectuer l'une des opérations suivantes:

  • Répondre à une interaction au bout de 30 secondes
  • effectuer des tâches en dehors de l'espace dans lequel l'interaction a eu lieu ;
  • Effectuer des tâches dans Chat qui ne sont pas disponibles en tant qu'actions de modules complémentaires Par exemple, listez les espaces auxquels un utilisateur ou une application Chat est membre, ou ajoutez des utilisateurs à un espace.
  • Effectuer des tâches pour le compte de l'utilisateur Chat (ce qui nécessite une authentification de l'utilisateur).

Pour en savoir plus sur l'authentification et l'appel de l'API Chat, consultez la présentation de l'API Chat.