Mises à jour: Consultez les notes de version pour découvrir les nouvelles fonctionnalités et les mises à jour du produit.

Cette page a été traduite par l'API Cloud Translation.

Événements

Les événements sont des notifications que votre agent peut envoyer et recevoir. Il existe trois types d'événements :

Généré par le serveur : envoyé à votre agent par la plate-forme RBM
Généré par l'utilisateur : envoyé à votre agent par l'appareil de l'utilisateur
Généré par l'agent : envoyé par votre agent à l'utilisateur

Événements générés par le serveur

La plate-forme RBM envoie des événements pour informer votre agent des mises à jour au niveau du serveur, telles que les expirations de messages.

Pour connaître les options de mise en forme et de valeur, consultez ServerEvent.

L'état du 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 après l'approbation de l'opérateur, vous recevez un événement AgentLaunchEvent pour indiquer le changement. Ces événements sont envoyés pour tous les agents RBM, pour toutes les modifications de l'état de lancement de l'opérateur.

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 générés par les utilisateurs).
Pour différencier les événements générés par l'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 transmis 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 du 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é par 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`	L'agent suspendu a été réactivé.
`SUSPENDED`	`TERMINATED`	L'agent suspendu a été désactivé.
`TERMINATED`	`LAUNCHED`	L'agent désactivé a été lancé.

Le message a expiré. La révocation a réussi.

Le message a expiré et a bien été révoqué. Cet événement serait un bon déclencheur pour votre stratégie de messagerie de secours.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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

Le message a expiré, mais n'a pas été révoqué.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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é 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.

Événements générés par les utilisateurs

Comme pour les messages utilisateur et les vérifications des fonctionnalités, votre agent reçoit les événements utilisateur au format JSON.

Pour connaître les options de mise en forme et de valeur, consultez UserEvent.

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

Cet événement indique qu'un message a été distribué.

{
  "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 du texte.

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

L'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

Important : Pour aider les développeurs à passer aux nouveaux événements de webhook UNSUBSCRIBE et SUBSCRIBE, Google Messages envoie également des messages "STOP" et "START" en même temps que les événements de webhook. Bien que vous puissiez vous appuyer sur votre logique STOP/START existante pour le moment, nous vous recommandons vivement de mettre à jour votre logique pour gérer les événements UNSUBSCRIBE et SUBSCRIBE, car ils deviendront obligatoires conformément à la spécification GSMA.

Si un utilisateur ne souhaite pas recevoir de messages non essentiels d'une entreprise (promotions, par exemple), il peut se désabonner de la conversation RBM dans Google Messages.

L'événement UNSUBSCRIBE indique que l'utilisateur s'est désabonné de sa conversation avec votre agent et l'entreprise qu'il représente. Voici un exemple de charge utile JSON :

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

Fonctionnement

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 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 liste les mots clés pour chaque pays disponible.

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. Dans ce 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 qu'un utilisateur se désabonne.

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 pour ce vol spécifique.

Motifs de désabonnement

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

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

Actuellement, les motifs de désabonnement ne sont pas partagés avec les partenaires ni les opérateurs.

L'utilisateur se réabonne à la conversation.

Les utilisateurs peuvent se réabonner à une conversation dont ils s'étaient désabonnés dans Google Messages.

L'événement SUBSCRIBE indique qu'un utilisateur souhaite recevoir des messages de votre agent, y compris du contenu non essentiel comme des promotions. Voici un exemple de charge utile JSON :

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

Fonctionnement

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 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é 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)	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.
La réinscription 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 statut et de reprendre l'envoi de messages en conséquence.

Événements générés par l'agent

Votre agent envoie des événements pour simuler des interactions humaines et assurer à l'utilisateur que votre agent interagit avec ses messages. Pour les utilisateurs, les événements s'affichent sous forme de notifications dans leurs conversations.

Pour connaître les options de mise en forme et de valeur, consultez phones.agentEvents.

L'agent envoie un événement `READ`.

Pour les utilisateurs, cet événement apparaît comme un accusé de lecture pour un message spécifique. Il indique à l'utilisateur que la plate-forme RBM a transmis son message et que l'agent est en train de le traiter.

Le code suivant envoie un événement READ pour un message avec un messageId correspondant.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);

Ce code est un extrait d'un exemple d'agent RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");

Ce code est un extrait d'un exemple d'agent RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)

Ce code est un extrait d'un exemple d'agent RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");

Ce code est un extrait d'un exemple d'agent RBM.

L'agent envoie un événement `IS_TYPING`.

Pour les utilisateurs, cet événement apparaît sous la forme d'un indicateur de saisie et leur indique que votre agent est en train de rédiger un message. L'indicateur de saisie expire au bout d'un court laps de temps (environ 20 secondes) ou lorsque l'appareil de l'utilisateur reçoit un nouveau message de votre agent. Votre agent peut envoyer plusieurs événements IS_TYPING pour réinitialiser le minuteur d'expiration de l'indicateur de saisie.

Le code suivant envoie un événement IS_TYPING.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});

Ce code est un extrait d'un exemple d'agent RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");

Ce code est un extrait d'un exemple d'agent RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')

Ce code est un extrait d'un exemple d'agent RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");

Ce code est un extrait d'un exemple d'agent RBM.

Recevoir des messages

Vérifications des capacités

Événements Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Événements générés par le serveur

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

Configuration du webhook

Prérequis

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

Le message a expiré. La révocation a réussi.

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

Événements générés par les utilisateurs

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

L'utilisateur lit le message de l'agent

L'utilisateur commence à saisir du texte

L'utilisateur envoie un message

L'utilisateur envoie un fichier

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

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

L'utilisateur se désabonne de la conversation

Fonctionnement

Règles métier

Exemple

Motifs de désabonnement

L'utilisateur se réabonne à la conversation.

Fonctionnement

Règles métier

Événements générés par l'agent

L'agent envoie un événement READ.

cURL

Node.js

Java

Python

C#

L'agent envoie un événement IS_TYPING.

cURL

Node.js

Java

Python

C#

Événements

L'agent envoie un événement `READ`.

L'agent envoie un événement `IS_TYPING`.