Ereignisse

Ereignisse sind Benachrichtigungen, die Ihr Agent senden und empfangen kann. Es gibt drei Arten von Ereignissen:

Vom Server generierte Ereignisse

Die RBM-Plattform sendet Ereignisse, um Ihren Agent über Aktualisierungen auf Serverebene wie Ablauf von Nachrichten zu informieren.

Informationen zu Formatierungs- und Wertoptionen finden Sie unter ServerEvent.

Der Aktivierungsstatus des Agents hat sich geändert

Die RBM-Plattform sendet für jede Änderung des Startstatus Ihres Agents eine AgentLaunchEvent. Wenn sich beispielsweise der Status Ihres Agents nach der Genehmigung durch den Mobilfunkanbieter von PENDING in LAUNCHED ändert, erhalten Sie ein AgentLaunchEvent-Ereignis, das diese Änderung angibt. Diese Ereignisse werden für alle RBM-Agents und für alle Änderungen des Carrier-Einführungsstatus gesendet.

Webhook-Konfiguration

Sie können Ihren Webhook auf Partner- oder Agent-Ebene verwenden, um diese Benachrichtigungen zu erhalten.

Vorbereitung

Struktur der Ereignisnutzlast

Die AgentLaunchEvent wird als Pub/Sub-Nachricht gesendet. 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 Agents Details
UNLAUNCHED Nicht veröffentlicht Bearbeiten ist zulässig.
PENDING Ausstehend Die Anfrage wurde zur Überprüfung an einen Mobilfunkanbieter gesendet.
LAUNCHED Eingeführt Nachrichten sind bei einem bestimmten Mobilfunkanbieter zulässig.
REJECTED Bei 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.

Das Datenfeld enthält ein Base64-codiertes JSON-Objekt mit den Details zum Startstatus. Hier ist 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"
    }

In der folgenden Tabelle sind die Startstatus von Agents und die Aktionen aufgeführt, die sie auslösen:

Alter Einführungsstatus Neuer Einführungsstatus Auslöser für Änderungen
PENDING LAUNCHED Genehmigung des Kundenservicemitarbeiters ausstehend.
PENDING REJECTED Ausstehender Agent abgelehnt.
LAUNCHED SUSPENDED Gestarteter Agent wurde gesperrt.
SUSPENDED LAUNCHED Gesperrter Agent wurde reaktiviert.
SUSPENDED TERMINATED Gesperrter Agent wurde beendet.
TERMINATED LAUNCHED Der zurückgezogene Agent wurde gestartet.

Nachricht ist abgelaufen; Widerruf erfolgreich

Die Nachricht ist abgelaufen und wurde erfolgreich widerrufen. Dieses Ereignis eignet sich gut als Trigger für Ihre Fallback-Messaging-Strategie.

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

Nachricht ist abgelaufen; Widerruf fehlgeschlagen

Die Nachricht ist abgelaufen, wurde aber nicht widerrufen.

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

Die Zustellung von Nachrichten wird 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 Einmalpasswort oder eine Betrugswarnung, sollten Sie sie über einen alternativen Kanal wie SMS senden, auch wenn dies zu doppelten Nachrichten an den Nutzer führt.

Von Nutzern erstellte Ereignisse

Wie bei Nutzernachrichten und Funktionsprüfungen empfängt Ihr Agent Nutzerereignisse als JSON.

Informationen zu Formatierungs- und Wertoptionen finden Sie unter UserEvent.

Nutzer erhält Nachricht vom Kundenservicemitarbeiter

Dieses Ereignis gibt an, dass eine Nachricht zugestellt wurde.

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

Nutzer liest die Nachricht des Kundenservicemitarbeiters

Dieses Ereignis gibt 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 gerade etwas eingibt.

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

Nutzer sendet eine SMS

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

Nutzer sendet eine Datei

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

Nutzer tippt auf einen Antwortvorschlag

Wenn ein Nutzer auf eine vorgeschlagene Antwort tippt, erhält Ihr Agent ein Ereignis mit den Postback-Daten und dem Text der Antwort.

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

Nutzer tippt auf eine vorgeschlagene Aktion

Wenn ein Nutzer auf eine vorgeschlagene Aktion tippt, erhält Ihr Agent ein Ereignis mit den Postback-Daten der Aktion.

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

Nutzer meldet sich von der Unterhaltung ab

Wenn ein Nutzer keine unwichtigen Nachrichten mehr von einem Unternehmen erhalten möchte, z. B. Werbenachrichten, kann er die RBM-Unterhaltung in Google Messages abbestellen.

Das UNSUBSCRIBE-Ereignis gibt an, dass der Nutzer das Abo für die Unterhaltung mit Ihrem Agent und dem Unternehmen, das er repräsentiert, gekündigt hat. Hier ein Beispiel für die JSON-Nutzlast:

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

Funktionsweise

  • Im Chatmenü ist immer die Option Abmelden verfügbar. Bei Werbe- und Mehrzweck-Agents wird diese Option auch direkt im Chat angezeigt, nachdem eine bestimmte Anzahl ungelesener Nachrichten eingegangen ist (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 Kundenservicemitarbeiter 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 Keywords für jedes unterstützte Land aufgeführt.

    Land (Ländercode) Keyword zum Abbestellen
    USA (US), Indien (IN), Vereinigtes Königreich (GB), Deutschland (DE) STOPPEN
    Spanien (ES), Mexiko (MX) BAJA
    Frankreich (FR) STOPPEN
    Brasilien (BR) parar

  • Nachdem sich der Nutzer abgemeldet hat, bleibt die Unterhaltung in seinem Posteingang, sofern sie nicht als Spam gemeldet wird. In diesem Fall wird sie in den Ordner Als Spam markiert und blockiert verschoben.

  • Um Richtlinien- und Geschäftsregelverstöße zu erkennen, überwacht Google Nachrichtenmuster, nachdem sich ein Nutzer abgemeldet hat.

Geschäftsregeln

  • Als RBM-Partner, der diese Unterhaltung verwaltet, sind Sie dafür verantwortlich, der Anfrage des Nutzers nachzukommen, das Abo zu kündigen.
  • Wenn Sie die Abmeldung nicht im Nachrichtenverlauf vornehmen 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, dürfen keine unwichtigen Nachrichten mehr gesendet werden.
  • Wichtige Nachrichten sind weiterhin zulässig. Dazu gehören:
    • Authentifizierungen, z. B. Einmalpasswörter
    • 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 Airline-Kundenservicemitarbeiter abmeldet, dessen Anwendungsfall Mehrfachverwendung ist, müssen Sie das Senden von Marketingnachrichten einstellen. Sie dürfen 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 Agent abbestellt, kann er einen der folgenden Gründe auswählen:

  • Nicht angemeldet
  • Zu viele Nachrichten
  • Kein Interesse mehr
  • Spam
  • Sonstiges

Derzeit werden die Gründe für die Kündigung nicht an Partner oder Mobilfunkanbieter weitergegeben.

Nutzer abonniert die Unterhaltung noch einmal

Nutzer können ein Abo für eine Unterhaltung, die sie zuvor in Google Messages gekündigt haben, wieder abschließen.

Das SUBSCRIBE-Ereignis gibt an, dass ein Nutzer Nachrichten von Ihrem Agent erhalten möchte, einschließlich nicht unbedingt erforderlicher Inhalte wie Werbeaktionen. Hier ist ein Beispiel für die JSON-Nutzlast:

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

Funktionsweise

  • Über die Option Abonnieren, die sowohl über das Chatmenü als auch über einen In-Chat-Link verfügbar ist, können Nutzer eine Unterhaltung wieder abonnieren, von der sie sich abgemeldet hatten.

  • Wenn Sie Abonnieren auswählen, werden zwei Aktionen gleichzeitig ausgelöst: Google Messages sendet ein länderspezifisches Keyword (z. B. „START“) an Ihren Agent und die RBM-Plattform sendet ein SUBSCRIBE-Ereignis an Ihren Webhook.

    Das spezifische Keyword wird durch den aus zwei Buchstaben bestehenden Ländercode der Telefonnummer des Nutzers bestimmt. In der folgenden Tabelle sind die Keywords für jedes unterstützte Land aufgeführt.

    Land (Ländercode) Keyword „Abonnieren“
    USA (US), Indien (IN), Vereinigtes Königreich (GB), Deutschland (DE) STARTEN
    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 nach erneuter Anmeldung nachzukommen.
  • Die erneute Anmeldung gilt für alle Nachrichtentypen, einschließlich nicht unbedingt erforderlicher Inhalte wie Werbeaktionen.
  • Wenn ein Nutzer Ihrem Unternehmen nach der Abmeldung eine Nachricht sendet, kann dies als erneute Anmeldung betrachtet werden.
  • Wenn ein Nutzer sein Abo außerhalb des Messaging-Kanals reaktiviert (z. B. auf Ihrer Website), sind Sie als RBM-Partner dafür verantwortlich, seinen Status zu aktualisieren und entsprechend wieder Nachrichten zu senden.

Von KI-Agenten generierte Ereignisse

Ihr Agent sendet Ereignisse, um menschliche Interaktionen zu simulieren und dem Nutzer zu versichern, dass er auf seine Nachrichten reagiert. Für Nutzer werden Ereignisse als Benachrichtigungen in ihren Unterhaltungen angezeigt.

Informationen zu Formatierungs- und Wertoptionen finden Sie unter phones.agentEvents.

Der Agent sendet ein READ-Ereignis.

Für Nutzer wird dieses Ereignis als Lesebestätigung für eine bestimmte Nachricht angezeigt. Der Nutzer wird darüber informiert, dass die RBM-Plattform seine Nachricht zugestellt hat und der Agent sie verarbeitet.

Mit dem folgenden Code wird ein READ-Ereignis für eine Nachricht mit einem passenden messageId gesendet.

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);
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

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");
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

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)
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

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");
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

Der Agent sendet ein IS_TYPING-Ereignis.

Für Nutzer wird dieses Ereignis als Eingabeaufforderung angezeigt und sie wissen, dass Ihr Agent eine Nachricht verfasst. Die Tippanzeige läuft nach kurzer Zeit (ca. 20 Sekunden) ab oder wenn das Gerät des Nutzers eine neue Nachricht von Ihrem Agent erhält. Ihr Agent kann mehrere IS_TYPING-Ereignisse senden, um den Ablauf-Timer für die Tippanzeige zurückzusetzen.

Mit dem folgenden Code wird ein IS_TYPING-Ereignis gesendet.

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!');
});
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

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");
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

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')
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.

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");
 Dieser Code ist ein Auszug aus einem RBM-Beispielagenten.
Zurück
Nachrichten empfangen
Weiter
Funktionsprüfungen