Ihr Agent empfängt Webhook-Ereignisse von der RBM-Plattform, die Sie sowohl über Nutzerinteraktionen als auch über Aktualisierungen auf Plattformebene informieren.
Diese Ereignisse werden nach ihrem Ursprung kategorisiert:
- Nutzerereignisse: Benachrichtigungen, die vom Gerät eines Nutzers an Ihren Agenten gesendet werden und eine Interaktion mit Ihrem Agenten signalisieren.
- Plattformereignisse: Benachrichtigungen über Änderungen des Startstatus von Agenten und den Ablauf von Nachrichten, die von der RBM-Plattform gesendet werden.
Weitere Informationen zu Statusereignissen, die Ihr Agent an das Gerät des Nutzers sendet, finden Sie unter Ereignisse senden.
Weitere Informationen zum Umgang mit Nutzernachrichten wie Text, Dateien, Standorten und anderen finden Sie unter Nachrichten empfangen.
Nutzerereignisse
Nutzerereignisse sind Benachrichtigungen vom Gerät des Nutzers, die den Nachrichtenstatus oder Änderungen am Abo melden (z.B. wenn der Nutzer in Google Messages das Abo gekündigt oder erneut abonniert hat).
Eine vollständige Liste der Formatierungs- und Wertoptionen finden Sie in der Referenz zu UserEvent.
Nutzer erhält Nachricht vom KI-Agenten
Dieses Ereignis zeigt an, dass eine Nachricht erfolgreich an das Gerät des Nutzers zugestellt wurde.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "DELIVERED",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}Nutzer liest Nachricht des KI-Agenten
Dieses Ereignis zeigt an, dass eine Nachricht geöffnet oder bestätigt wurde.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "READ",
"eventId": "EVENT_ID",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID"
}Nutzer beginnt mit der Eingabe
Dieses Ereignis gibt an, dass ein Nutzer eine Antwort eingibt.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "IS_TYPING",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}Nutzer tippt auf eine vorgeschlagene Aktion
Wenn ein Nutzer auf eine vorgeschlagene Aktion tippt, empfängt Ihr Agent ein Ereignis mit den Postback-Daten der Aktion.
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID",
"suggestionResponse": {
"postbackData": "postback_1234"
}
}Der Nutzer meldet sich von der Unterhaltung ab.
Dieses Ereignis gibt an, dass der Nutzer sich vom Erhalt nicht essenzieller Nachrichten wie Werbeaktionen von Ihrem Agenten und dem von ihm vertretenen Unternehmen abgemeldet hat. Nutzer lösen dieses Ereignis aus, wenn sie die RBM-Unterhaltung in Google Messages abbestellen.
Hier ist ein Beispiel für die JSON-Nutzlast:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "UNSUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}So funktioniert das Abbestellen
- Im Chatmenü ist immer die Option Abbestellen verfügbar. Bei Werbe- und Mehrzweck-Agenten wird diese Option nach einer bestimmten Anzahl ungelesener Nachrichten auch direkt im Chat angezeigt. Die genauen Regeln variieren je nach Land.
Wenn Sie Abbestellen auswählen, werden zwei Aktionen gleichzeitig ausgelöst: Google Messages sendet ein länderspezifisches Keyword (z. B. „STOP“) an Ihren Agenten und die RBM-Plattform sendet ein
UNSUBSCRIBE-Ereignis an Ihren Webhook.Das Keyword wird durch den aus zwei Buchstaben bestehenden Ländercode der Telefonnummer des Nutzers bestimmt. In der folgenden Tabelle sind die Schlüsselwörter für jedes unterstützte Land aufgeführt.
Land (Ländercode) Keyword für Abmeldung Deutschland (DE), Indien (IN), Niederlande (NL), Vereinigtes Königreich (GB), USA (US) STOPPEN Spanien (ES), Mexiko (MX) BAJA Frankreich (FR) STOP Brasilien (BR) parar Nachdem der Nutzer das Abo gekündigt hat, bleibt die Unterhaltung in seinem Posteingang, es sei denn, sie wird als Spam gemeldet. In diesem Fall wird sie in den Ordner Als Spam markiert & blockiert verschoben.
Google überwacht Nachrichtenmuster, nachdem sich ein Nutzer abgemeldet hat, um Verstöße gegen Richtlinien und Geschäftsregeln zu erkennen.
Geschäftsregeln
- Als RBM-Partner, der diese Unterhaltung verwaltet, sind Sie dafür verantwortlich, der Abmeldeanfrage des Nutzers nachzukommen.
- Wenn Sie die Abmeldung nicht im Nachrichten-Thread durchführen können, müssen Sie sofort eine Bestätigungsnachricht mit einem direkten Link zur Website oder App senden, auf der Nutzer ihre Aboeinstellungen verwalten können.
- Nachdem der Nutzer die Nachrichten abbestellt hat, ist das Senden nicht essenzieller Nachrichten verboten.
- Wichtige Nachrichten sind weiterhin zulässig. Dazu gehören:
- Authentifizierungen, z. B. Einmalpasswörter (OTPs)
- Benachrichtigungen zu einem bestimmten Dienst, den der Nutzer angefordert und dem er zugestimmt hat
- Bestätigung der Abmeldeanfrage des Nutzers mit Informationen zur weiteren Verwaltung seiner Kommunikationseinstellungen
Beispiel
Wenn sich ein Nutzer von einem KI-Agenten einer Fluggesellschaft abmeldet, dessen Anwendungsfall Mehrfachnutzung ist, dürfen Sie keine Werbebotschaften mehr senden. Sie können jedoch Flugaktualisierungen senden, wenn der Nutzer ausdrücklich zugestimmt hat, Aktualisierungen für diesen bestimmten Flug zu erhalten.
Gründe für die Abmeldung
Wenn ein Nutzer Ihren Agenten abbestellt, kann er einen Grund aus den folgenden Optionen auswählen:
- Zu viele Nachrichten
- Ich habe mich nie dafür angemeldet
- Kein Interesse mehr
- Das sieht nach Betrug aus
- Sonstiges
Um die Auswahlverzerrung zu verringern, werden die ersten vier Optionen für jeden Nutzer in einer zufälligen Reihenfolge angezeigt. Diese Reihenfolge bleibt bei allen Besuchen des Nutzers gleich und Sonstige bleibt unten fixiert.
Die Gründe für die Kündigung werden zusammengefasst und in der Analyseübersicht angezeigt, damit du nachvollziehen kannst, warum Nutzer kündigen.
Nutzer abonniert die Unterhaltung wieder
Dieses Ereignis gibt an, dass ein Nutzer wieder Nachrichten von Ihrem Agenten erhalten möchte, einschließlich nicht wesentlicher Inhalte wie Werbeaktionen. Nutzer können dieses Ereignis auslösen, indem sie eine Unterhaltung, die sie zuvor in Google Messages abbestellt haben, wieder abonnieren.
Hier ist ein Beispiel für die JSON-Nutzlast:
{
"senderPhoneNumber": "PHONE_NUMBER",
"eventType": "SUBSCRIBE",
"eventId": "EVENT_ID",
"agentId": "AGENT_ID"
}So funktioniert das erneute Abonnieren
- Über die Option Abonnieren, die sowohl im Chatmenü als auch über einen In-Chat-Link verfügbar ist, können Nutzer eine Unterhaltung, die sie abbestellt hatten, erneut abonnieren.
Wenn Sie Abonnieren auswählen, werden zwei gleichzeitige Aktionen ausgelöst: Google Messages sendet ein länderspezifisches Keyword (z. B. „START“) an Ihren Agenten und die RBM-Plattform sendet ein SUBSCRIBE-Ereignis an Ihren Webhook. Das jeweilige Keyword wird durch den aus zwei Buchstaben bestehenden Ländercode der Telefonnummer des Nutzers bestimmt. In der folgenden Tabelle sind die Schlüsselwörter für jedes unterstützte Land aufgeführt.
Land (Ländercode) Keyword „Abonnieren“ Deutschland (DE), Indien (IN), Niederlande (NL), Vereinigtes Königreich (GB), USA (US) START Spanien (ES), Mexiko (MX) ALTA Frankreich (FR) Démarrer Brasilien (BR) começar
Geschäftsregeln
- Als RBM-Partner, der diese Unterhaltung verwaltet, sind Sie dafür verantwortlich, der Anfrage des Nutzers nachzukommen, das Abo wieder zu aktivieren.
- Das erneute Abonnieren gilt für alle Nachrichtentypen, einschließlich nicht wesentlicher Inhalte wie Werbeaktionen.
- Wenn ein Nutzer Ihrem Unternehmen nach dem Abmelden eine Nachricht sendet, kann dies als Anfrage zur erneuten Anmeldung betrachtet werden.
- Wenn ein Nutzer außerhalb des Messaging-Kanals (z. B. auf Ihrer Website) Nachrichten erneut abonniert, liegt es in Ihrer Verantwortung als RBM-Partner, seinen Status zu aktualisieren und das Senden von Nachrichten entsprechend fortzusetzen.
Plattformereignisse
Die RBM-Plattform sendet Plattformereignisse, um Ihren Agenten über Änderungen am Startstatus des Agenten oder über den Ablauf von Nachrichten zu informieren.
Der Aktivierungsstatus des KI-Agenten hat sich geändert
Die RBM-Plattform sendet bei jeder Änderung des Startstatus Ihres Agenten eine AgentLaunchEvent. Beispiel: Wenn sich der Status Ihres Agenten von PENDING in LAUNCHED ändert. Das Ereignis wird als Pub/Sub-Nachricht bereitgestellt. Um dieses Ereignis von anderen Ereignissen zu unterscheiden, prüfen Sie den Pfad message.attributes.type auf den Wert agent_launch_event.
Webhook-Konfiguration
Sie können Ihren Webhook auf Partner- oder Agent-Ebene verwenden, um diese Benachrichtigungen zu erhalten.
Vorbereitung
- Konfigurieren Sie Ihren Webhook für RBM-Nachrichten. Dies ist erforderlich, um Nachrichten und Ereignisse von Nutzern zu empfangen.
- Wenn Sie zwischen Nutzerereignissen und Ereignissen zum Startstatus des Agents unterscheiden möchten, prüfen Sie den Pfad
message.attributes.typeauf den Wertagent_launch_event.
Struktur der Ereignisnutzlast
Die AgentLaunchEvent wird als Pub/Sub-Nachricht bereitgestellt.
Beispiel:
{
"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"
}
Das Feld AgentLaunchEvent.LaunchState in der Ereignisnutzlast gibt den neuen Startstatus des Agenten an. Folgende Werte sind möglich:
| Wert | Aktivierungsstatus des KI-Agenten | Details |
|---|---|---|
PENDING |
Ausstehend | Die Anfrage wurde zur Überprüfung an einen Mobilfunkanbieter gesendet. |
LAUNCHED |
Eingeführt | Nachrichten sind bei einem bestimmten Mobilfunkanbieter zulässig. |
REJECTED |
Von einem bestimmten Mobilfunkanbieter abgelehnt | Der Ablehnungsgrund wird im Kommentar angegeben. |
SUSPENDED |
Bei einem bestimmten Mobilfunkanbieter gesperrt | Der Grund für die Sperrung wird im Kommentar angegeben. |
UNLAUNCHED |
Nicht aktiviert | Agenten, deren Aktivierung bei allen Mobilfunkanbietern aufgehoben wurde, können bearbeitet werden. |
Das Datenfeld enthält ein Base64-codiertes JSON-Objekt mit den Details zum Startstatus. Hier ein Beispiel für das decodierte JSON:
{
"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"
}
Vom Mobilfunkanbieter initiierte Änderungen des Launch-Status
Dies sind zulässige Übergänge, die in der Regel von Mobilfunkanbietern während des Überprüfungs- und Durchsetzungsprozesses vorgenommen werden:
| Alter Aktivierungsstatus | Neuer Einführungsstatus | Trigger-Aktion |
|---|---|---|
PENDING |
LAUNCHED |
Einführungsanfrage genehmigen |
PENDING |
REJECTED |
Einführungsanfrage ablehnen |
LAUNCHED |
SUSPENDED |
Sperrung aus Gründen der Durchsetzung/Verwaltung. |
SUSPENDED |
LAUNCHED |
Stellen Sie den aktiven Status eines KI-Agenten wieder her. |
SUSPENDED |
UNLAUNCHED |
Einen KI-Agenten beenden. |
REJECTED |
LAUNCHED |
Zuvor abgelehnte Launch-Anfrage genehmigen. |
Vom Partner initiierte Änderungen des Startstatus
Dies sind zulässige Übergänge, die normalerweise von Partnern durchgeführt werden:
| Alter Aktivierungsstatus | Neuer Einführungsstatus | Trigger-Aktion |
|---|---|---|
UNSPECIFIED |
PENDING |
Reichen Sie die Formulare zur Überprüfung ein. |
PENDING |
UNLAUNCHED |
Ausstehende Veröffentlichungsanfrage abbrechen |
UNLAUNCHED |
PENDING |
Reichen Sie die Formulare zur Überprüfung ein. |
REJECTED |
PENDING |
Reichen Sie die App noch einmal zur Überprüfung ein. |
SUSPENDED |
PENDING |
Reichen Sie die App noch einmal zur Überprüfung ein. |
Nachricht ist abgelaufen; Widerruf erfolgreich
Dieses Ereignis zeigt an, dass die Gültigkeitsdauer (TTL) der Nachricht abgelaufen ist und die Nachricht erfolgreich widerrufen wurde. Das ist ein guter Auslöser für Ihre Fallback-Messaging-Strategie.
Eine vollständige Liste der Formatierungs- und Wertoptionen finden Sie in der Referenz zu ServerEvent.
{
"phoneNumber": "PHONE_NUMBER",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID",
"eventType": "TTL_EXPIRATION_REVOKED",
"eventId": "EVENT_ID",
"sendTime": "TIMESTAMP"
}Nachricht ist abgelaufen; Widerruf fehlgeschlagen
Dieses Ereignis gibt an, dass die TTL der Nachricht abgelaufen ist, sie aber nicht erfolgreich widerrufen wurde.
Eine vollständige Liste der Formatierungs- und Wertoptionen finden Sie in der Referenz zu ServerEvent.
{
"phoneNumber": "PHONE_NUMBER",
"messageId": "MESSAGE_ID",
"agentId": "AGENT_ID",
"eventType": "TTL_EXPIRATION_REVOKE_FAILED",
"eventId": "EVENT_ID",
"sendTime": "TIMESTAMP"
}Die Zustellung von Nachrichten ist nicht garantiert.
- Wenn die Nachricht zugestellt wurde, erhalten Sie ein
DELIVERED-Ereignis an Ihrem Webhook. - Wenn die Nachricht nicht zugestellt wurde, verwenden Sie die Revoke API, um eine Widerrufsanfrage zu senden.
Wenn die Nachricht zeitkritisch ist, z. B. ein OTP oder eine Betrugswarnung, ist es am besten, die Nachricht über einen alternativen Kanal wie SMS zu senden, auch wenn dies zu doppelten Nachrichten an den Nutzer führt.