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 l'agente o i suoi messaggi.
  • Eventi della piattaforma: notifiche sulle modifiche allo 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.

Eventi utente

Gli eventi utente sono notifiche dal dispositivo dell'utente che segnalano lo stato del messaggio o le modifiche all'abbonamento (ad es. l'utente ha annullato l'iscrizione o si è riabbonato in Google Messaggi).

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

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 digitare

Questo evento indica che un utente sta digitando una risposta.

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

L'utente invia un messaggio

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

L'utente invia un file

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

L'utente tocca una risposta suggerita

Quando un utente tocca una risposta suggerita, l'agente riceve un evento con i dati di postback e il testo della risposta.

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

L'utente tocca un'azione suggerita

Quando un utente tocca un'azione suggerita, il tuo 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 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

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

  • Se selezioni Annulla iscrizione, vengono attivate due azioni simultanee: Google Messaggi invia una parola chiave specifica per paese (ad esempio "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) INTERROMPI
    Spagna (ES), Messico (MX) BAJA
    Francia (FR) INTERROMPI
    Brasile (BR) parar

  • Dopo l'annullamento dell'iscrizione, la conversazione rimane nella Posta in arrivo dell'utente a meno che non venga segnalata come spam, nel qual caso viene spostata nella cartella Spam e messaggi bloccati.

  • Per identificare le violazioni delle norme e delle regole aziendali, Google monitora i pattern dei messaggi dopo l'annullamento dell'iscrizione da parte di un utente.

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 l'annullamento dell'iscrizione da parte dell'utente, l'invio di messaggi non essenziali è vietato.
  • I messaggi essenziali sono comunque consentiti. Questi includono:
    • Autenticazioni, come le password uniche (OTP)
    • Notifiche relative a un servizio specifico richiesto e approvato 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 è multi-uso, 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 di annullamento dell'iscrizione vengono visualizzati nella panoramica di Analytics per aiutare i partner a capire perché gli utenti annullano l'iscrizione.

L'utente si abbona di nuovo 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 riabbonandosi a una conversazione da cui si erano precedentemente disiscritti 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'abbonamento

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

  • Se selezioni Iscriviti, vengono attivate due azioni simultanee: Google Messaggi invia una parola chiave specifica per paese (ad esempio "INIZIA") 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'abbonamento
    Stati Uniti (US), India (IN), Regno Unito (GB), Germania (DE) INIZIO
    Spagna (ES), Messico (MX) ALTA
    Francia (FR) Avvia
    Brasile (BR) começar

Regole aziendali

  • In qualità di partner RBM che gestisce questa conversazione, è tua responsabilità rispettare la richiesta di riabbonamento dell'utente.
  • La nuova 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, questo può essere considerato una richiesta di nuova iscrizione.
  • Se un utente si iscrive nuovamente al di fuori del canale di messaggistica (ad esempio 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 all'agente le modifiche allo stato di avvio dell'agente o alle 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 cambia da PENDING a LAUNCHED. L'evento viene inviato come messaggio Pub/Sub. Per distinguere questo evento dagli altri, 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 degli utenti).
  • Per distinguere tra eventi utente ed eventi di stato di avvio dell'agente, controlla il percorso message.attributes.type per il valore agent_launch_event.

Struttura del payload evento

AgentLaunchEvent viene inviato 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 avvio dell'agente. Ecco i valori possibili:

Valore Stato del lancio dell'agente Dettagli
UNLAUNCHED Non pubblicati La modifica è consentita.
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 per un determinato corriere Il motivo del rifiuto è specificato nel commento.
SUSPENDED Sospeso su un determinato operatore Il motivo della sospensione è specificato nel commento.

Il campo dati contiene un oggetto JSON con codifica base64 con i dettagli dello stato di lancio. Ecco un esempio di 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"
    }

La tabella seguente mostra gli stati di avvio dell'agente e le azioni che li attivano:

Stato di lancio precedente Nuovo stato del lancio Trigger per il cambiamento
PENDING LAUNCHED In attesa di approvazione dell'agente.
PENDING REJECTED Agente in attesa rifiutato.
LAUNCHED SUSPENDED Agente lanciato sospeso.
SUSPENDED LAUNCHED L'agente sospeso è stato riattivato.
SUSPENDED TERMINATED L'agente sospeso è stato terminato.
TERMINATED LAUNCHED Agente terminato avviato.

Il messaggio è scaduto; la revoca è riuscita

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

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

{
  "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 non è stato revocato correttamente.

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

{
  "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 consegnato, riceverai un evento DELIVERED nel webhook.
  • Se il messaggio non è stato recapitato, utilizza l'API di revoca per inviare una richiesta di revoca.

Se il messaggio è urgente, ad esempio un OTP o un avviso di frode, è meglio inviarlo tramite un canale alternativo come gli SMS, anche se ciò comporta l'invio di messaggi duplicati all'utente.

Indietro
Invia eventi
Avanti
Controlli delle funzionalità