Ricevere eventi

L'agente riceve eventi webhook dalla piattaforma RBM, che ti informano sia delle interazioni degli utenti sia degli aggiornamenti a livello di piattaforma.

Questi eventi sono classificati in base alla loro origine:

  • Eventi utente: notifiche inviate dal dispositivo di un utente al tuo agente, che segnalano un'interazione con il tuo agente.
  • Eventi della piattaforma: notifiche sulle modifiche dello stato di lancio dell'agente e sulle scadenze dei messaggi inviate dalla piattaforma RBM.

Per informazioni dettagliate sugli eventi di stato che l'agente invia al dispositivo dell'utente, vedi Inviare eventi.

Per informazioni dettagliate su come gestire i messaggi degli utenti, come testo, file, località, e altro, vedi Ricevere messaggi.

Eventi utente

Gli eventi utente sono notifiche provenienti dal dispositivo dell'utente che segnalano lo stato dei messaggi o le modifiche agli abbonamenti (ad es. l'utente ha annullato o riattivato l'abbonamento in Google Messaggi).

Per le opzioni di formattazione e valore complete, consulta il UserEvent riferimento.

L'utente riceve il messaggio dell'agente

Questo evento indica che un messaggio è stato recapitato correttamente al dispositivo dell'utente.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "DELIVERED",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

L'utente legge il messaggio dell'agente

Questo evento indica che un messaggio è stato aperto o confermato.

{
  "senderPhoneNumber": "PHONE_NUMBER",
  "eventType": "READ",
  "eventId": "EVENT_ID",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID"
}

L'utente inizia a scrivere

Questo evento indica che un utente sta scrivendo una risposta.

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

L'utente tocca un'azione suggerita

Quando un utente tocca un'azione suggerita, l'agente riceve un evento con i dati di postback dell'azione.

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

L'utente annulla l'iscrizione alla conversazione

Questo evento indica che l'utente ha annullato l'iscrizione alla ricezione di messaggi non essenziali, come le promozioni, dal tuo agente e dall'attività che rappresenta. Gli utenti attivano questo evento annullando l'iscrizione alla conversazione RBM in Google Messaggi.

Ecco un esempio del payload JSON:

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

Come funziona l'annullamento dell'iscrizione

  • L'opzione Annulla iscrizione è sempre disponibile nel menu della chat. Per gli agenti promozionali e multiuso, questa opzione viene visualizzata anche direttamente nella chat dopo un certo numero di messaggi da leggere (le regole specifiche variano in base al paese).

  • La selezione di Annulla iscrizione attiva due azioni simultanee: Google Messaggi invia una parola chiave specifica del paese (ad es. "STOP") al tuo agente e la piattaforma RBM invia un evento UNSUBSCRIBE al tuo webhook.

    La parola chiave è determinata dal codice paese di due lettere del numero di telefono dell'utente. La tabella seguente elenca le parole chiave per ogni paese supportato.

    Paese (codice paese) Parola chiave per l'annullamento dell'iscrizione
    Stati Uniti (US), India (IN), Regno Unito (GB), Germania (DE), Paesi Bassi (NL) STOP
    Spagna (ES), Messico (MX) BAJA
    Francia (FR) STOP
    Brasile (BR) parar

  • Dopo che l'utente ha annullato l'iscrizione, la conversazione rimane nella sua posta in arrivo, a meno che non venga segnalata come spam, nel qual caso viene spostata nella cartella Spam e bloccati.

  • Per identificare le violazioni delle norme e delle regole aziendali, Google monitora i pattern dei messaggi dopo che un utente ha annullato l'iscrizione.

Regole aziendali

  • In qualità di partner RBM che gestisce questa conversazione, è tua responsabilità rispettare la richiesta di annullamento dell'iscrizione dell'utente.
  • Se non riesci a eseguire l'annullamento dell'iscrizione all'interno del thread di messaggi, devi inviare immediatamente un messaggio di conferma con un link diretto al sito web o all'app in cui gli utenti possono gestire le proprie preferenze di abbonamento.
  • Dopo che l'utente ha annullato l'iscrizione, è vietato inviare messaggi non essenziali.
  • I messaggi essenziali sono ancora consentiti. Questi includono:
    • Autenticazioni, ad esempio password monouso (OTP)
    • Notifiche relative a un servizio specifico richiesto e autorizzato dall'utente
    • Conferma della richiesta di annullamento dell'iscrizione dell'utente, con informazioni per gestire ulteriormente le preferenze di comunicazione

Esempio

Se un utente annulla l'iscrizione a un agente di una compagnia aerea il cui caso d'uso è multiuso, devi interrompere l'invio di messaggi di marketing. Tuttavia, puoi inviare aggiornamenti sui voli se l'utente ha fornito il consenso esplicito a ricevere aggiornamenti per quel volo specifico.

Motivi dell'annullamento dell'iscrizione

Quando un utente annulla l'iscrizione al tuo agente, può selezionare un motivo tra le seguenti opzioni:

  • Spam
  • Non ho mai effettuato l'iscrizione
  • Troppi messaggi
  • Non mi interessa più
  • Altro

I motivi dell'annullamento dell'iscrizione vengono visualizzati nella panoramica di Analytics per aiutare i partner a capire perché gli utenti annullano l'iscrizione.

L'utente riattiva l'iscrizione alla conversazione

Questo evento indica che un utente vuole ricevere di nuovo messaggi dal tuo agente, inclusi contenuti non essenziali come le promozioni. Gli utenti possono attivare questo evento riattivando l'iscrizione a una conversazione a cui avevano annullato l'iscrizione in Google Messaggi.

Ecco un esempio del payload JSON:

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

Come funziona la riattivazione dell'iscrizione

  • L'opzione Iscriviti, disponibile sia dal menu della chat sia da un link nella chat, consente agli utenti di riattivare l'iscrizione a una conversazione a cui avevano annullato l'iscrizione.

  • La selezione di Iscriviti attiva due azioni simultanee: Google Messaggi invia una parola chiave specifica del paese (ad es. "START") al tuo agente e la piattaforma RBM invia un evento SUBSCRIBE al tuo webhook. La parola chiave specifica è determinata dal codice paese di due lettere del numero di telefono dell'utente. La tabella seguente elenca le parole chiave per ogni paese supportato.

    Paese (codice paese) Parola chiave per l'iscrizione
    Stati Uniti (US), India (IN), Regno Unito (GB), Germania (DE), Paesi Bassi (NL) START
    Spagna (ES), Messico (MX) ALTA
    Francia (FR) Démarrer
    Brasile (BR) começar

Regole aziendali

  • In qualità di partner RBM che gestisce questa conversazione, è tua responsabilità rispettare la richiesta di riattivazione dell'iscrizione dell'utente.
  • La riattivazione dell'iscrizione si applica a tutti i tipi di messaggi, inclusi i contenuti non essenziali come le promozioni.
  • Se un utente invia un messaggio alla tua attività dopo aver annullato l'iscrizione, questa azione può essere considerata una richiesta di riattivazione dell'iscrizione.
  • Se un utente riattiva l'iscrizione al di fuori del canale di messaggistica (ad es. sul tuo sito web), è tua responsabilità, in qualità di partner RBM, aggiornare il suo stato e riprendere a inviare messaggi di conseguenza.

Eventi della piattaforma

La piattaforma RBM invia eventi della piattaforma per notificare al tuo agente le modifiche allo stato di lancio dell'agente o le scadenze dei messaggi.

Lo stato di lancio dell'agente è cambiato

La piattaforma RBM invia un AgentLaunchEvent per ogni modifica dello stato di lancio dell'agente. Ad esempio, quando lo stato dell'agente passa da PENDING a LAUNCHED. L'evento viene recapitato come messaggio Pub/Sub. Per distinguerlo da altri eventi, controlla il percorso message.attributes.type per il valore agent_launch_event.

Configurazione webhook

Puoi utilizzare il webhook a livello di partner o di agente per ricevere queste notifiche.

Prerequisiti

  • Configura il webhook per la messaggistica RBM (questo è un requisito per ricevere messaggi ed eventi utente).
  • Per distinguere tra eventi utente ed eventi di stato di lancio dell'agente, controlla il percorso message.attributes.type per il valore agent_launch_event.

Struttura del payload dell'evento

Il AgentLaunchEvent viene recapitato come messaggio Pub/Sub. Ecco un esempio:

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

Il campo AgentLaunchEvent.LaunchState nel payload dell'evento indica il nuovo stato di lancio dell'agente. Ecco i valori possibili:

Valore Stato di lancio dell'agente Dettagli
PENDING In attesa La richiesta è stata inviata a un operatore per la revisione.
LAUNCHED Lanciato I messaggi sono consentiti su un determinato operatore.
REJECTED Rifiutato su un determinato operatore Il motivo del rifiuto è specificato nel commento.
SUSPENDED Sospeso su un determinato operatore Il motivo della sospensione è specificato nel commento.
UNLAUNCHED Non lanciato La modifica è consentita per gli agenti che non sono stati lanciati da tutti gli operatori.

Il campo dati contiene un oggetto JSON con codifica Base64 con i dettagli dello stato di lancio. Ecco un esempio del JSON decodificato:

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

Modifiche dello stato di lancio avviate dall'operatore

Queste sono le transizioni consentite che in genere vengono gestite dagli operatori durante la procedura di revisione e applicazione:

Stato di lancio precedente Nuovo stato di lancio Azione trigger
PENDING LAUNCHED Approvare una richiesta di lancio.
PENDING REJECTED Rifiutare una richiesta di lancio.
LAUNCHED SUSPENDED Sospendere per motivi di applicazione/amministrativi.
SUSPENDED LAUNCHED Ripristinare lo stato attivo di un agente.
SUSPENDED UNLAUNCHED Terminare un agente.

Modifiche dello stato di lancio avviate dal partner

Queste sono le transizioni consentite che in genere vengono gestite dai partner:

Stato di lancio precedente Nuovo stato di lancio Azione trigger
UNSPECIFIED PENDING Inviare per la revisione.
UNLAUNCHED PENDING Inviare per la revisione.
REJECTED PENDING Inviare di nuovo per la revisione.

Il messaggio è scaduto; la revoca è riuscita

Questo evento indica che il TTL (Time To Live) del messaggio è scaduto e che il messaggio è stato revocato correttamente. Questo è un buon trigger per la tua strategia di messaggistica di fallback.

Per le opzioni di formattazione e valore complete, consulta il ServerEvent riferimento.

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

Il messaggio è scaduto; la revoca non è riuscita

Questo evento indica che il TTL del messaggio è scaduto, ma la revoca non è riuscita.

Per le opzioni di formattazione e valore complete, consulta il ServerEvent riferimento.

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

La consegna dei messaggi non è garantita.

  • Se il messaggio è stato recapitato, riceverai un evento DELIVERED al tuo webhook.
  • Se il messaggio non è stato recapitato, utilizza l'API di revoca per inviare una richiesta di revoca.

Se il messaggio è sensibile al tempo, ad esempio una password monouso o un avviso di frode, è preferibile inviarlo tramite un canale alternativo come gli SMS, anche se ciò comporta la ricezione di messaggi duplicati da parte dell'utente.

Indietro
Invia eventi
Avanti
Controlli delle funzionalità