Ereignisse empfangen

Ihr Agent erhält Webhook-Ereignisse von der RBM-Plattform, die Sie sowohl über Nutzerinteraktionen als auch über Updates auf Plattformebene informieren.

Diese Ereignisse werden nach ihrer Herkunft 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 Aktivierungsstatus des Agenten und über 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, usw. finden Sie unter Nachrichten empfangen.

Nutzerereignisse

Nutzerereignisse sind Benachrichtigungen vom Gerät des Nutzers, die den Nachrichtenstatus oder Änderungen des Abos melden (d.h., der Nutzer hat sich abgemeldet oder sich wieder angemeldet in Google Messages).

Vollständige Formatierungs- und Wertoptionen finden Sie in der UserEvent Referenz.

Nutzer erhält eine Nachricht vom Agenten

Dieses Ereignis zeigt an, dass eine Nachricht erfolgreich an das Gerät des Nutzers gesendet wurde.

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

Nutzer liest eine Nachricht vom 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 zeigt 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, 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

Dieses Ereignis zeigt an, dass der Nutzer sich abgemeldet hat, um keine unwichtigen Nachrichten mehr von Ihrem Agenten und dem Unternehmen, das er vertritt, zu erhalten, z. B. Werbenachrichten. Nutzer lösen dieses Ereignis aus, indem sie sich in Google Messages von der RBM-Unterhaltung abmelden.

Hier ein Beispiel für die JSON-Nutzlast:

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

So funktioniert die Abmeldung

  • 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 Abmelden 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 Keywords für jedes unterstützte Land aufgeführt.

    Land (Ländercode) Keyword für die Abmeldung
    USA (US), Indien (IN), Vereinigtes Königreich (GB), Deutschland (DE), Niederlande (NL) STOPPEN
    Spanien (ES), Mexiko (MX) BAJA
    Frankreich (FR) STOP
    Brasilien (BR) parar

  • 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 Spam und blockierte Kontakte verschoben.

  • Um Verstöße gegen Richtlinien und Geschäftsregeln zu erkennen, beobachtet Google die Nachrichtenmuster, nachdem sich ein Nutzer abgemeldet hat.

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 Nachrichtenverlauf durchführen können, müssen Sie sofort eine Bestätigungsnachricht mit einem direkten Link zur Website oder App senden, auf der Nutzer ihre Abopräferenzen verwalten können.
  • Nachdem sich der Nutzer abgemeldet hat, dürfen keine unwichtigen Nachrichten mehr gesendet werden.
  • Wichtige Nachrichten sind weiterhin zulässig. Dazu gehören:
    • Authentifizierungen wie 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 Agenten einer Fluggesellschaft abmeldet, dessen Anwendungsfall Mehrzweck ist, müssen Sie das Senden von Marketingnachrichten einstellen. 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 sich ein Nutzer von Ihrem Agenten abmeldet, kann er einen Grund aus den folgenden Optionen auswählen:

  • Spam
  • Noch nie angemeldet
  • Zu viele Nachrichten
  • Kein Interesse mehr
  • Sonstiges

Die Gründe für die Abmeldung werden in der Analytics-Übersicht angezeigt, damit Partner nachvollziehen können, warum sich Nutzer abmelden.

Nutzer meldet sich wieder für die Unterhaltung an

Dieses Ereignis zeigt an, dass ein Nutzer wieder Nachrichten von Ihrem Agenten erhalten möchte, einschließlich unwichtiger Inhalte wie Werbenachrichten. Nutzer können dieses Ereignis auslösen, indem sie sich in Google Messages wieder für eine Unterhaltung anmelden, von der sie sich zuvor abgemeldet haben.

Hier ein Beispiel für die JSON-Nutzlast:

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

So funktioniert das erneute Abonnieren

  • Mit der Option Abonnieren , die sowohl im Chatmenü als auch über einen In-Chat-Link verfügbar ist, können Nutzer sich wieder für eine Unterhaltung anmelden, 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 Agenten 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 für die Anmeldung
    USA (US), Indien (IN), Vereinigtes Königreich (GB), Deutschland (DE), Niederlande (NL) 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, sich wieder anzumelden.
  • Die erneute Anmeldung gilt für alle Nachrichtentypen, einschließlich unwichtiger Inhalte wie Werbenachrichten.
  • Wenn ein Nutzer nach der Abmeldung eine Nachricht an Ihr Unternehmen sendet, kann dies als Anfrage zur erneuten Anmeldung betrachtet werden.
  • Wenn sich ein Nutzer außerhalb des Messaging-Kanals (z. B. auf Ihrer Website) wieder anmeldet, sind Sie als RBM-Partner dafür verantwortlich, seinen Status zu aktualisieren und entsprechend Nachrichten zu senden.

Plattformereignisse

Die RBM-Plattform sendet Plattformereignisse, um Ihren Agenten über Änderungen des Aktivierungsstatus des Agenten oder über den Ablauf von Nachrichten zu informieren.

Der Aktivierungsstatus des Agenten hat sich geändert

Die RBM-Plattform sendet für jede Änderung des Aktivierungsstatus Ihres Agenten ein AgentLaunchEvent. Zum Beispiel, wenn sich der Status Ihres Agenten von PENDING zu LAUNCHED ändert. Das Ereignis wird als Pub/Sub-Nachricht gesendet. Um es 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 Agentenebene verwenden, um diese Benachrichtigungen zu erhalten.

Vorbereitung

  • Konfigurieren Sie Ihren Webhook für RBM-Messaging. Dies ist eine Voraussetzung für den Empfang von Nutzernachrichten und Nutzerereignissen.
  • Um zwischen Nutzerereignissen und Ereignissen zum Aktivierungsstatus des Agenten zu unterscheiden, prüfen Sie den message.attributes.type Pfad auf den Wert agent_launch_event.

Struktur der Ereignisnutzlast

Das 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 Aktivierungsstatus des Agenten an. Mögliche Werte:

Wert Aktivierungsstatus des Agenten Details
PENDING Ausstehend Die Anfrage wurde zur Überprüfung an einen Mobilfunkanbieter gesendet.
LAUNCHED Aktiviert Nachrichten sind bei einem bestimmten Mobilfunkanbieter zulässig.
REJECTED Bei einem bestimmten Mobilfunkanbieter abgelehnt Der Grund für die Ablehnung ist im Kommentar angegeben.
SUSPENDED Bei einem bestimmten Mobilfunkanbieter gesperrt Der Grund für die Sperrung ist im Kommentar angegeben.
UNLAUNCHED Nicht aktiviert Die Bearbeitung ist für Agents zulässig, die von allen Mobilfunkanbietern deaktiviert wurden.

Das Datenfeld enthält ein Base64-codiertes JSON-Objekt mit den Details zum Aktivierungsstatus. 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 Aktivierungsstatus

Dies sind zulässige Übergänge, die in der Regel von Mobilfunkanbietern während des Überprüfungs- und Durchsetzungsprozesses verarbeitet werden:

Alter Aktivierungsstatus Neuer Aktivierungsstatus Trigger-Aktion
PENDING LAUNCHED Aktivierungsanfrage genehmigen
PENDING REJECTED Aktivierungsanfrage ablehnen
LAUNCHED SUSPENDED Aus Durchsetzungs-/Administratorengründen sperren
SUSPENDED LAUNCHED Agenten wieder aktivieren
SUSPENDED UNLAUNCHED Agenten zurückziehen
REJECTED LAUNCHED Zuvor abgelehnte Aktivierungsanfrage genehmigen

Vom Partner initiierte Änderungen des Aktivierungsstatus

Dies sind zulässige Übergänge, die in der Regel von Partnern verarbeitet werden:

Alter Aktivierungsstatus Neuer Aktivierungsstatus Trigger-Aktion
UNSPECIFIED PENDING Zur Überprüfung einreichen
PENDING UNLAUNCHED Ausstehende Aktivierungsanfrage abbrechen
UNLAUNCHED PENDING Zur Überprüfung einreichen
REJECTED PENDING Noch einmal zur Überprüfung einreichen
SUSPENDED PENDING Noch einmal zur Überprüfung einreichen

Nachricht ist abgelaufen; Widerruf erfolgreich

Dieses Ereignis zeigt an, dass die Gültigkeitsdauer (Time-to-Live, TTL) der Nachricht abgelaufen ist und die Nachricht erfolgreich widerrufen wurde. Dies ist ein guter Trigger für Ihre Fallback-Messaging-Strategie.

Vollständige Formatierungs- und Wertoptionen finden Sie in der ServerEvent Referenz.

{
  "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 zeigt an, dass die TTL der Nachricht abgelaufen ist, sie aber nicht erfolgreich widerrufen wurde.

Vollständige Formatierungs- und Wertoptionen finden Sie in der ServerEvent Referenz.

{
  "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, senden Sie mit der Revoke API eine Widerrufsanfrage.

Wenn die Nachricht zeitkritisch ist, z. B. ein OTP oder eine Betrugswarnung, sollten Sie sie über einen alternativen Kanal wie SMS senden, auch wenn dies zu doppelten Nachrichten für den Nutzer führt.

Zurück
Ereignisse senden
Weiter
Funktionsprüfungen