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 opcje formatowania i wartości 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 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 wskazuje, ż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 wykonanie 2 działań jednocześnie: 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 2-literowy kod kraju numeru 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ł wyraźną zgodę na otrzymywanie aktualizacji dotyczących konkretnego lotu.

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 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 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 wykonanie 2 działań jednocześnie: 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 2-literowy kod kraju numeru 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 komunikat 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 otrzymywania tych powiadomień możesz użyć 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 komunikat 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. Oto możliwe wartości:

Wartość Stan uruchamiania agenta Szczegóły
PENDING Oczekuje Prośba została wysłana do operatora do sprawdzenia.
LAUNCHED Uruchomiony Wiadomości są dozwolone u danego operatora.
REJECTED Odrzucony 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 powodów administracyjnych lub związanych z egzekwowaniem zasad.
SUSPENDED LAUNCHED Przywróć agenta do stanu aktywnego.
SUSPENDED UNLAUNCHED Zakończ działanie agenta.

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.

Wiadomość wygasła; wycofanie się powiodło

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

Pełne opcje formatowania i wartości znajdziesz w dokumentacji ServerEvent.

{
  "phoneNumber": "[phone number]" ,
  "messageId": "[RCS message ID]",
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

Wiadomość wygasła; wycofanie się nie powiodło

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

Pełne opcje formatowania i wartości znajdziesz w dokumentacji ServerEvent.

{
  "phoneNumber": "[phone number]",
  "messageId": "[RCS message ID]",
  "agentId": "[bot ID]",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "[unique ID]",
  "sendTime": "[time stamp]"
}

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ą alternatywnym 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