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 ou ses messages.
  • Événements de plate-forme : notifications envoyées par la plate-forme RBM concernant les changements d'état de lancement de l'agent et l'expiration des messages.

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

Événements utilisateur

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

Pour obtenir la liste complète des options de mise en forme et des valeurs, consultez la documentation de référence sur UserEvent.

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

Cet événement indique qu'un message a bien été distribué à 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 à saisir du texte

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 envoie un message

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Un utilisateur envoie un fichier

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "userFile": {
    "payload": {
      "mimeType": "image/gif",
      "fileSizeBytes": 127806,
      "fileUri": "https://storage.googleapis.com/copper_test/77ddb795-24ad-4607-96ae-b08b4d86406a/d2dcc67ab888d34ee272899c020b13402856f81597228322079eb007e8c9",
      "fileName": "4_animated.gif"
    }
  },
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

L'utilisateur appuie sur une suggestion de réponse.

Lorsqu'un utilisateur appuie sur une réponse suggérée, votre agent reçoit un événement avec les données de postback et le texte de la réponse.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

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 avec 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, envoyés par votre agent et 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

  • Une option Se désabonner est toujours disponible dans le menu de chat. Pour les agents promotionnels et à usages multiples, 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 vous sélectionnez Se désabonner, deux actions se déclenchent 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 liste les mots clés pour chaque pays accepté.

    Pays (code pays) Mot clé de désabonnement
    Allemagne (DE), États-Unis (US), Inde (IN), Royaume-Uni (GB) ARRÊTER
    Espagne (ES), Mexique (MX) BAJA
    France (FR) ARRÊTER
    Brésil (BR) parar

  • Une fois que l'utilisateur se désabonne, 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 vers le dossier Spam et conversations bloquées.

  • Pour identifier les cas de non-respect des règles et des règles métier, Google surveille les schémas de messages après la désinscription d'un utilisateur.

Règles métier

  • En tant que partenaire RBM qui gère cette conversation, il vous incombe 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 immédiatement envoyer un message de confirmation avec 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é, il est interdit de lui envoyer des messages non essentiels.
  • Les messages essentiels restent autorisés. Par exemple :
    • Authentifications, comme les mots de passe à usage unique (OTP)
    • Notifications concernant un service spécifique que l'utilisateur a demandé et accepté
    • Confirmation de la demande de désabonnement de l'utilisateur, avec des informations pour gérer plus précisément 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 cesser de lui envoyer des messages marketing. Toutefois, vous pouvez envoyer des informations sur les vols si l'utilisateur a explicitement accepté de recevoir des informations sur un vol spécifique.

Motifs de désabonnement

Lorsqu'un utilisateur se désabonne de votre agent, il peut sélectionner un motif parmi les options suivantes :

  • Spam
  • Je ne me suis jamais inscrit(e)
  • Trop de messages
  • Je ne suis plus intéressé
  • Autre

Les motifs de désabonnement sont indiqués dans l'aperçu Analytics pour aider les partenaires à 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 comme 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 de la réinscription

  • Une option S'abonner, disponible à la fois dans le menu de 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 vous sélectionnez S'abonner, deux actions se déclenchent simultanément : Google Messages envoie un mot clé spécifique au pays (par exemple, "DÉMARRER") à 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é pour s'abonner
    Allemagne (DE), États-Unis (US), Inde (IN), Royaume-Uni (GB) DÉMARRER
    Espagne (ES), Mexique (MX) ALTA
    France (FR) Démarrer
    Brésil (BR) commencer

Règles métier

  • En tant que partenaire RBM qui gère cette conversation, il vous incombe de répondre à la demande de réabonnement de l'utilisateur.
  • La réinscription s'applique à tous les types de messages, y compris les contenus non essentiels tels que 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 statut et de reprendre l'envoi de messages en conséquence.

Événements de plate-forme

La plate-forme RBM envoie des événements pour informer votre agent des modifications apportées à son état de lancement ou à 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 envoyé sous la forme d'un message Pub/Sub. Pour le différencier des autres événements, vérifiez le chemin 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 (cette étape est obligatoire pour recevoir les messages et les événements utilisateur).
  • Pour faire la différence entre les événements utilisateur et les événements d'état de lancement de l'agent, vérifiez le chemin message.attributes.type pour la valeur agent_launch_event.

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

Le AgentLaunchEvent est distribué sous la forme d'un 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
UNLAUNCHED Non lancé La modification est autorisée.
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 transporteur donné Le motif de la suspension est indiqué dans le commentaire.

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 code 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"
    }

Le tableau suivant présente les états de lancement de l'agent et les actions qui les déclenchent :

Ancien état de lancement Nouvel état de lancement Déclencheur de changement
PENDING LAUNCHED L'agent en attente a été approuvé.
PENDING REJECTED L'agent en attente a été refusé.
LAUNCHED SUSPENDED Agent lancé suspendu.
SUSPENDED LAUNCHED Un agent suspendu a été réactivé.
SUSPENDED TERMINATED L'agent suspendu a été résilié.
TERMINATED LAUNCHED L'agent désactivé a été lancé.

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 été révoqué. Il s'agit d'un bon déclencheur pour votre stratégie de messages de secours.

Pour obtenir la liste complète des options de mise en forme et des valeurs, consultez la documentation de référence sur ServerEvent.

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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

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

Pour obtenir la liste complète des options de mise en forme et des valeurs, consultez la documentation de référence sur ServerEvent.

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

La distribution des messages n'est pas garantie.

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

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

Précédent
Envoyer des événements
Suivant
Vérifications des capacités