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 plate-forme : notifications concernant les modifications de l'état de lancement de l'agent et l'expiration des messages envoyées 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 lieux, 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 obtenir des informations complètes sur le formatage et les options de valeur, 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 un 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 à écrire

Cet événement indique qu'un utilisateur est en train de rédiger 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 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 a choisi de ne plus recevoir de messages non essentiels, tels que des 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 du désabonnement

  • Une option Se désabonner est toujours disponible dans le menu de chat. Pour les agents promotionnels et à usage multiple, 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 le pays).

  • La sélection de l'option Se désabonner déclenche deux actions simultanées : 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), Royaume-Uni (GB) ARRÊTER
    Espagne (ES), Mexique (MX) BAJA
    France (FR) ARRÊTER
    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 vers le dossier Spam et conversations bloquées.

  • Pour identifier les violations des règles et des règles métier, Google surveille les modèles de messages après qu'un utilisateur s'est désabonné.

Règles métier

  • En tant que partenaire RBM qui gère cette conversation, il vous incombe de répondre à la demande de désabonnement de l'utilisateur.
  • Si vous ne pouvez pas effectuer le désabonnement 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 d'envoyer des messages non essentiels.
  • Les messages essentiels sont toujours autorisés. Ils incluent :
    • Les authentifications, telles que les mots de passe à usage unique (OTP)
    • Les notifications concernant un service spécifique que l'utilisateur a demandé et accepté
    • La confirmation de la demande de désabonnement de l'utilisateur, avec des informations permettant de gérer 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 à usage multiple, vous devez cesser d'envoyer des messages marketing. Toutefois, vous pouvez envoyer des informations sur les vols si l'utilisateur a donné son consentement explicite pour 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 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 affichés dans la vue d'ensemble 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 tels que des promotions. Les utilisateurs peuvent déclencher cet événement en se réabonnant à une conversation à laquelle ils s'étaient précédemment 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

  • Une option S'abonner, disponible à la fois dans le menu de chat et dans un lien intégré au chat, permet aux utilisateurs de se réabonner à une conversation à laquelle ils s'étaient désabonnés.

  • La sélection de l'option S'abonner déclenche deux actions simultanées : 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 répertorie les mots clés pour chaque pays compatible.

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

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.
  • Le réabonnement s'applique à tous les types de messages, y compris aux 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 é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 distribué sous forme de 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 (cette étape est obligatoire pour recevoir les messages et les événements utilisateur).
  • Pour faire la distinction entre les événements utilisateur et les é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 des événements

Le AgentLaunchEvent est distribué 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 de refus est spécifié dans le commentaire.
SUSPENDED Suspendu sur un opérateur donné Le motif de suspension est spécifié dans le commentaire.
UNLAUNCHED Non lancé La modification est autorisée pour les agents qui ont été désactivés sur 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 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"
    }

Modifications de l'état de lancement initiées par l'opérateur

Il s'agit de 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/d'administration.
SUSPENDED LAUNCHED Restaurer l'état actif d'un agent.
SUSPENDED UNLAUNCHED Désactiver un agent.

Modifications de l'état de lancement initiées par le partenaire

Il s'agit de 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 Envoyer pour examen.
UNLAUNCHED PENDING Envoyer pour examen.
REJECTED PENDING Renvoyer 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 été révoqué. Il s'agit d'un bon déclencheur pour votre stratégie de messagerie de secours.

Pour obtenir des informations complètes sur le formatage et les options de valeur, 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 la durée de vie (TTL) du message a expiré, mais qu'il n'a pas été révoqué.

Pour obtenir des informations complètes sur le formatage et les options de valeur, 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é distribué, vous recevrez un événement DELIVERED sur 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 OTP 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 des messages en double pour l'utilisateur.

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