Odbieranie zdarzeń

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

Te zdarzenia są podzielone na kategorie według ich pochodzenia:

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

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

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

Zdarzenia użytkownika

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 ponownie ją wykupił w Wiadomościach Google).

Pełne informacje o formatowaniu i opcjach wartości znajdziesz w dokumentacji UserEvent.

Użytkownik otrzymuje wiadomość od agenta

To zdarzenie oznacza, ż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 oznacza, ż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 oznacza, że użytkownik pisze 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, Twój agent otrzyma zdarzenie z danymi zwrotnymi działania.

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

Użytkownik anuluje subskrypcję rozmowy

To zdarzenie oznacza, że użytkownik zrezygnował z otrzymywania mniej ważnych wiadomości, takich jak promocje, od Twojego agenta i firmy, którą reprezentuje. Użytkownicy wywołują to zdarzenie, anulując 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 wielokrotnego użytku ta opcja pojawia się też bezpośrednio na czacie po określonej liczbie nieprzeczytanych wiadomości (konkretne reguły różnią się w zależności od kraju).

  • Wybranie opcji Anuluj subskrypcję powoduje 2 jednoczesne działania: Wiadomości Google wysyłają do Twojego agenta słowo kluczowe specyficzne dla danego kraju (np. „STOP”), a platforma RBM wysyła do Twojego webhooka zdarzenie UNSUBSCRIBE.

    Słowo kluczowe jest określane przez dwuliterowy kod 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 anulowania subskrypcji
    Stany Zjednoczone (US), Indie (IN), Wielka Brytania (GB), Niemcy (DE), Holandia (NL) STOP
    Hiszpania (ES), Meksyk (MX) BAJA
    Francja (FR) STOP
    Brazylia (BR) parar

  • Gdy użytkownik anuluje subskrypcję, rozmowa pozostaje 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 anulowaniu subskrypcji przez użytkownika.

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ć swoimi preferencjami subskrypcji.
  • Po anulowaniu subskrypcji przez użytkownika wysyłanie mniej ważnych wiadomości jest zabronione.
  • Wiadomości ważne są nadal dozwolone. Należą do nich:
    • Uwierzytelnianie, np. hasła jednorazowe.
    • Powiadomienia o konkretnej usłudze, o którą użytkownik poprosił i na którą wyraził zgodę.
    • Potwierdzenie prośby użytkownika o anulowanie subskrypcji wraz z informacjami o dalszym zarządzaniu preferencjami komunikacji.

Przykład

Jeśli użytkownik anuluje subskrypcję agenta linii lotniczych, który jest używany do wielu celów, musisz przestać wysyłać wiadomości marketingowe. Możesz jednak wysyłać aktualizacje lotów, jeśli użytkownik wyraził na to zgodę.

Powody anulowania subskrypcji

Gdy użytkownik anuluje subskrypcję Twojego agenta, może wybrać powód z tych opcji:

  • Spam
  • Nigdy się nie zarejestrowano
  • Za dużo wiadomości
  • Już nie interesuje mnie ten kanał
  • Inne

Powody anulowania subskrypcji są widoczne w przeglądzie Analytics, aby pomóc partnerom zrozumieć, dlaczego użytkownicy anulują subskrypcję.

Użytkownik ponownie subskrybuje rozmowę

To zdarzenie oznacza, ż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 ponowne subskrybowanie

  • Opcja Subskrybuj dostępna w menu czatu i za pomocą linku bezpośrednio na czacie umożliwia użytkownikom ponowne subskrybowanie rozmowy, z której wcześniej zrezygnowali.

  • Wybranie opcji Subskrybuj powoduje 2 jednoczesne działania: Wiadomości Google wysyłają do Twojego agenta słowo kluczowe specyficzne dla danego kraju (np. „START”), a platforma RBM wysyła do Twojego webhooka zdarzenie SUBSCRIBE. Konkretne słowo kluczowe jest określane przez dwuliterowy kod 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 subskrypcji
    Stany Zjednoczone (US), Indie (IN), Wielka Brytania (GB), Niemcy (DE), Holandia (NL) 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 ponowne subskrybowanie.
  • Ponowne subskrybowanie dotyczy wszystkich typów wiadomości, w tym mniej ważnych treści, takich jak promocje.
  • Jeśli użytkownik wyśle do Twojej firmy wiadomość po anulowaniu subskrypcji, można to uznać za prośbę o ponowne subskrybowanie.
  • Jeśli użytkownik ponownie subskrybuje poza kanałem wiadomości (np. w Twojej witrynie), Twoim obowiązkiem jako partnera RBM jest zaktualizowanie jego stanu i wznowienie wysyłania wiadomości.

Zdarzenia platformy

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

Zmieniono stan uruchamiania agenta

Platforma RBM wysyła AgentLaunchEvent przy każdej zmianie stanu uruchamiania agenta. Na przykład gdy stan agenta zmieni się z PENDING na LAUNCHED. Zdarzenie jest dostarczane jako wiadomość Pub/Sub. Aby odróżnić je od innych zdarzeń, sprawdź ścieżkę message.attributes.type pod kątem wartości agent_launch_event.

Konfiguracja webhooka

Do odbierania tych powiadomień możesz używać webhooka na poziomie partnera lub agenta.

Wymagania wstępne

  • Skonfiguruj webhooka do obsługi wiadomości RBM (jest to wymagane do odbierania wiadomości od użytkowników i zdarzeń użytkownika).
  • Aby odróżnić zdarzenia użytkownika od zdarzeń stanu uruchamiania agenta, sprawdź ścieżkę message.attributes.type pod kątem wartości agent_launch_event.

Struktura ładunku zdarzenia

Element 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 uruchamiania agenta. 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 Odrzucona przez danego operatora Powód odrzucenia jest podany w komentarzu.
SUSPENDED Zawieszony u danego operatora Powód zawieszenia jest podany w komentarzu.
UNLAUNCHED Nieuruchomiony Edytowanie jest dozwolone w przypadku agentów, którzy zostali wycofani z uruchomienia u wszystkich operatorów.

Pole danych zawiera obiekt JSON zakodowany w standardzie Base64 ze szczegółami stanu uruchamiania. 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 uruchamiania zainicjowane przez operatora

Są to 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 Odrzuć prośbę o uruchomienie.
LAUNCHED SUSPENDED Zawieszenie z powodu egzekwowania lub administracji.
SUSPENDED LAUNCHED Przywróć agenta do stanu aktywnego.
SUSPENDED UNLAUNCHED Zakończ działanie agenta.
REJECTED LAUNCHED Zatwierdź wcześniej odrzuconą prośbę o uruchomienie.

Zmiany stanu uruchamiania zainicjowane przez partnera

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

Stary stan uruchamiania Nowy stan uruchamiania Działanie wyzwalacza
UNSPECIFIED PENDING Prześlij do sprawdzenia.
PENDING UNLAUNCHED Anuluj oczekującą prośbę 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; wycofanie się powiodło

To zdarzenie oznacza, że upłynął czas życia wiadomości (TTL) i wiadomość została wycofana. Jest to dobry wyzwalacz dla strategii wysyłania wiadomości zastępczych.

Pełne informacje o formatowaniu i opcjach wartości 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; wycofanie się nie powiodło

To zdarzenie oznacza, że upłynął czas życia wiadomości (TTL), ale nie udało się jej wycofać.

Pełne informacje o formatowaniu i opcjach wartości 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 w webhooku zdarzenie DELIVERED.
  • Jeśli wiadomość nie została dostarczona, użyj interfejsu API revoke, aby wysłać prośbę o wycofanie.

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

Wstecz
Wysyłaj wydarzenia
Dalej
Testy możliwości