Ereignisse empfangen

Ihr Agent empfängt Webhook-Ereignisse von der RBM-Plattform, die Sie sowohl über Nutzerinteraktionen als auch über Updates 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 oder seinen Nachrichten signalisieren.
  • Plattformereignisse: Benachrichtigungen zu Änderungen des Startstatus von Agenten und zum 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.

Nutzerereignisse

Nutzerereignisse sind Benachrichtigungen vom Gerät des Nutzers, in denen der Nachrichtenstatus oder Aboänderungen gemeldet werden (z.B. wenn der Nutzer in Google Messages sein Abo gekündigt oder sein Abo reaktiviert hat).

Eine vollständige Liste der Formatierungs- und Wertoptionen finden Sie in der Referenz zu UserEvent.

Nutzer erhält Nachricht vom Kundenservicemitarbeiter

Dieses Ereignis gibt an, dass eine Nachricht erfolgreich auf dem Gerät des Nutzers zugestellt wurde.

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

Nutzer liest Nachricht vom Kundenservicemitarbeiter

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 eine Antwort 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

Dieses Ereignis gibt an, dass der Nutzer den Erhalt unwichtiger Nachrichten wie Werbenachrichten von Ihrem Agent und dem Unternehmen, das er vertritt, abbestellt hat. Nutzer lösen dieses Ereignis aus, indem sie das RBM-Gespräch in Google Messages beenden.

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 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, 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 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:

  • 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 Nutzer sich abmelden.

Nutzer abonniert die Unterhaltung noch einmal

Dieses Ereignis gibt an, dass ein Nutzer wieder Nachrichten von Ihrem Agent erhalten möchte, einschließlich unwichtiger Inhalte wie Werbeaktionen. Nutzer können dieses Ereignis auslösen, indem sie eine Unterhaltung, die sie zuvor in Google Messages abgemeldet 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 die erneute Registrierung

  • Ü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 haben.

  • 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 die einzelnen unterstützten Länder 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 das 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.

Plattformereignisse

Die RBM-Plattform sendet Plattformereignisse, um Ihren Agent über Änderungen am Startstatus des Agents oder über Ablauf von Nachrichten zu informieren.

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 von PENDING in LAUNCHED ändert. Das Ereignis wird als Pub/Sub-Nachricht zugestellt. Um dieses Ereignis von anderen zu unterscheiden, prüfen Sie den message.attributes.type-Pfad 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

  • Webhook für RBM-Messaging konfigurieren (erforderlich, um Nutzernachrichten und Nutzerereignisse 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 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 Veränderungen
PENDING LAUNCHED Genehmigung des Agenten ausstehend.
PENDING REJECTED Der ausstehende Agent wurde abgelehnt.
LAUNCHED SUSPENDED Gestarteter Agent wurde gesperrt.
SUSPENDED LAUNCHED Gesperrter Agent wurde reaktiviert.
SUSPENDED TERMINATED Gesperrter Agent wurde beendet.
TERMINATED LAUNCHED Ein zurückgezogener Agent wurde gestartet.

Nachricht ist abgelaufen; Widerruf erfolgreich

Dieses Ereignis gibt an, dass die Gültigkeitsdauer (TTL) der Nachricht abgelaufen ist und die Nachricht erfolgreich widerrufen wurde. Das ist ein guter Trigger 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": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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.

Zurück
Ereignisse senden
Weiter
Funktionsprüfungen