Odbieranie zdarzeń

Agent otrzymuje z platformy RBM zdarzenia webhook, które informują o interakcjach użytkowników i aktualizacjach na poziomie platformy.

Są one podzielone na kategorie według pochodzenia:

  • Zdarzenia użytkownika: powiadomienia wysyłane z urządzenia użytkownika do Twojego agenta, sygnalizujące interakcję z agentem lub jego wiadomościami.
  • 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ń.

Zdarzenia dotyczące użytkowników

Wydarzenia użytkownika to powiadomienia z urządzenia użytkownika, które informują o stanie wiadomości lub zmianach subskrypcji (np. użytkownik zrezygnował z subskrypcji lub ponownie ją aktywował w Wiadomościach Google).

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

Użytkownik otrzymuje wiadomość od pracownika obsługi klienta

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 pracownika obsługi klienta

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 wpisuje odpowiedź.

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

Użytkownik wysyła SMS-a

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "text": "Hi",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID"
}

Użytkownik wysyła plik

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

Użytkownik klika sugerowaną odpowiedź

Gdy użytkownik kliknie sugerowaną odpowiedź, Twój agent otrzyma zdarzenie z danymi zwrotnymi i tekstem odpowiedzi.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventId": "EVENT_ID",
  "agentId": "AGENT_ID",
  "suggestionResponse": {
    "postbackData": "postback_1234",
    "text": "Hello there!"
  }
}

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ę wątku

To zdarzenie oznacza, że użytkownik zrezygnował z otrzymywania od Twojego agenta i reprezentowanej przez niego firmy mniej ważnych wiadomości, takich jak promocje. Użytkownicy wywołują to zdarzenie, rezygnując z 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 rezygnacja z subskrypcji

  • W menu czatu zawsze dostępna jest opcja Anuluj subskrypcję. W przypadku agentów promocyjnych i wielofunkcyjnych 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).

  • Kliknięcie opcji Anuluj subskrypcję powoduje 2 działania wykonywane 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 na podstawie dwuliterowego kodu 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
    Indie (IN), Niemcy (DE), Stany Zjednoczone (US), Wielka Brytania (GB) ZATRZYMAJ
    Hiszpania (ES), Meksyk (MX) BAJA
    Francja (FR) ZATRZYMAJ
    Brazylia (BR) parar

  • Po rezygnacji użytkownika z subskrypcji wątek pozostaje w jego skrzynce odbiorczej, chyba że zostanie zgłoszony jako spam. W takim przypadku zostanie przeniesiony do folderu Spam i zablokowane.

  • Aby wykrywać naruszenia zasad i reguł biznesowych, Google monitoruje wzorce wiadomości po rezygnacji użytkownika z subskrypcji.

Reguły biznesowe

  • Jako partner RBM zarządzający tą rozmową odpowiadasz za spełnienie prośby użytkownika o rezygnację z subskrypcji.
  • Jeśli nie możesz zrezygnować z subskrypcji w wątku wiadomości, musisz natychmiast wysłać wiadomość z potwierdzeniem zawierającą bezpośredni link do strony internetowej lub aplikacji, w której użytkownicy mogą zarządzać ustawieniami subskrypcji.
  • Po anulowaniu subskrypcji przez użytkownika wysyłanie mniej ważnych wiadomości jest zabronione.
  • Wiadomości o charakterze podstawowym są nadal dozwolone. Obejmują one:
    • uwierzytelnianie, np. hasła jednorazowe,
    • Powiadomienia dotyczące konkretnej usługi, o którą użytkownik poprosił i na którą wyraził zgodę
    • Potwierdzenie prośby użytkownika o rezygnację z 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 to wielokrotne użycie, musisz przestać wysyłać wiadomości marketingowe. Możesz jednak wysyłać aktualizacje dotyczące lotu, jeśli użytkownik wyraził zgodę na otrzymywanie aktualizacji dotyczących tego konkretnego lotu.

Powody anulowania subskrypcji

Gdy użytkownik zrezygnuje z subskrypcji Twojego agenta, może wybrać powód z tych opcji:

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

Powody anulowania subskrypcji są wyświetlane w przeglądzie Analytics, aby pomóc partnerom zrozumieć, dlaczego użytkownicy rezygnują z subskrypcji.

Ponowne subskrybowanie wątku przez użytkownika

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 ponowna subskrypcja

  • Opcja Subskrybuj, dostępna w menu czatu i w linku na czacie, umożliwia użytkownikom ponowne zasubskrybowanie rozmowy, z której zrezygnowali.

  • Kliknięcie Subskrybuj powoduje 2 działania wykonywane jednocześnie: Wiadomości Google wysyłają do agenta słowo kluczowe specyficzne dla danego kraju (np. „START”), a platforma RBM wysyła do webhooka zdarzenie SUBSCRIBE. Konkretne słowo kluczowe jest określane przez dwuliterowy 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
    Indie (IN), Niemcy (DE), Stany Zjednoczone (US), Wielka Brytania (GB) ROZPOCZNIJ
    Hiszpania (ES), Meksyk (MX) ALTA
    Francja (FR) Démarrer
    Brazylia (BR) começar

Reguły biznesowe

  • Jako partner RBM zarządzający 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 kanał wiadomości (np. w Twojej witrynie), Twoim obowiązkiem jako partnera RBM jest zaktualizowanie jego stanu i wznowienie wysyłania wiadomości.

Zdarzenia na platformie

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

Stan uruchamiania agenta został zmieniony

Platforma RBM wysyła AgentLaunchEvent za każdym razem, gdy zmieni się stan wdrożenia 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ź message.attributes.type ścieżkę wartości agent_launch_event.

Konfiguracja webhooka

Aby otrzymywać te powiadomienia, 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 i zdarzeń użytkowników).
  • Aby odróżnić zdarzenia użytkownika od zdarzeń stanu uruchomienia agenta, sprawdź ścieżkę message.attributes.type pod kątem wartości 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
UNLAUNCHED Nie uruchomiono Edytowanie jest dozwolone.
PENDING Oczekuje Prośba została wysłana do przewoźnika w celu sprawdzenia.
LAUNCHED Uruchomiony Wiadomości są dozwolone w danej sieci.
REJECTED Odrzucono w przypadku danego operatora Powód odrzucenia jest podany w komentarzu.
SUSPENDED Zawieszone u danego przewoźnika Powód zawieszenia jest podany w komentarzu.

Pole danych zawiera zakodowany w standardzie Base64 obiekt JSON 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"
    }

W tabeli poniżej znajdziesz stany uruchomienia agenta i działania, które je wywołują:

Stary stan uruchamiania Nowy stan uruchamiania Bodziec do zmian
PENDING LAUNCHED Oczekujący agent został zatwierdzony.
PENDING REJECTED Odrzucono agenta oczekującego.
LAUNCHED SUSPENDED Uruchomiony agent został zawieszony.
SUSPENDED LAUNCHED Zawieszony agent został ponownie aktywowany.
SUSPENDED TERMINATED Zawieszony agent został zakończony.
TERMINATED LAUNCHED Uruchomiono zakończonego agenta.

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

To zdarzenie oznacza, że czas życia wiadomości wygasł i została ona cofnięta. To dobry wyzwalacz dla strategii wiadomości zastępczych.

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

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

Wiadomość wygasła; nie udało się jej wycofać

To zdarzenie oznacza, że czas życia wiadomości wygasł, ale nie została ona skutecznie wycofana.

Pełne opcje formatowania i wartości znajdziesz w 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 zdarzenie DELIVERED w swoim webhooku.
  • Jeśli wiadomość nie została dostarczona, użyj interfejsu API do wycofania, aby wysłać żądanie wycofania.

Jeśli wiadomość jest pilna, np. zawiera jednorazowy kod 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