Wydarzenia

Zdarzenia to powiadomienia, które Twój agent może wysyłać i odbierać. Istnieją 3 rodzaje zdarzeń:

Zdarzenia generowane przez serwer

Platforma RBM wysyła zdarzenia, aby powiadamiać agenta o aktualizacjach na poziomie serwera, takich jak wygasanie wiadomości.

Opcje formatowania i wartości znajdziesz w sekcji ServerEvent.

Zmiana stanu uruchamiania agenta

Platforma RBM wysyła AgentLaunchEvent za każdym razem, gdy zmieni się stan wdrożenia agenta. Jeśli np. stan agenta zmieni się z PENDING na LAUNCHED po zatwierdzeniu przez operatora, otrzymasz zdarzenie AgentLaunchEvent informujące o tej zmianie. Te zdarzenia są wysyłane do wszystkich agentów RBM w przypadku wszystkich zmian stanu wdrożenia operatora.

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 od użytkowników i zdarzeń wygenerowanych przez użytkowników).
  • Aby odróżnić zdarzenia wygenerowane przez 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 przypadku danego operatora.
REJECTED Odrzucono w przypadku danego operatora Przyczyna odrzucenia jest podana w komentarzu.
SUSPENDED Zawieszone u danego operatora 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 Oczekuje na zatwierdzenie agenta.
PENDING REJECTED Odrzucono oczekującego agenta.
LAUNCHED SUSPENDED Uruchomiony agent został zawieszony.
SUSPENDED LAUNCHED Zawieszony agent został ponownie aktywowany.
SUSPENDED TERMINATED Zawieszony agent został zamknięty.
TERMINATED LAUNCHED Uruchomiono zakończonego agenta.

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

Wiadomość wygasła i została cofnięta. To zdarzenie będzie dobrym wyzwalaczem dla strategii wiadomości rezerwowych.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

Wiadomość wygasła; nie udało się cofnąć dostępu

Wiadomość wygasła, ale nie została unieważniona.

{
  "phoneNumber": [phone number of recipient that the original message was intended for] ,
  "messageId": [RCS message ID of the message],
  "agentId": [bot ID],
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": [unique ID generated by the RBM platform],
  "sendTime": [time at which the server sent this event]
}

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ć prośbę o wycofanie.

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.

Zdarzenia wygenerowane przez użytkowników

Podobnie jak w przypadku wiadomości użytkowników i sprawdzania możliwości agent otrzymuje zdarzenia użytkownika w formacie JSON.

Opcje formatowania i wartości znajdziesz w sekcji UserEvent.

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

To zdarzenie oznacza, że wiadomość została dostarczona.

{
  "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 wskazuje, że użytkownik pisze.

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

Jeśli użytkownik nie chce otrzymywać od firmy mniej ważnych wiadomości, takich jak promocje, może zrezygnować z subskrypcji rozmowy RBM w Wiadomościach Google.

Zdarzenie UNSUBSCRIBE oznacza, że użytkownik zrezygnował z rozmowy z Twoim agentem i firmą, którą reprezentuje. Oto przykład ładunku JSON:

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

Jak to działa

  • 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 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) Anulowanie subskrypcji słowa kluczowego
    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ą musisz spełnić prośbę 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 witryny 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 niezbędnym 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 anuluje subskrypcję Twojego agenta, może wybrać powód z tych opcji:

  • Nie mam konta
  • Za dużo wiadomości
  • Już nie interesuje mnie ten kanał
  • Spam
  • Inne

Obecnie powody rezygnacji z subskrypcji nie są udostępniane partnerom ani operatorom.

Użytkownik ponownie subskrybuje wątek

Użytkownicy mogą ponownie zasubskrybować rozmowę, z której wcześniej zrezygnowali, w Wiadomościach Google.

Zdarzenie SUBSCRIBE oznacza, że użytkownik chce otrzymywać wiadomości od Twojego agenta, w tym treści nieistotne, takie jak promocje. Oto przykład ładunku JSON:

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

Jak to działa

  • Opcja Subskrybuj, dostępna w menu czatu i w linku w 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) Subskrypcja słowa kluczowego
    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 wygenerowane przez agenta

Twój agent wysyła zdarzenia, aby symulować interakcje z użytkownikiem i zapewnić go, że reaguje na jego wiadomości. Użytkownicy widzą zdarzenia jako powiadomienia w ramach rozmów.

Opcje formatowania i wartości znajdziesz w sekcji phones.agentEvents.

Agent wysyła zdarzenie READ.

Dla użytkowników to zdarzenie jest potwierdzeniem odczytania konkretnej wiadomości. Informuje użytkownika, że platforma RBM dostarczyła jego wiadomość i agent ją przetwarza.

Poniższy kod wysyła zdarzenie READ w przypadku wiadomości z pasującym messageId.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'READ',
  'messageId': 'MESSAGE_ID'
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage('+12223334444', messageId);
 Ten kod to fragment przykładowego agenta RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that messageId has been read
rbmApiHelper.sendReadMessage(messageId, "+12223334444");
 Ten kod to fragment przykładowego agenta RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that message_id was read
rbm_service.send_read_event('+12223334444', message_id)
 Ten kod to fragment przykładowego agenta RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that messageId has been read
rbmApiHelper.SendReadMessage(messageId, "+12223334444");
 Ten kod to fragment przykładowego agenta RBM.

Agent wysyła zdarzenie IS_TYPING

Użytkownicy widzą to zdarzenie jako wskaźnik pisania, który informuje ich, że agent pisze wiadomość. Wskaźnik pisania wygasa po krótkim czasie (około 20 sekund) lub gdy urządzenie użytkownika otrzyma nową wiadomość od Twojego agenta. Agent może wysłać wiele zdarzeń IS_TYPING, aby zresetować czas wygaśnięcia wskaźnika pisania.

Poniższy kod wysyła zdarzenie IS_TYPING.

cURL

curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentEvents?eventId=EVENT_ID&agentId=AGENT_ID" \
-H "Content-Type: application/json" \
-H "User-Agent: curl/rcs-business-messaging" \
-H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \
-d "{
  'eventType': 'IS_TYPING',
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage('+12223334444', function() {
    console.log('Typing event sent!');
});
 Ten kod to fragment przykładowego agenta RBM.

Java

import com.google.rbm.RbmApiHelper;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper();

// Send the device an event to indicate that the agent is typing
rbmApiHelper.sendIsTypingMessage("+12223334444");
 Ten kod to fragment przykładowego agenta RBM.

Python

# Reference to RBM Python client helper and messaging object structure
from rcs_business_messaging import rbm_service

# Send the device an event to indicate that the agent is typing
rbm_service.send_is_typing_event('+12223334444')
 Ten kod to fragment przykładowego agenta RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                                 projectId);

// Send the device an event to indicate that the agent is typing
rbmApiHelper.SendIsTypingMessage(messageId, "+12223334444");
 Ten kod to fragment przykładowego agenta RBM.
Wstecz
Odbieranie wiadomości
Dalej
Testy możliwości