Ereignisse

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

• Servergeneriert: Wird von der RBM-Plattform an Ihren Agent gesendet.
• Vom Nutzer generiert: Wird vom Gerät des Nutzers an Ihren Agent gesendet
• Vom Agent generiert: Wird von Ihrem Agent an den Nutzer gesendet.

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 ein AgentLaunchEvent für jede Änderung des Startstatus Ihres Agents. 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

• Webhook für RBM-Messaging konfigurieren (erforderlich, um Nutzernachrichten und von Nutzern generierte Ereignisse zu empfangen).
• Um zwischen nutzergenerierten Ereignissen und Ereignissen zum Startstatus des Agents zu unterscheiden, prüfen Sie den message.attributes.type-Pfad auf den Wert agent_launch_event.

Struktur der Ereignisnutzlast

Die AgentLaunchEvent wird als Pub/Sub-Nachricht gesendet. Beispiel:

{
  "message": {
    "attributes": {
      "business_id": "[email protected]",
      "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:

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": "[email protected]",
      "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": "[email protected]",
      "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:

Nachricht ist abgelaufen; Widerruf erfolgreich

Die Nachricht ist abgelaufen und wurde erfolgreich widerrufen. Dieses Ereignis eignet sich gut als Auslöser 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 Antwort 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 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 Ereignis UNSUBSCRIBE gibt an, dass der Nutzer die Unterhaltung mit Ihrem Agent und dem Unternehmen, das er repräsentiert, beendet 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, sendet Google Messages eine SMS mit dem Text „STOP“ von der Nummer des Nutzers an den RBM-Agenten. Gleichzeitig sendet die RBM-Plattform ein UNSUBSCRIBE-Ereignis an den Webhook des Agents.
• Nachdem sich der Nutzer abgemeldet 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 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 Einstellungen für Mitteilungen

Beispiel

Wenn sich ein Nutzer von einem Airline-Kundenservicemitarbeiter abmeldet, dessen Anwendungsfall mehrfach verwendbar 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 der Nutzer Abonnieren auswählt, sendet Google Messages eine Nachricht mit dem Text „START“ von der Nummer des Nutzers an den RBM-Agent. Gleichzeitig sendet die RBM-Plattform ein SUBSCRIBE-Ereignis an den Webhook des Agents.

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

// 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);

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");

# 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)

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");

Der Kundenservicemitarbeiter sendet ein IS_TYPING-Ereignis.

Für Nutzer wird dieses Ereignis als Eingabeaufforderung angezeigt und informiert sie darüber, 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 des Tippanzeige-Indikators zurückzusetzen.

Mit dem folgenden Code wird ein IS_TYPING-Ereignis gesendet.

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',
}"

// 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!');
});

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");

# 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')

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");