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. Gdy np. stan agenta zmieni się z PENDING na LAUNCHED po zatwierdzeniu przez przewoźnika, 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 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 Oczekuje na zatwierdzenie przez agenta.
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

Wiadomość wygasła i została cofnięta. To zdarzenie będzie dobrym wyzwalaczem 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 revoke, aby wysłać żądanie odwołania.

Jeśli wiadomość jest pilna, np. jest to 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 zduplikowanych wiadomości do użytkownika.

Wydarzenia generowane przez użytkowników

Podobnie jak w przypadku komunikatów użytkownika i sprawdzeń uprawnień, agent odbiera zdarzenia użytkownika w formacie JSON.

Aby zapoznać się z opcjami formatowania i wartości, zobacz 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 wiadomość tekstową

{
  "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 zawierające dane i tekst odpowiedzi.

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

Użytkownik klika sugerowaną akcję

Gdy użytkownik kliknie sugerowaną akcję, Twój agent otrzyma zdarzenie z danymi zwrotnymi dotyczącymi tej akcji.

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

Użytkownik rezygnuje z subskrypcji konwersacji

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 subskrypcji konwersacji z 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

  • Opcja Anuluj subskrypcję jest zawsze dostępna w menu czatu. 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).

  • Wybranie opcji Anuluj subskrypcję powoduje jednoczesne wykonanie dwóch czynności: usługa Google Messages wysyła do agenta słowo kluczowe specyficzne dla kraju (na przykład „STOP”), a platforma RBM wysyła zdarzenie UNSUBSCRIBE do Twojego webhooka.

    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ą 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 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 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 zapisuje się do konwersacji

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, np. 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 zarówno w menu czatu, jak i za pośrednictwem linku w czacie, umożliwia użytkownikom ponowną subskrypcję konwersacji, z której wcześniej zrezygnowali.

  • Wybranie opcji Subskrybuj powoduje jednoczesne wykonanie dwóch czynności: usługa Google Messages wysyła do agenta słowo kluczowe specyficzne dla kraju (na przykład „START”), a platforma RBM wysyła zdarzenie SUBSCRIBE do webhooka.

    Konkretne słowo kluczowe jest określane przez dwuliterowy kod kraju numeru telefonu użytkownika. W poniższej tabeli wymieniono słowa kluczowe dla każdego obsługiwanego kraju.

    Kraj (kod kraju) Subskrybuj słowo kluczowe
    Stany Zjednoczone (US), Indie (IN), Wielka Brytania (GB), Niemcy (DE) ROZPOCZNIJ
    Hiszpania (ES), Meksyk (MX) ALTA
    Francja (FR) Démarrer
    Brazylia (BR) começar

Reguły biznesowe

  • Jako partner RBM zarządzający tą konwersacją, Twoim obowiązkiem jest spełnienie prośby użytkownika o ponowną subskrypcję.
  • Ponowna subskrypcja dotyczy wszystkich typów wiadomości, także tych zbędnych, np. treści promocyjnych.
  • 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 generowane przez agenta

Twój agent wysyła zdarzenia, aby symulować interakcje międzyludzkie i zapewnić użytkownika, że agent odpowiada na jego wiadomości. Użytkownicy widzą zdarzenia jako powiadomienia w ramach rozmów.

Aby zapoznać się z opcjami formatowania i wartości, zobacz phones.agentEvents.

Agent wysyła zdarzenie READ.

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

Poniższy kod wysyła zdarzenie READ dla 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 jest fragmentem 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 jest fragmentem 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 Twój 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