Ereignisse empfangen

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.type auf den Wert agent_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.