Eventi

Gli eventi sono notifiche che l'agente può inviare e ricevere. Esistono tre tipi di eventi:

Eventi generati dal server

La piattaforma RBM invia eventi per notificare all'agente gli aggiornamenti a livello di server, ad esempio le scadenze dei messaggi.

Per le opzioni di formattazione e valore, vedi ServerEvent.

Lo stato del 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 dopo l'approvazione del corriere, ricevi un evento AgentLaunchEvent per indicare la modifica. Questi eventi vengono inviati per tutti gli agenti RBM, per tutte le modifiche dello stato di lancio dell'operatore.

Configurazione webhook

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

Prerequisiti

  • Configura il webhook per la messaggistica RBM (questo è un requisito per ricevere i messaggi degli utenti e gli eventi generati dagli utenti).
  • Per distinguere tra eventi generati dall'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 Agente sospeso terminato.
TERMINATED LAUNCHED Agente terminato avviato.

Il messaggio è scaduto; la revoca è riuscita

Il messaggio è scaduto ed è stato revocato. Questo evento sarebbe un buon trigger per la tua strategia di messaggistica di riserva.

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

Il messaggio è scaduto; la revoca non è riuscita

Il messaggio è scaduto, ma non è stato revocato.

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

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 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.

Eventi generati dagli utenti

Come per i messaggi utente e i controlli delle funzionalità, l'agente riceve gli eventi utente in formato JSON.

Per le opzioni di formattazione e valore, vedi UserEvent.

L'utente riceve il messaggio dell'agente

Questo evento indica che un messaggio è stato recapitato.

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

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

Se un utente non vuole ricevere messaggi non essenziali da un'attività, ad esempio promozioni, può annullare l'iscrizione alla conversazione RBM in Google Messaggi.

L'evento UNSUBSCRIBE indica che l'utente ha annullato l'iscrizione alla conversazione con il tuo agente e l'attività che rappresenta. Ecco un esempio del payload JSON:

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

Come funziona

  • 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 il 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 monouso (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:

  • Non sono iscritto
  • Troppi messaggi
  • Non mi interessa più
  • Spam
  • Altro

Al momento, i motivi di annullamento dell'iscrizione non vengono condivisi con partner o operatori.

L'utente si abbona di nuovo alla conversazione

Gli utenti possono riabbonarsi a una conversazione da cui si sono disiscritti in Google Messaggi.

L'evento SUBSCRIBE indica che un utente vuole ricevere messaggi dal tuo agente, inclusi contenuti non essenziali come le promozioni. Ecco un esempio del payload JSON:

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

Come funziona

  • Un'opzione Iscriviti, disponibile sia dal menu della chat sia da un link nella chat, consente agli utenti di riabbonarsi 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'iscrizione
    Stati Uniti (US), India (IN), Regno Unito (GB), Germania (DE) INIZIO
    Spagna (ES), Messico (MX) ALTA
    Francia (FR) Inizia
    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 generati dall'agente

L'agente invia eventi per simulare le interazioni umane e assicurare all'utente che l'agente sta interagendo con i suoi messaggi. Per gli utenti, gli eventi vengono visualizzati come notifiche all'interno delle conversazioni.

Per le opzioni di formattazione e valore, vedi phones.agentEvents.

L'agente invia un evento READ

Per gli utenti, questo evento viene visualizzato come conferma di lettura di un messaggio specifico. Consente all'utente di sapere che la piattaforma RBM ha recapitato il suo messaggio e che l'agente lo sta elaborando.

Il seguente codice invia un evento READ per un messaggio con un messageId corrispondente.

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);
 Questo codice è un estratto di un agente campione 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");
 Questo codice è un estratto di un agente campione 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)
 Questo codice è un estratto di un agente campione 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");
 Questo codice è un estratto di un agente campione RBM.

L'agente invia un evento IS_TYPING

Per gli utenti, questo evento viene visualizzato come indicatore di digitazione e li informa che l'agente sta componendo un messaggio. L'indicatore di digitazione scade dopo un breve periodo di tempo (circa 20 secondi) o quando il dispositivo dell'utente riceve un nuovo messaggio dal tuo agente. L'agente può inviare più eventi IS_TYPING per reimpostare il timer di scadenza dell'indicatore di digitazione.

Il seguente codice invia un evento 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!');
});
 Questo codice è un estratto di un agente campione 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");
 Questo codice è un estratto di un agente campione 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')
 Questo codice è un estratto di un agente campione 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");
 Questo codice è un estratto di un agente campione RBM.
Indietro
Ricevere messaggi
Avanti
Controlli delle funzionalità