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.
  • 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, consulta Invia eventi.

Per informazioni dettagliate su come gestire i messaggi degli utenti, come testo, file, posizioni e altro, consulta Ricevi messaggi.

Eventi utente

Gli eventi utente sono notifiche provenienti dal dispositivo dell'utente che segnalano lo stato dei messaggi o le modifiche all'abbonamento (ad es. l'utente ha annullato l'iscrizione o si è iscritto di nuovo in Google Messaggi).

Per le opzioni complete di formattazione e valori, consulta il riferimento 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 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 accessori, 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 di 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 non letti (le regole specifiche variano in base al paese).

  • Selezionando Annulla iscrizione, vengono attivate due azioni simultanee: Google Messaggi invia una parola chiave specifica per il paese (ad esempio "STOP") all'agente e la piattaforma RBM invia un evento UNSUBSCRIBE al 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) INTERROMPI
    Spagna (ES), Messico (MX) BAJA
    Francia (FR) STOP
    Brasile (BR) parar

  • Dopo l'annullamento dell'iscrizione da parte dell'utente, 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 messaggi bloccati.

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

Regole commerciali

  • In qualità di partner RBM che gestisce questa conversazione, è tua responsabilità soddisfare la richiesta di annullamento dell'iscrizione dell'utente.
  • Se non puoi annullare l'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 iscrizione.
  • Dopo l'annullamento dell'iscrizione da parte dell'utente, l'invio di messaggi accessori è vietato.
  • I messaggi essenziali sono comunque consentiti. Tra cui:
    • Autenticazioni, come le password monouso (OTP)
    • Notifiche relative a un servizio specifico richiesto e acconsentito dall'utente
    • Conferma della richiesta di annullamento dell'iscrizione dell'utente, con informazioni per gestire ulteriormente le sue 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:

  • Troppi messaggi
  • Non ho mai fatto la registrazione
  • Non mi interessa più
  • Sembra una frode
  • Altro

Per ridurre il bias di selezione, le prime quattro opzioni vengono visualizzate in un ordine casuale per ogni utente. Questo ordine rimane invariato nelle visite dell'utente e Altro rimane fisso in basso.

I motivi dell'annullamento dell'iscrizione vengono aggregati e mostrati nella panoramica di Analytics per aiutarti a capire perché gli utenti annullano l'iscrizione.

L'utente si iscrive nuovamente 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 iscrivendosi nuovamente a una conversazione da cui avevano annullato l'iscrizione in precedenza in Google Messaggi.

Ecco un esempio di payload JSON:

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

Come funziona il riabbonamento

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

  • Selezionando Iscriviti, vengono attivate due azioni simultanee: Google Messaggi invia una parola chiave specifica per il paese (ad esempio "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) INIZIO
    Spagna (ES), Messico (MX) ALTA
    Francia (FR) Démarrer
    Brasile (BR) começar

Regole commerciali

  • In qualità di partner RBM che gestisce questa conversazione, è tua responsabilità soddisfare la richiesta dell'utente di iscriversi di nuovo.
  • 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 riattivazione dell'iscrizione.
  • Se un utente si iscrive di nuovo al di fuori del canale di messaggistica (ad esempio sul tuo sito web), è tua responsabilità in qualità di partner RBM aggiornare lo stato e riprendere l'invio dei messaggi di conseguenza.

Eventi della piattaforma

La piattaforma RBM invia eventi della piattaforma per informare l'agente delle modifiche allo stato di lancio dell'agente o alle scadenze dei messaggi.

Lo stato di lancio dell'agente è cambiato

La piattaforma RBM invia un AgentLaunchEvent per ogni modifica allo 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 differenziarlo da altri eventi, controlla il percorso message.attributes.type per il valore agent_launch_event.

Configurazione del 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 dell'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 lancio dell'agente. Ecco i valori possibili:

Valore Stato del 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 da 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 di 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"
}

Modifiche dello stato di lancio avviate dall'operatore

Queste sono le transizioni consentite che vengono in genere gestite dai corrieri durante il processo di revisione e applicazione:

Stato di lancio precedente Nuovo stato del lancio Azione trigger
PENDING LAUNCHED Approvare una richiesta di lancio.
PENDING REJECTED Rifiutare una richiesta di lancio.
LAUNCHED SUSPENDED Sospensione per motivi di applicazione/amministrazione.
SUSPENDED LAUNCHED Ripristinare lo stato attivo di un agente.
SUSPENDED UNLAUNCHED Termina un agente.
REJECTED LAUNCHED Approvare una richiesta di lancio precedentemente rifiutata.

Modifiche dello stato di lancio avviate dal partner

Queste sono le transizioni consentite che vengono solitamente gestite dai partner:

Stato di lancio precedente Nuovo stato del lancio Azione trigger
UNSPECIFIED PENDING Invia per la revisione.
PENDING UNLAUNCHED Annullare una richiesta di lancio in attesa.
UNLAUNCHED PENDING Invia per la revisione.
REJECTED PENDING Invia di nuovo per la revisione.
SUSPENDED PENDING Invia di nuovo per la revisione.

Il messaggio è scaduto; revoca riuscita

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

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

Il messaggio è scaduto; revoca non riuscita

Questo evento indica che il TTL del messaggio è scaduto, ma non è stato revocato correttamente.

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

{
  "phoneNumber": "PHONE_NUMBER",
  "messageId": "MESSAGE_ID",
  "agentId": "AGENT_ID",
  "eventType": "TTL_EXPIRATION_REVOKE_FAILED",
  "eventId": "EVENT_ID",
  "sendTime": "TIMESTAMP"
}

La consegna dei messaggi non è garantita.

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

Se il messaggio è urgente, ad esempio una OTP o un avviso di attività fraudolenta, è 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à