Recevoir des événements

Votre agent reçoit des événements de webhook de la plate-forme RBM, qui vous informent des interactions des utilisateurs et des mises à jour au niveau de la plate-forme.

Ces événements sont classés par origine :

  • Événements utilisateur : notifications envoyées depuis l'appareil d'un utilisateur à votre agent, signalant une interaction avec votre agent.
  • Événements de la plate-forme : notifications concernant les changements d'état de lancement de l'agent et l'expiration des messages envoyés par la plate-forme RBM.

Pour en savoir plus sur les événements d'état que votre agent envoie à l'appareil de l'utilisateur, consultez Envoyer des événements.

Pour en savoir plus sur la gestion des messages utilisateur, tels que le texte, les fichiers, les emplacements, etc., consultez Recevoir des messages.

Événements utilisateur

Les événements utilisateur sont des notifications provenant de l'appareil de l'utilisateur qui signalent l'état des messages ou les modifications d'abonnement (par exemple, l'utilisateur s'est désabonné ou réabonné dans Google Messages).

Pour connaître toutes les options de mise en forme et de valeur, consultez la documentation de référence sur UserEvent.

L'utilisateur reçoit le message de l'agent

Cet événement indique qu'un message a bien été distribué sur l'appareil de l'utilisateur.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

L'utilisateur lit le message de l'agent

Cet événement indique qu'un message a été ouvert ou confirmé.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

L'utilisateur commence à taper

Cet événement indique qu'un utilisateur est en train de saisir une réponse.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "IS_TYPING",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

L'utilisateur appuie sur une action suggérée

Lorsqu'un utilisateur appuie sur une action suggérée, votre agent reçoit un événement contenant les données de postback de l'action.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234"
  }
}

L'utilisateur se désabonne de la conversation

Cet événement indique que l'utilisateur s'est désabonné des messages non essentiels, tels que les promotions, de votre agent et de l'entreprise qu'il représente. Les utilisateurs déclenchent cet événement en se désabonnant de la conversation RBM dans Google Messages.

Voici un exemple de charge utile JSON :

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "UNSUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Fonctionnement de la désinscription

  • L'option Se désabonner est toujours disponible dans le menu de chat. Pour les agents promotionnels et polyvalents, cette option s'affiche également directement dans le chat après un certain nombre de messages non lus (les règles spécifiques varient selon les pays).
  • Si l'utilisateur sélectionne Se désabonner, deux actions sont déclenchées simultanément : Google Messages envoie un mot clé spécifique au pays (par exemple, "STOP") à votre agent, et la plate-forme RBM envoie un événement UNSUBSCRIBE à votre webhook.

    Le mot clé est déterminé par le code pays à deux lettres du numéro de téléphone de l'utilisateur. Le tableau suivant répertorie les mots clés pour chaque pays compatible.

    Pays (code pays) Mot clé de désabonnement
    Allemagne (DE), États-Unis (US), Inde (IN), Pays-Bas (NL), Royaume-Uni (GB) ARRÊTER
    Espagne (ES), Mexique (MX) BAJA
    France (FR) STOP
    Brésil (BR) parar
  • Une fois que l'utilisateur s'est désabonné, la conversation reste dans sa boîte de réception, sauf si elle est signalée comme spam, auquel cas elle est déplacée dans le dossier Spam et conversations bloquées.

  • Pour identifier les cas de non-respect des règles et des règles d'entreprise, Google surveille les schémas de messages après qu'un utilisateur s'est désabonné.

Règles commerciales

  • En tant que partenaire RBM qui gère cette conversation, il est de votre responsabilité de respecter la demande de désabonnement de l'utilisateur.
  • Si vous ne pouvez pas effectuer la désinscription dans le fil de discussion, vous devez envoyer immédiatement un message d'accusé de réception contenant un lien direct vers le site Web ou l'application où les utilisateurs peuvent gérer leurs préférences d'abonnement.
  • Une fois que l'utilisateur s'est désabonné, l'envoi de messages non essentiels est interdit.
  • Les messages essentiels sont toujours autorisés. Par exemple :
    • Authentifications, telles que les mots de passe à usage unique (OTP)
    • Notifications concernant un service spécifique demandé et accepté par l'utilisateur
    • Confirmation de la demande de désabonnement de l'utilisateur, avec des informations pour gérer davantage ses préférences de communication

Exemple

Si un utilisateur se désabonne d'un agent de compagnie aérienne dont le cas d'utilisation est multi-usage, vous devez arrêter de lui envoyer des messages marketing. Toutefois, vous pouvez envoyer des informations sur un vol si l'utilisateur a explicitement accepté de recevoir des informations sur ce vol spécifique.

Motifs de désabonnement

Lorsqu'un utilisateur se désabonne de votre agent, il peut sélectionner l'un des motifs suivants :

  • Trop de messages
  • Je ne me suis jamais inscrit
  • Ça ne m'intéresse plus
  • Ça ressemble à une escroquerie
  • Autre

Pour réduire le biais de sélection, les quatre premières options sont affichées dans un ordre aléatoire pour chaque utilisateur. Cet ordre reste le même lors des visites de l'utilisateur, et Autre reste fixé en bas.

Les motifs de désabonnement sont regroupés et affichés dans la vue d'ensemble d'Analytics pour vous aider à comprendre pourquoi les utilisateurs se désabonnent.

L'utilisateur se réabonne à la conversation

Cet événement indique qu'un utilisateur souhaite à nouveau recevoir des messages de votre agent, y compris des contenus non essentiels tels que des promotions. Les utilisateurs peuvent déclencher cet événement en se réabonnant à une conversation dont ils s'étaient désabonnés dans Google Messages.

Voici un exemple de charge utile JSON :

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "SUBSCRIBE",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Fonctionnement du réabonnement

  • L'option S'abonner, disponible dans le menu du chat et via un lien dans le chat, permet aux utilisateurs de se réabonner à une conversation dont ils s'étaient désabonnés.
  • Si l'utilisateur sélectionne S'abonner, deux actions sont déclenchées simultanément : Google Messages envoie un mot clé spécifique au pays (par exemple, "START") à votre agent, et la plate-forme RBM envoie un événement SUBSCRIBE à votre webhook. Le mot clé spécifique est déterminé par le code pays à deux lettres du numéro de téléphone de l'utilisateur. Le tableau suivant liste les mots clés pour chaque pays accepté.

    Pays (code pays) Mot clé d'abonnement
    Allemagne (DE), États-Unis (US), Inde (IN), Pays-Bas (NL), Royaume-Uni (GB) DÉMARRER
    Espagne (ES), Mexique (MX) ALTA
    France (FR) Démarrer
    Brésil (BR) começar

Règles commerciales

  • En tant que partenaire RBM qui gère cette conversation, il est de votre responsabilité de répondre à la demande de réabonnement de l'utilisateur.
  • Le réabonnement s'applique à tous les types de messages, y compris les contenus non essentiels comme les promotions.
  • Si un utilisateur envoie un message à votre entreprise après s'être désabonné, cela peut être considéré comme une demande de réabonnement.
  • Si un utilisateur se réabonne en dehors du canal de messagerie (par exemple, sur votre site Web), il vous incombe, en tant que partenaire RBM, de mettre à jour son état et de reprendre l'envoi de messages en conséquence.

Événements de plate-forme

La plate-forme RBM envoie des événements de plate-forme pour informer votre agent des modifications apportées à l'état de lancement de l'agent ou de l'expiration des messages.

L'état de lancement de l'agent a changé

La plate-forme RBM envoie un AgentLaunchEvent pour chaque modification de l'état de lancement de votre agent. Par exemple, lorsque l'état de votre agent passe de PENDING à LAUNCHED. L'événement est diffusé sous la forme d'un message Pub/Sub. Pour le différencier des autres événements, vérifiez le chemin d'accès message.attributes.type pour la valeur agent_launch_event.

Configuration du webhook

Vous pouvez utiliser votre webhook au niveau du partenaire ou de l'agent pour recevoir ces notifications.

Prérequis

  • Configurez votre webhook pour la messagerie RBM (obligatoire pour recevoir les messages et les événements des utilisateurs).
  • Pour différencier les événements utilisateur des événements d'état de lancement de l'agent, vérifiez le chemin d'accès message.attributes.type pour la valeur agent_launch_event.

Structure de la charge utile de l'événement

Le AgentLaunchEvent est envoyé sous forme de message Pub/Sub.

Exemple :

{
  "message": {
    "attributes": {
      "business_id": "rbm-chatbot-id@rbm.goog",
      "event_type": "REJECTED",
      "product": "RBM",
      "project_number": "3338881441851",
      "type": "agent_launch_event"
    },
    "data": "....BASE64-encoded-JSON-with-notification...",
    "messageId": "14150481888479752",
    "message_id": "14150481888479752",
    "publishTime": "2025-03-05T18:50:21.88Z",
    "publish_time": "2025-03-05T18:50:21.88Z"
  },
  "subscription": "projects/rbm-partner-gcp/subscriptions/rbm-sub"
}

Le champ AgentLaunchEvent.LaunchState de la charge utile de l'événement indique le nouvel état de lancement de l'agent. Voici les valeurs possibles :

Valeur État de lancement de l'agent Détails
PENDING En attente La demande a été envoyée à un opérateur pour examen.
LAUNCHED Lancé Les messages sont autorisés sur un opérateur donné.
REJECTED Refusé sur un opérateur donné Le motif du refus est indiqué dans le commentaire.
SUSPENDED Suspendu sur un opérateur donné Le motif de la suspension est spécifié dans le commentaire.
UNLAUNCHED Non lancé La modification est autorisée pour les agents qui ont été désactivés par tous les opérateurs.

Le champ de données contient un objet JSON encodé en base64 avec les détails de l'état de lancement. Voici un exemple de fichier JSON décodé :

 {
      "eventId": "rbm-chatbot-id/0a7ed168-676e-4a56-b422-b23434",
      "agentId": "rbm-chatbot-id@rbm.goog",
      "botDisplayName": "RBM Welcome Bot 7 - RBM Chatbot name",
      "brandId": "bd38fbff-392a-437b-a6f2-7f2e43745b56",
      "brandDisplayName": "Chatbots brand",
      "regionId": "/v1/regions/fi-rcs",
      "oldLaunchState": "PENDING",
      "newLaunchState": "REJECTED",
      "actingParty": "rbm-support@google.com",
      "comment": "Carrier has rejected the launch: policy violation",
      "sendTime": "2025-03-05T18:50:19.386436Z"
}

Changements de l'état de lancement initiés par l'opérateur

Voici les transitions autorisées qui sont généralement gérées par les opérateurs lors du processus d'examen et d'application :

Ancien état de lancement Nouvel état de lancement Action de déclenchement
PENDING LAUNCHED Approuver une demande de lancement.
PENDING REJECTED Refuser une demande de lancement
LAUNCHED SUSPENDED Suspendre pour des raisons d'application ou d'administration.
SUSPENDED LAUNCHED Rétablir l'état actif d'un agent.
SUSPENDED UNLAUNCHED Arrêter un agent.
REJECTED LAUNCHED Approuver une demande de lancement précédemment refusée.

Changements d'état de lancement initiés par le partenaire

Voici les transitions autorisées qui sont généralement gérées par les partenaires :

Ancien état de lancement Nouvel état de lancement Action de déclenchement
UNSPECIFIED PENDING Envoyez-les pour examen.
PENDING UNLAUNCHED Annuler une demande de lancement en attente.
UNLAUNCHED PENDING Envoyez-les pour examen.
REJECTED PENDING Renvoyez-les pour examen.
SUSPENDED PENDING Renvoyez-les pour examen.

Le message a expiré ; la révocation a réussi

Cet événement indique que la durée de vie (TTL) du message a expiré et que le message a bien été révoqué. C'est un bon déclencheur pour votre stratégie de messagerie de remplacement.

Pour connaître toutes les options de mise en forme et de valeur, consultez la documentation de référence sur ServerEvent.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

Le message a expiré. Échec de la révocation.

Cet événement indique que la valeur TTL du message a expiré, mais qu'il n'a pas été révoqué.

Pour connaître toutes les options de mise en forme et de valeur, consultez la documentation de référence sur ServerEvent.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

La distribution des messages n'est pas garantie.

  • Si le message a été distribué, vous recevrez un événement DELIVERED au niveau de votre webhook.
  • Si le message n'a pas été distribué, utilisez l'API de révocation pour envoyer une demande de révocation.

Si le message est urgent, comme un mot de passe à usage unique ou une alerte de fraude, il est préférable de l'envoyer via un autre canal, comme un SMS, même si cela entraîne l'envoi de messages en double à l'utilisateur.