Dopo aver effettuato la registrazione a Business Messages, puoi ricevere i messaggi per conto del tuo agente di test. Puoi ricevere messaggi per i brand che gestisci dopo creare, verificare e avviare gli agenti per tali brand.
Quando un cliente invia un messaggio a un agente che gestisci, Business Messages invia un payload JSON al tuo webhook che contiene vari ID, contenuti dei messaggi e informazioni sulla posizione.
Utilizza la pagina dei log della console per gli sviluppatori di Business Communications per eseguire il debug dei problemi di recapito dei messaggi.
Gestire i messaggi in arrivo
Il modo in cui il tuo agente gestisce e risponde ai messaggi degli utenti dipende molto dalla logica di business. In genere, i passaggi per rispondere a un messaggio utente sono coerenti.
Invia l'acknowledgement del messaggio
Per confermare un messaggio ricevuto dal webhook, restituisce una risposta HTTP valida ai messaggi inviati al webhook.
Se un messaggio non viene recapitato a causa di timeout di pubblicazione, connettività del webhook, reindirizzamento o problemi di autorizzazione, Google archivia e inoltra il messaggio, con diversi tentativi, per 7 giorni o fino a quando il webhook non lo riceve correttamente.
Verifica che il messaggio provenga da Google
Devi verificare che Google abbia inviato il messaggio prima di elaborarne i contenuti.
Per verificare se Google ha inviato un messaggio che hai ricevuto,
- Analizza l'intestazione
X-Goog-Signaturedel messaggio. Si tratta di una copia hash con codifica Base64 del payload del corpo del messaggio. Utilizzando il token client (presentato durante la configurazione del webhook) come chiave, crea un HMAC SHA512 dei byte del payload dei messaggi e codifica il risultato in base64.
Confronta l'hash
X-Goog-Signaturecon l'hash che hai creato.- Se gli hash corrispondono, hai verificato che Google ha inviato il messaggio.
- Se gli hash non corrispondono, controlla il processo di hashing su un messaggio noto. Se la procedura di hashing funziona correttamente e ricevi un messaggio che ritieni sia stato inviato in modo fraudolento, contattaci (devi accedere con un Account Google di Business Messages).
Consulta l'esempio di verifica del messaggio nei repository GitHub per i bot di eco in Java, Node.js e Python.
Identifica le impostazioni internazionali
Gli utenti comunicano da molte posizioni e in molte lingue. Business Messages
rappresenta le preferenze di lingua degli utenti con i campi resolvedLocale e
userDeviceLocale, che sono basati sulle impostazioni internazionali dei dispositivi.
Consulta Localizzazione e impostazioni internazionali.
Dove possibile, instrada i messaggi e scrivi le risposte in base alle preferenze di lingua degli utenti.
Indirizzare il messaggio in base al contesto
Il contesto del messaggio determina il tipo di informazioni che l'utente potrebbe cercare.
Ad esempio, se un utente invia un messaggio con un valore placeId, gli ha inviato una posizione specifica (identificata da placeId) e potrebbe porre domande specifiche sulla località. Analogamente, se un messaggio ha un valore nearPlaceId, che identifica una località vicino all'utente, è probabile che l'utente voglia conoscere informazioni specifiche sulla località, ma l'agente deve confermare la località con cui l'utente vuole chattare prima di iniziare la conversazione.
Con le informazioni di contesto del messaggio, indirizza il messaggio alla posizione più adatta per rispondere:
- Se il messaggio è in una nuova conversazione e si tratta di una domanda frequente, puoi rispondere con l'automazione.
- Se l'automazione non è in grado di gestire la domanda, indirizzala a un operatore.
- Se le impostazioni internazionali del messaggio non corrispondono a quelle predefinite dell'agente, instrada il messaggio a un operatore che possa supportare tale lingua.
- Se la domanda riguarda una località specifica, indirizzala a qualcuno che abbia informazioni sulla località in questione.
- Se il messaggio è in corso in una conversazione, indirizzalo all'operatore in tempo reale che partecipa alla conversazione.
Identificare il tipo di messaggio inviato dall'utente
Gli utenti possono inviare tre tipi di messaggi:
- Gli SMS sono risposte in formato libero.
- I messaggi immagine includono un URL firmato per un'immagine caricata dall'utente.
- I messaggi suggerimenti includono i dati postback e il testo dell'azione suggerita o della risposta suggerita che l'utente ha toccato.
Elabora i contenuti del messaggio
Se l'agente utilizza l'automazione, i contenuti del messaggio utente devono guidare la logica dell'agente e la risposta successiva nella conversazione.
Il modo più semplice per identificare l'intenzione dell'utente è utilizzare i dati postback provenienti da una risposta suggerita o un'azione suggerita. Indipendentemente dal testo associato al suggerimento, i dati postback sono leggibili dal computer.
Se un utente invia un SMS, il tuo agente potrebbe analizzare la risposta per le parole chiave supportate o utilizzare la comprensione del linguaggio naturale (come con l'integrazione di Dialogflow per elaborare il messaggio dell'utente e identificare un percorso da seguire.
Se l'agente non sa come rispondere al messaggio dell'utente, deve rispondere con uno stato di errore e provare a continuare la conversazione chiedendo all'utente ulteriori informazioni, chiedendo input in modo diverso o consegnando la conversazione a un operatore.
Rispondere all'utente
Dopo che l'agente identifica la risposta corretta, tramite l'automazione o un operatore, invia un messaggio e continua la conversazione con l'utente.
Quando scrivi una risposta, tieni conto delle impostazioni internazionali dell'utente. Puoi anche personalizzare le risposte recuperando i valori dall'oggetto userInfo in ciascun messaggio che ricevi.
Tipi di messaggi
Il codice seguente mostra in che modo l'agente riceve i messaggi.
Per informazioni sulla formattazione e sul valore, consulta
UserMessage.
Testo
Il modo più comune per rispondere agli utenti è con testo normale. Gli SMS hanno il seguente formato.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"message": {
"messageId": "MESSAGE_ID",
"name": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"text": "MESSAGE_TEXT",
"createTime": "MESSAGE_CREATE_TIME",
},
"dialogflowResponse": {
"autoResponded": "BOOLEAN",
"faqResponse": {
"userQuestion": "USER_QUESTION",
"answers": [{
"faqQuestion": "FAQ_QUESTION",
"faqAnswer": "FAQ_ANSWER",
"matchConfidenceLevel": "CONFIDENCE_LEVEL",
"matchConfidence": "CONFIDENCE_NUMERIC",
}],
},
},
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
Per le opzioni di formattazione e valore, consulta
Message.
Immagine
Oltre a inviare SMS, gli utenti possono inviare immagini all'agente come messaggi.
Business Messages archivia le immagini condivise, per 7 giorni, negli URL
firmati
e li include nel campo text del payload dei messaggi.
Se l'agente include l'automazione, assicurati che quest'ultima sappia come rispondere se un utente condivide un'immagine. Per gli agenti in tempo reale, assicurati che le immagini vengano trasmesse o che gli URL nei messaggi siano cliccabili.
...
"message": {
"text": "https://storage.googleapis.com/business-messages-us/936640919331/jzsu6cdguNGsBhmGJGuLs1DS?x-goog-algorithm\u003dGOOG4-RSA-SHA256\u0026x-goog-credential\u003duranium%40rcs-uranium.iam.gserviceaccount.com%2F20190826%2Fauto%2Fstorage%2Fgoog4_request\u0026x-goog-date\u003d20190826T201038Z\u0026x-goog-expires\u003d604800\u0026x-goog-signedheaders\u003dhost\u0026x-goog-signature\u003d89dbf7a74d21ab42ad25be071b37840a544a43d68e67270382054e1442d375b0b53d15496dbba12896b9d88a6501cac03b5cfca45d789da3e0cae75b050a89d8f54c1ffb27e467bd6ba1d146b7d42e30504c295c5c372a46e44728f554ba74b7b99bd9c6d3ed45f18588ed1b04522af1a47330cff73a711a6a8c65bb15e3289f480486f6695127e1014727cac949e284a7f74afd8220840159c589d48dddef1cc97b248dfc34802570448242eac4d7190b1b10a008404a330b4ff6f9656fa84e87f9a18ab59dc9b91e54ad11ffdc0ad1dc9d1ccc7855c0d263d93fce6f999971ec79879f922b582cf3bb196a1fedc3eefa226bb412e49af7dfd91cc072608e98"
}
...
Per le opzioni di formattazione e valore, consulta
Message.
Suggerimento
Le risposte suggerite e le azioni suggerite consentono agli utenti di rispondere o eseguire azioni con un tocco. Quando un utente tocca un suggerimento, l'agente riceve un payload con il testo del suggerimento e i dati postback.
I messaggi dei suggerimenti hanno il seguente formato.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"suggestionResponse": {
"message": "conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"postbackData": "POSTBACK_DATA",
"createTime": "RESPONSE_CREATE_TIME",
"text": "SUGGESTION_TEXT",
"suggestionType": "SUGGESTION_TYPE",
}
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
Per le opzioni di formattazione e valore, consulta
SuggestionResponse.
Richiesta di autenticazione
Il suggerimento per la richiesta di autenticazione consente agli utenti di accedere con un provider OAuth per fornire i dettagli sull'identità con l'agente o consentire all'agente di eseguire azioni per conto degli utenti. Vedi Autenticarsi con OAuth.
Se un utente accede correttamente con il provider OAuth specificato, l'agente riceve un payload con il codice di autorizzazione. Se un utente non riesce ad accedere, l'agente riceve un payload con i dettagli dell'errore.
I messaggi di richiesta di autenticazione hanno il seguente formato.
{
"agent": "brands/BRAND_ID/agents/AGENT_ID",
"conversationId": "CONVERSATION_ID",
"customAgentId": "CUSTOM_AGENT_ID",
"requestId": "REQUEST_ID",
"authenticationResponse": {
"code": "AUTHORIZATION_CODE",
"redirect_uri": "REDIRECT_URI",
"errorDetails": {
"error": "ERROR",
"errorDescription": "ERROR_DESCRIPTION",
},
}
"context": {
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
},
"sendTime": "SEND_TIME",
}
Per le opzioni di formattazione e valore, consulta
AuthenticationResponse.
Contesto del messaggio
Ogni messaggio contiene informazioni di contesto sull'origine del messaggio.
...
"context": {
"customContext": "CUSTOM_CONTEXT",
"entryPoint": "CONVERSATION_ENTRYPOINT",
"placeId": "LOCATION_PLACE_ID",
"nearPlaceId": "NEARBY_LOCATION_PLACE_ID",
"deflectedPhoneNumber": "DEFLECTED_PHONE_NUMBER",
"resolvedLocale": "MATCH_OF_USER_AND_AGENT_LOCALES",
"userInfo": {
"displayName": "USER_NAME",
"userDeviceLocale": "USER_LOCALE",
},
"widget": {
"url": "WEBSITE_URL",
"widgetContext": "WIDGET_CONTEXT",
},
},
...
| Campo | Descrizione |
|---|---|
customContext |
Dati di contesto specificati dal partner. |
entryPoint |
La piattaforma di messaggistica dalla quale l'utente ha iniziato la conversazione, come definito da EntryPoint. |
placeId |
Un identificatore univoco contenuto nel database di Google Places per la località a cui l'utente ha inviato un messaggio. Viene visualizzato solo nei messaggi provenienti da punti di contatto specifici per la località. |
nearPlaceId |
Un identificatore univoco recuperato dal database di Google Places per la prima
posizione di un pacchetto locale. Conferma le località con cui gli utenti vogliono chattare quando ricevi i valori nearPlaceId. |
deflectedPhoneNumber |
Il numero di telefono che Business Messages ha deviato dall'utente per chiamare quando è iniziata la conversazione. |
resolvedLocale |
La migliore corrispondenza calcolata della lingua dell'utente (segnalata in Il valore della lingua è un tag di lingua IETF BCP 47 con formato corretto. |
userInfo.displayName |
Il nome dell'utente che ha inviato il messaggio. Se l'utente disattiva la condivisione dell'identità, il campo è vuoto. |
userInfo.userDeviceLocale |
Impostazioni internazionali dell'utente, segnalate dal suo dispositivo come tag lingua IETF BCP 47 ben formulato. |
widget.url |
L'URL del sito web su cui è stata lanciata la piattaforma di conversazione. |
widget.widgetContext |
Il valore dell'attributo data-bm-widget-context del widget utilizzato per avviare la conversazione. |
Cronologia conversazione
Google non fornisce le cronologie delle conversazioni. Mantieni le tue conversazioni storiche, in modo conforme alle tue norme sulla privacy e alle tue best practice, in modo da poter inviare risposte informate ai messaggi futuri degli utenti.