Cette page explique comment les applications Google Chat peuvent recevoir des événements dans Google Chat et y répondre.
Un événement Google Chat représente une activité ou une modification dans Chat, comme un nouveau message dans un espace. Votre application Chat peut utiliser des événements pour comprendre ce qui s'est passé et prendre des mesures ou répondre de manière pertinente pour vos utilisateurs.
Voici quelques exemples d'utilisation des événements :
- Surveillez les nouveaux messages dans un espace et répondez-y, par exemple en recherchant des mots clés ou des expressions.
- Envoyez un message de bienvenue aux utilisateurs lorsqu'ils rejoignent l'espace pour leur expliquer les règles de l'espace ou leur donner des conseils sur l'utilisation efficace de l'application Chat.
- Suivez et analysez l'activité Chat. Par exemple, envoyez un rapport mensuel sur les nouveaux membres ou les messages qui suscitent le plus de réactions ou de réponses.
- Communiquez sur différentes plates-formes de messagerie. Par exemple, les utilisateurs peuvent envoyer et recevoir des messages d'utilisateurs sur une autre plate-forme de messagerie sans quitter Chat.
Fonctionnement des événements
Chaque fois qu'un événement se produit dans Google Chat, une ressource de l'API Google Chat est créée, mise à jour ou supprimée. Chat utilise des événements pour fournir à votre application Chat des informations sur le type d'activité qui s'est produit et sur la ressource de l'API Chat qui a été affectée.
Message.
Chat crée ensuite un événement contenant des données sur le nouveau
message.Chat catégorise les événements par type. Les types d'événements vous aident à filtrer et à ne recevoir que le type d'informations dont vous avez besoin, et vous permettent de gérer les activités similaires de la même manière.
Le tableau suivant montre comment une activité dans Chat affecte une ressource de l'API Chat associée et le type d'événement que votre application Chat reçoit :
| Activité | Ressource de l'API Chat | Type d'événement |
|---|---|---|
| Un utilisateur publie un message dans un espace Chat. | Une ressource Message est créée. |
Nouveau message |
| Un utilisateur devient gestionnaire d'espace. | Une ressource Membership est mise à jour. |
Abonnement mis à jour |
| Un utilisateur réagit à un message. | Une ressource Reaction est créée. |
Nouvelle réaction |
| Un utilisateur quitte un espace. | Une ressource Membership est supprimée. |
Abonnement supprimé |
Recevoir des événements de Google Chat
Pour recevoir des événements, votre application Chat peut effectuer l'une des opérations suivantes :
- Abonnez-vous aux événements à l'aide de l'API Google Workspace Events pour les recevoir au fur et à mesure qu'ils se produisent.
- Interrogez les événements récents en appelant l'API Chat.
Le tableau suivant explique la différence et les raisons d'interroger ou de s'abonner à des événements :
| S'abonner à des événements | Interroger des événements | |
|---|---|---|
| Cas d'utilisation |
|
|
| API | API Google Workspace Events | API Chat |
| Source des événements | Espaces, utilisateurs et organisations Google Workspace ( Preview développeur) | Espaces uniquement |
| Événements compatibles |
Pour obtenir la liste des types d'événements compatibles, consultez la section Types d'événements pour créer des abonnements dans la documentation de l'API Google Workspace Events. |
Pour obtenir la liste des types d'événements compatibles, consultez la ressource spaceEvents dans la documentation de référence de l'API Chat.
|
| Format des événements | Message Google Cloud Pub/Sub, formaté conformément à la spécification CloudEvent. Pour en savoir plus, consultez Structure des événements Google Workspace. |
Ressource de l'API Chat
(
spaces.spaceEvent)
|
| Données d'événement | Chaîne encodée en base64 avec ou sans données de ressource. Pour obtenir des exemples de charges utiles, consultez Données d'événement. | Charge utile JSON contenant des données de ressource. Certains types d'événements n'incluent que certains champs de ressource. Pour obtenir des exemples de charges utiles, consultez la documentation de référence. |
Exemple : Interroger ou s'abonner à des événements concernant les abonnements dans un espace
Dans cet exemple, une application Chat souhaite recevoir des informations sur les modifications apportées aux membres d'un espace Chat. Dans l'espace, l'activité d'abonnement suivante se produit :
- Un utilisateur rejoint l'espace, ce qui crée une ressource
Membershipet déclenche un événement de nouveau membre. - Un utilisateur devient gestionnaire d'espace, ce qui met à jour la ressource
Membershipde l'utilisateur et déclenche un événement de membre mis à jour. - Un utilisateur quitte l'espace, ce qui supprime la ressource
Membershipde l'utilisateur et déclenche un événement de membre supprimé.
S'abonner aux événements d'abonnement
Pour recevoir des événements en temps réel, l'
application Chat appelle la méthode
subscriptions.create()
de l'API Google Workspace Events pour s'abonner à l'espace pour tous les types d'événements d'abonnement. Une fois l'abonnement créé, l'application Chat peut commencer à recevoir des événements d'abonnement.
Dans la figure 2, l'application Chat dispose d'un abonnement actif à l'espace. Elle reçoit donc un événement chaque fois qu'un abonnement dans l'espace est modifié. L'application Chat peut ensuite traiter ou répondre en temps réel à l'une des activités, par exemple en publiant un message de bienvenue privé à l'intention du membre qui a rejoint l'espace.
Pour savoir comment créer des abonnements à l'aide de l'API Google Workspace Events, consultez la documentation de l'API Google Workspace Events.
Interroger les événements d'abonnement récents
Au lieu de recevoir les événements d'abonnement au fur et à mesure qu'ils se produisent, une application Chat peut appeler l'API Chat pour lister les événements d'espace récents liés à l'activité d'abonnement.
Dans la figure 3, une application Chat appelle la méthode de l'API Chat
spaces.spaceEvents.list()
une fois que toutes les activités d'abonnement ont eu lieu, et filtre la requête
pour les événements d'abonnement nouveaux, mis à jour et supprimés. L'API Chat renvoie une liste de ressources spaceEvent qui représentent chacune des modifications d'abonnement.
L'application Chat peut ensuite traiter ou répondre en fonction de l'activité récente, par exemple en publiant un message hebdomadaire résumant l'activité d'abonnement de l'espace au cours des sept derniers jours.
Pour interroger des événements à l'aide de l'API Chat, consultez Lister les événements d'un espace Google Chat.
Limites et comportements de distribution
Limites générales
- Pour recevoir des événements d'abonnement, l'utilisateur ou l'application Chat doit être membre direct de l'espace. S'il a été ajouté, mis à jour ou supprimé indirectement dans un espace via un groupe Google, l'abonnement ne reçoit pas ces événements d'abonnement. Pour comprendre le fonctionnement des abonnements aux groupes Google, consultez Ajouter un groupe Google à un espace.
Abonnements utilisateur
-
Pour les abonnements aux utilisateurs, les événements concernant les nouveaux membres dans les messages privés ou les discussions de groupe sans nom (
google.workspace.chat.membership.v1.created), ne se déclenchent qu'après la publication du premier message.
Abonnements client ( Preview développeur)
Pour les abonnements client, les limites suivantes s'appliquent :
- L'organisation Google Workspace doit disposer d'au moins une licence d'offre Enterprise. Notez que cette exigence n'est pas strictement appliquée lors de la phase du programme Preview développeur, mais elle le sera à l'avenir (annonce séparée).
- Une application Chat ne peut créer qu'un seul abonnement client pour une organisation Google Workspace donnée. Une organisation Google Workspace peut avoir jusqu'à cinq abonnements client au total (créés par différentes applications Chat).
Pour les abonnements client, la distribution des événements suit ces règles générales :
- Événements d'espace : distribués uniquement si l'événement se produit dans un espace géré par votre organisation Google Workspace.
- Événements utilisateur : distribués uniquement si l'événement se produit pour un utilisateur appartenant à votre organisation Google Workspace.
La seule exception à ces règles concerne les événements d'abonnement. Votre abonnement peut recevoir des événements d'abonnement à la fois des espaces gérés par votre organisation et des espaces gérés par des organisations externes, mais leur distribution dépend de l'organisation qui gère l'espace :
Espaces gérés par votre organisation Google Workspace
Si une modification d'abonnement se produit dans un espace géré par l'organisation Google Workspace, elle est distribuée en tant qu'événement d'espace.
Le nom de ressource d'un événement d'espace utilise le format suivant :
spaces/{spaceId}/spaceEvents/{spaceEventId}
Espaces gérés par des organisations externes
Si l'abonnement d'un utilisateur géré par votre organisation Google Workspace est modifié dans un espace géré par une organisation externe (par exemple, un espace nommé externe ou un message privé créé par un utilisateur externe), votre abonnement reçoit cet événement en tant qu'événement utilisateur.
Le nom de ressource d'un événement utilisateur utilise le format suivant :
users/{userId}/userEvents/{userEventId}
Articles associés
- Présentation de l'API Google Workspace Events
- Créer un abonnement
- Obtenir des informations sur un événement d'espace Google Chat
- Lister les événements d'un espace Google Chat