Odbieranie zdarzeń

Twój agent otrzymuje z platformy RBM zdarzenia webhooka, które powiadamiają Cię o interakcjach użytkowników i aktualizacjach na poziomie platformy.

Zdarzenia te są podzielone na kategorie według ich pochodzenia:

  • Zdarzenia użytkownika: powiadomienia wysyłane z urządzenia użytkownika do agenta, które sygnalizują interakcję z agentem.
  • Zdarzenia platformy: powiadomienia o zmianach stanu uruchomienia agenta i wygaśnięciu wiadomości wysyłane przez platformę RBM.

Szczegółowe informacje o zdarzeniach stanu, które agent wysyła na urządzenie użytkownika, znajdziesz w artykule Wysyłanie zdarzeń.

Szczegółowe informacje o tym, jak obsługiwać wiadomości użytkowników, takie jak tekst, pliki, lokalizacje i inne, znajdziesz w artykule Odbieranie wiadomości.

Zdarzenia dotyczące użytkowników

Zdarzenia użytkownika to powiadomienia z urządzenia użytkownika, które informują o stanie wiadomości lub zmianach subskrypcji (np. użytkownik anulował subskrypcję lub subskrybuje ponownie w Wiadomościach Google).

Pełne informacje o opcjach formatowania i wartościach znajdziesz w dokumentacji UserEvent.

Użytkownik otrzymuje wiadomość od agenta

To zdarzenie wskazuje, że wiadomość została dostarczona na urządzenie użytkownika.

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

Użytkownik odczytuje wiadomość od agenta

To zdarzenie wskazuje, że wiadomość została otwarta lub potwierdzona.

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

Użytkownik zaczyna pisać

To zdarzenie wskazuje, że użytkownik wpisuje odpowiedź.

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

Użytkownik klika sugerowane działanie

Gdy użytkownik kliknie sugerowane działanie, agent otrzyma zdarzenie z danymi postbacku działania.

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

Użytkownik anuluje subskrypcję rozmowy

To zdarzenie wskazuje, że użytkownik zrezygnował z otrzymywania od Twojego agenta i firmy, którą reprezentuje, mniej ważnych wiadomości, takich jak promocje. Użytkownicy wywołują to zdarzenie, gdy anulują subskrypcję rozmowy RBM w Wiadomościach Google.

Oto przykład ładunku JSON:

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

Jak działa anulowanie subskrypcji

  • Opcja Anuluj subskrypcję jest zawsze dostępna w menu czatu. W przypadku agentów promocyjnych i wielofunkcyjnych ta opcja pojawia się również bezpośrednio na czacie po określonej liczbie nieprzeczytanych wiadomości (konkretne zasady różnią się w zależności od kraju).
  • Wybranie opcji Anuluj subskrypcję powoduje jednoczesne wykonanie 2 działań: Wiadomości Google wysyłają do agenta słowo kluczowe właściwe dla danego kraju (np. „STOP”), a platforma RBM wysyła do Twojego webhooka zdarzenie UNSUBSCRIBE.

    Słowo kluczowe jest określane na podstawie dwuliterowego kodu kraju w numerze telefonu użytkownika. W tabeli poniżej znajdziesz słowa kluczowe dla każdego obsługiwanego kraju.

    Kraj (kod kraju) Słowo kluczowe dotyczące anulowania subskrypcji
    Holandia (NL), Indie (IN), Niemcy (DE), Stany Zjednoczone (US), Wielka Brytania (GB) STOP
    Hiszpania (ES), Meksyk (MX) BAJA
    Francja (FR) STOP
    Brazylia (BR) parar
  • Gdy użytkownik anuluje subskrypcję, rozmowa pozostanie w jego skrzynce odbiorczej, chyba że zostanie zgłoszona jako spam. W takim przypadku zostanie przeniesiona do folderu Spam i zablokowane.

  • Aby wykrywać naruszenia zasad i reguł biznesowych, Google monitoruje wzorce wiadomości po tym, jak użytkownik anuluje subskrypcję.

Reguły biznesowe

  • Jako partner RBM, który zarządza tą rozmową, musisz spełnić prośbę użytkownika o anulowanie subskrypcji.
  • Jeśli nie możesz anulować subskrypcji w wątku wiadomości, musisz natychmiast wysłać wiadomość z potwierdzeniem i bezpośrednim linkiem do witryny lub aplikacji, w której użytkownicy mogą zarządzać preferencjami subskrypcji.
  • Po anulowaniu subskrypcji przez użytkownika wysyłanie nieistotnych wiadomości jest zabronione.
  • Ważne wiadomości są nadal dozwolone. Są to między innymi:
    • uwierzytelnianie, np. hasła jednorazowe;
    • powiadomienia dotyczące konkretnej usługi, o którą poprosił użytkownik i na którą wyraził zgodę;
    • Potwierdzenie prośby użytkownika o anulowanie subskrypcji wraz z informacjami o dalszym zarządzaniu preferencjami dotyczącymi komunikacji.

Przykład

Jeśli użytkownik zrezygnuje z subskrypcji agenta linii lotniczych, którego przypadek użycia jest wielokrotnego użytku, musisz przestać wysyłać przekazy marketingowe. Możesz jednak wysyłać aktualizacje dotyczące lotu, jeśli użytkownik wyraził wyraźną zgodę na otrzymywanie aktualizacji dotyczących tego konkretnego lotu.

Powody anulowania subskrypcji

Gdy użytkownik anuluje subskrypcję Twojego agenta, może wybrać jedną z tych opcji:

  • Za dużo wiadomości
  • Supskrypcja nie został dokonana przeze mnie
  • Już mnie to nie interesuje
  • To wygląda na oszustwo
  • Inne

Aby ograniczyć błąd selekcji, pierwsze 4 opcje są wyświetlane każdemu użytkownikowi w losowej kolejności. Ta kolejność pozostaje niezmienna podczas wizyt użytkownika, a opcja Inne pozostaje na dole.

Powody rezygnacji z subskrypcji są agregowane i wyświetlane w Przeglądzie statystyk, aby pomóc Ci zrozumieć, dlaczego użytkownicy rezygnują z subskrypcji.

Użytkownik ponownie subskrybuje rozmowę

To zdarzenie wskazuje, że użytkownik chce ponownie otrzymywać wiadomości od Twojego agenta, w tym mniej ważne treści, takie jak promocje. Użytkownicy mogą wywołać to zdarzenie, ponownie subskrybując rozmowę, z której wcześniej zrezygnowali w Wiadomościach Google.

Oto przykład ładunku JSON:

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

Jak działa ponowna subskrypcja

  • Opcja Subskrybuj, dostępna zarówno w menu czatu, jak i za pomocą linku bezpośrednio na czacie, umożliwia użytkownikom ponowne zasubskrybowanie rozmowy, z której wcześniej zrezygnowali.
  • Wybranie opcji Subskrybuj powoduje jednoczesne wykonanie 2 działań: Wiadomości Google wysyłają do Twojego agenta słowo kluczowe właściwe dla danego kraju (np. „START”), a platforma RBM wysyła do Twojego webhooka zdarzenie SUBSCRIBE. Konkretne słowo kluczowe jest określane na podstawie dwuliterowego kodu kraju numeru telefonu użytkownika. W tabeli poniżej znajdziesz słowa kluczowe dla poszczególnych obsługiwanych krajów.

    Kraj (kod kraju) Słowo kluczowe dotyczące subskrypcji
    Holandia (NL), Indie (IN), Niemcy (DE), Stany Zjednoczone (US), Wielka Brytania (GB) START
    Hiszpania (ES), Meksyk (MX) ALTA
    Francja (FR) Démarrer
    Brazylia (BR) começar

Reguły biznesowe

  • Jako partner RBM, który zarządza tą rozmową, musisz spełnić prośbę użytkownika o ponowną subskrypcję.
  • Ponowna subskrypcja dotyczy wszystkich typów wiadomości, w tym treści nieistotnych, takich jak promocje.
  • Jeśli użytkownik wyśle wiadomość do Twojej firmy po anulowaniu subskrypcji, może to zostać uznane za prośbę o ponowną subskrypcję.
  • Jeśli użytkownik ponownie zasubskrybuje treści poza kanałem wiadomości (np. na Twojej stronie internetowej), jako partner RBM musisz zaktualizować jego stan i odpowiednio wznowić wysyłanie wiadomości.

Zdarzenia na platformie

Platforma RBM wysyła zdarzenia platformy, aby powiadomić agenta o zmianach stanu uruchomienia agenta lub wygaśnięciu wiadomości.

Stan uruchamiania agenta uległ zmianie

Platforma RBM wysyła AgentLaunchEvent przy każdej zmianie stanu uruchomienia agenta. Na przykład gdy stan agenta zmieni się z PENDING na LAUNCHED. Zdarzenie jest dostarczane jako komunikat Pub/Sub. Aby odróżnić to zdarzenie od innych, sprawdź, czy ścieżka message.attributes.type ma wartość agent_launch_event.

Konfiguracja webhooka

Aby otrzymywać te powiadomienia, możesz użyć webhooka na poziomie partnera lub agenta.

Wymagania wstępne

  • Skonfiguruj webhooka na potrzeby wiadomości RBM (jest to wymagane do odbierania wiadomości i zdarzeń użytkowników).
  • Aby odróżnić zdarzenia użytkownika od zdarzeń stanu uruchomienia agenta, sprawdź, czy ścieżka message.attributes.type ma wartość agent_launch_event.

Struktura ładunku zdarzenia

AgentLaunchEvent jest dostarczany jako wiadomość Pub/Sub.

Oto przykład:

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

Pole AgentLaunchEvent.LaunchState w ładunku zdarzenia wskazuje nowy stan uruchomienia agenta. Oto możliwe wartości:

Wartość Stan uruchamiania agenta Szczegóły
PENDING Oczekujące Prośba została wysłana do operatora w celu sprawdzenia.
LAUNCHED Uruchomiony Wiadomości są dozwolone u danego operatora.
REJECTED Odrzucone u danego operatora Powód odrzucenia jest podany w komentarzu.
SUSPENDED zawieszone u danego operatora, Powód zawieszenia jest podany w komentarzu.
UNLAUNCHED Nie uruchomiono Edytowanie jest dozwolone w przypadku agentów, którzy zostali wycofani przez wszystkich operatorów.

Pole danych zawiera obiekt JSON zakodowany w standardzie Base64 ze szczegółami stanu uruchomienia. Oto przykład zdekodowanego kodu 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"
}

Zmiany stanu uruchomienia zainicjowane przez operatora

Oto dozwolone przejścia, które są zwykle obsługiwane przez operatorów podczas procesu sprawdzania i egzekwowania:

Stary stan uruchamiania Nowy stan uruchamiania Działanie wyzwalacza
PENDING LAUNCHED Zatwierdź prośbę o uruchomienie.
PENDING REJECTED odrzucić prośbę o uruchomienie,
LAUNCHED SUSPENDED zawieszenie z powodu egzekwowania zasad lub z powodów administracyjnych,
SUSPENDED LAUNCHED przywrócić agenta do stanu aktywnego,
SUSPENDED UNLAUNCHED Zakończ działanie agenta.
REJECTED LAUNCHED Zatwierdź odrzuconą wcześniej prośbę o uruchomienie.

Zmiany stanu uruchomienia zainicjowane przez partnera

Oto dozwolone przejścia, które zwykle są obsługiwane przez partnerów:

Stary stan uruchamiania Nowy stan uruchamiania Działanie wyzwalacza
UNSPECIFIED PENDING Prześlij do sprawdzenia.
PENDING UNLAUNCHED Anulowanie oczekującej prośby o uruchomienie.
UNLAUNCHED PENDING Prześlij do sprawdzenia.
REJECTED PENDING Prześlij ponownie do sprawdzenia.
SUSPENDED PENDING Prześlij ponownie do sprawdzenia.

Wiadomość wygasła; unieważnienie się powiodło

To zdarzenie wskazuje, że czas życia (TTL) wiadomości wygasł i została ona pomyślnie unieważniona. To dobry moment na uruchomienie strategii wiadomości zastępczych.

Pełne informacje o opcjach formatowania i wartościach znajdziesz w dokumentacji ServerEvent.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

Wiadomość wygasła; nie udało się jej unieważnić

To zdarzenie wskazuje, że czas TTL wiadomości wygasł, ale nie została ona pomyślnie unieważniona.

Pełne informacje o opcjach formatowania i wartościach znajdziesz w dokumentacji ServerEvent.

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

Dostarczenie wiadomości nie jest gwarantowane.

  • Jeśli wiadomość została dostarczona, otrzymasz zdarzenie DELIVERED w webhooku.
  • Jeśli wiadomość nie została dostarczona, użyj interfejsu API do unieważniania, aby wysłać prośbę o unieważnienie.

Jeśli wiadomość jest pilna, np. zawiera hasło jednorazowe lub ostrzeżenie o oszustwie, najlepiej wysłać ją za pomocą alternatywnego kanału, np. SMS-a, nawet jeśli spowoduje to wysłanie do użytkownika zduplikowanych wiadomości.