Gli agenti RBM comunicano con gli utenti inviando e ricevendo messaggi. Per inviare messaggi agli utenti, l'agente invia richieste di messaggi all'API RCS Business Messaging. Una singola richiesta può includere testo, schede avanzate, file multimediali e PDF, nonché risposte suggerite e azioni suggerite.
In determinate situazioni, la piattaforma RBM restituisce errori per aiutarti a gestire il recapito dei messaggi:
- Se invii un messaggio a un utente il cui dispositivo non supporta RCS o non ha RCS abilitato, la piattaforma RBM restituisce un errore 404 NOT_FOUND. In questo caso, puoi tentare di contattare l'utente tramite i metodi di fallback definiti nella tua infrastruttura.
- Se invii un messaggio a un utente RCS su una rete in cui il tuo agente non è ancora stato lanciato o su una rete che non ha attivato il traffico RCS, la piattaforma RBM restituisce un errore 404 NOT_FOUND.
- Se invii un messaggio con funzionalità non supportate dal dispositivo di un utente, la piattaforma RBM restituisce l'errore 400 INVALID_ARGUMENT e non recapita il messaggio.
Nell'ambito della tua strategia di messaggistica multicanale, è consigliabile revocare i messaggi che non vengono recapitati dopo un periodo di tempo ragionevole e inviarli tramite un canale diverso. Per revocare automaticamente i messaggi a un'ora predefinita, imposta una scadenza del messaggio.
Il destinatario è offline
La piattaforma RBM accetta comunque un messaggio per la consegna se il destinatario è offline. Ricevi una risposta 200 OK e la piattaforma RBM conserva il messaggio e tenta di inviarlo nuovamente per 30 giorni. Non è necessario chiedere a RBM di inviare di nuovo il messaggio.
RBM elimina i messaggi non consegnati 30 giorni dopo l'invio.
A seconda del caso d'uso dell'agente, potresti voler revocare un messaggio non consegnato prima di questo timeout di 30 giorni. La revoca può impedire agli utenti offline di ricevere un messaggio obsoleto quando tornano online. Esistono diversi modi per revocare un messaggio:
- Invia una richiesta di revoca per attivarla.
- Imposta la scadenza di un messaggio per revocarlo automaticamente al momento opportuno.
Impostare la scadenza di un messaggio
Il messaggio dell'agente è urgente? Ad esempio, gli OTP sono validi solo per un breve periodo. Le offerte a tempo limitato scadono. Inoltre, i promemoria per gli appuntamenti non sono più pertinenti dopo la data dell'appuntamento. Per mantenere i messaggi tempestivi e pertinenti, imposta una data di scadenza. In questo modo, gli utenti offline non riceveranno contenuti obsoleti quando torneranno online. La scadenza è anche un buon segnale per richiamare la strategia di messaggistica di riserva, in modo che gli utenti ricevano le informazioni di cui hanno bisogno in tempo.
Per impostare una scadenza del messaggio, specifica uno dei seguenti campi nel messaggio dell'agente:
expireTime: l'ora esatta in UTC in cui il messaggio scade.ttl(durata TTL): la quantità di tempo prima della scadenza del messaggio.
Per le opzioni di formattazione e valore, vedi AgentMessage.
Una volta scaduto il messaggio, la piattaforma RBM smette di tentare di recapitarlo e viene revocato automaticamente. Tuttavia, in rari casi potrebbe non funzionare. Ad esempio, l'API potrebbe attivare la revoca mentre la piattaforma RBM era in procinto di inviare il messaggio. Per confermare se il messaggio scaduto è stato revocato correttamente, RBM invierà una notifica evento al tuo webhook.
Il valore massimo per ttl e expireTime è 15 giorni dopo l'invio del messaggio.
Sebbene non esista un valore minimo per ttl e expireTime, si consiglia di attendere almeno 10 secondi
dopo l'invio del messaggio per ridurre significativamente la possibilità di
ricevere la notifica sia di revoca che di consegna.
Imposta il tipo di traffico dei messaggi
L'API RBM include un campo messageTrafficType per classificare i messaggi.
Sebbene i
casi d'uso degli agenti
definiscono ancora il comportamento degli agenti e quali regole aziendali si applicano,
messageTrafficType consente una classificazione più dettagliata dei contenuti dei messaggi. In definitiva, ciò consentirà a un singolo agente di gestire
più casi d'uso. Al momento, non ci sono impatti sui casi d'uso o sulle regole aziendali esistenti degli agenti.
Questo campo è facoltativo, ma ti consigliamo di impostarlo ora per non ricevere un errore quando il campo diventerà obbligatorio.
Per impostare il tipo di traffico dei messaggi, assegna l'messageTrafficType appropriato
per ogni messaggio in base al suo contenuto. RBM supporta i seguenti tipi
di traffico.
| Tipo di traffico | Contenuto del messaggio | Caso d'uso dell'agente |
|---|---|---|
AUTHENTICATION |
Per i messaggi di autenticazione. | OTP |
TRANSACTION |
Per i messaggi relativi a servizi o prodotti esistenti di un utente. Ad esempio, conferme, ricevute di pagamento o dettagli della prenotazione. | Transazionale o multiuso |
PROMOTION |
Per messaggi promozionali come offerte, sconti, annunci o altri contenuti promozionali. | Promozionale o multiuso |
SERVICEREQUEST |
Per i messaggi relativi ai servizi che l'utente ha richiesto esplicitamente. | OTP, transazionale, promozionale o multiuso |
ACKNOWLEDGEMENT |
Per i messaggi utilizzati per confermare l'azione di un utente, in particolare una richiesta di annullamento dell'iscrizione. per confermare che la richiesta dell'utente è stata ricevuta ed è in fase di elaborazione. | OTP, transazionale, promozionale o multiuso |
Se non è impostato alcun tipo di traffico, il sistema assegna il tipo predefinito per il caso d'uso dell'agente.
| Caso d'uso dell'agente | Tipo di traffico predefinito |
|---|---|
| OTP | AUTHENTICATION |
| Transazionale | TRANSACTION |
| Promozionale | PROMOTION |
| Multi-uso | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Gli agenti multiuso non hanno un tipo di traffico predefinito. Devi impostare il tipo di traffico
in modo esplicito per ogni messaggio in base al suo contenuto. Se non sostituisci il valore
MESSAGE_TRAFFIC_TYPE_UNSPECIFIED, si verificherà un errore.
Limiti di dimensione dei messaggi
La dimensione massima dell'intera stringa AgentMessage è 250 kB. La parte di testo del messaggio ha un limite di 3072 caratteri.
La dimensione massima di un file che può essere inviato tramite RBM è 100 MB. Per saperne di più, consulta File multimediali e PDF.
Testo
I messaggi più semplici sono composti da testo. I messaggi sono più adatti per comunicare informazioni senza la necessità di immagini, interazioni complesse o risposte.
Esempio
Il seguente codice invia un messaggio di testo normale. Per le opzioni di formattazione e valore, vedi
phones.agentMessages.create.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!" }, "messageTrafficType": "PROMOTION" }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { messageText: 'Hello, world!', msisdn: '+12223334444', }; // Send a simple message to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444" ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a simple RBM text message message_text = messages.TextMessage('Hello, world!') # Send text message to the device messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
C#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
Contenuti del messaggio di base - Conversione di SMS
Gli operatori hanno introdotto modelli di fatturazione per supportare il passaggio dei messaggi SMS a RBM. Un messaggio RBM contenente fino a 160 caratteri UTF-8 è chiamato messaggio di base.
Quando crei una richiesta per inviare un messaggio di base, ricorda che i caratteri vengono conteggiati come 1 byte (UTF-8). Se invii un messaggio contenente caratteri speciali come emoji o un set di caratteri multibyte, ogni carattere viene conteggiato come 2-4 caratteri UTF-8 o più.
Inserisci del testo nella casella per verificarne la lunghezza:
Contenuti dei messaggi di base e anteprime dei link
I client RCS potrebbero implementare le anteprime dei link. Se un messaggio RBM di solo testo include un URL per un sito web con tag Open Graph, potrebbe essere visualizzata un'immagine di anteprima che dà l'impressione di contenuti più ricchi.
Tieni presente che il client RCS potrebbe consentire all'utente di disattivare le anteprime dei link.
Password monouso per la verifica dell'utente
Puoi utilizzare RBM per inviare password monouso (OTP) per la verifica automatica dell'utente con l'API SMS Retriever. Non esiste un'API dedicata alla lettura degli OTP ricevuti tramite RBM.
Come funziona per Android
Per le app per Android registrate con l'API SMS Retriever, l'API è in attesa di un messaggio RBM formattato correttamente. Questo messaggio deve contenere sia l'OTP sia un hash univoco che identifica la tua app.
Quando viene ricevuto un messaggio RBM con il formato corretto, l'API SMS Retriever lo elabora proprio come un OTP via SMS. Una volta che l'hash corrisponde a quello della tua app, l'OTP viene estratto e inoltrato alla tua app per la verifica automatica dell'utente.
- SMS RBM di esempio per la verifica dell'utente:
Your code is <OTP> <app hash>. - Esempio:
Your code is 123456 M8tue43FGT.
Per scoprire di più su SMS Retriever e sulle API correlate, consulta la documentazione di SMS Retriever. Per informazioni dettagliate sulla verifica automatica degli utenti nelle app registrate con l'API SMS Retriever, consulta questo diagramma di flusso.
Come funziona per iOS
Per iOS, la gestione OTP integrata del sistema rileva e suggerisce automaticamente le OTP RBM per il completamento automatico, proprio come le OTP SMS. Per la lettura dell'OTP da parte dell'app per iOS non è necessaria un'integrazione API specifica.
File multimediali e PDF
Quando invii un messaggio con un'immagine, un video, un audio o un file PDF, il tuo agente deve fornire un URL accessibile pubblicamente per i contenuti o caricare direttamente il file. Per i file multimediali, puoi anche specificare un'immagine in miniatura che consenta agli utenti di visualizzare l'anteprima dei contenuti prima di farci clic sopra. Per i file audio, viene utilizzato il widget audio predefinito come segnaposto.
La piattaforma RBM memorizza nella cache i file per 60 giorni e l'API restituisce un ID file che il tuo agente può includere nei messaggi agli utenti. Dopo 60 giorni, RBM rimuove i file dalla cache.
Quando specifichi i file per URL, la best practice prevede di impostare
contentMessage.forceRefresh su false. L'impostazione contentMessage.forceRefresh
su true impone a RBM di recuperare nuovi contenuti dall'URL specificato, anche se i contenuti dell'URL sono memorizzati nella cache, il che aumenta i tempi di consegna dei messaggi per gli utenti.
Consulta le best practice per i consigli e i limiti relativi alle dimensioni dei file.
Esempio di URL del file
Il seguente codice invia un'immagine. Per le opzioni di formattazione e valore, vedi
AgentContentMessage.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "contentInfo": { "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif', msisdn: '+12223334444', }; // Send an image/video to a device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage; import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // create media only message AgentContentMessage agentContentMessage = new AgentContentMessage(); agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl)); // attach content to message AgentMessage agentMessage = new AgentMessage(); agentMessage.setContentMessage(agentContentMessage); rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create media file attachment file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif') messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create content info with the file url ContentInfo contentInfo = new ContentInfo { FileUrl = fileUrl }; // Attach content info to a message AgentContentMessage agentContentMessage = new AgentContentMessage { ContentInfo = contentInfo, }; // Attach content to message AgentMessage agentMessage = new AgentMessage { ContentMessage = agentContentMessage }; rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
In alternativa, puoi caricare i contenuti multimediali prima di inviarli in un messaggio con
files.create.
Esempio di caricamento di file
Il seguente codice carica un file video e un file miniatura, quindi invia entrambi
i file in un messaggio. Per le opzioni di formattazione e valore, vedi
files.create
e AgentContentMessage.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: video/mp4" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"# Capture server-specified video file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: image/jpeg" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"# Capture server-specified image file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "uploadedRbmFile": { "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME", "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME" } } }'
Tipi di contenuti multimediali supportati
RBM supporta i seguenti tipi di contenuti multimediali. Per le miniature, sono supportati solo i formati image/jpeg, image/jpg, image/gif e image/png.
| Tipo di media | Tipo di documento | Estensione | Funziona con le schede interattive |
|---|---|---|---|
| application/ogg | Audio OGG | .ogx | No |
| application/pdf | No | ||
| audio/aac | Audio AAC | .aac | No |
| audio/mp3 | Audio MP3 | .mp3 | No |
| audio/mpeg | Audio MPEG | .mpeg | No |
| audio/mpg | MPG | .mp3 | No |
| audio/mp4 | MP4 audio | .mp4 | No |
| audio/mp4-latm | MP4-latm audio | .mp4 | No |
| audio/3gpp | Audio 3GPP | .3gp | No |
| image/jpeg | JPEG | .jpeg, .jpg | Sì |
| image/gif | GIF | .gif | Sì |
| image/png | PNG. | .png | Sì |
| video/h263 | Video H263 | .h263 | Sì |
| video/m4v | Video M4V | .m4v | Sì |
| video/mp4 | Video MP4 | .mp4 | Sì |
| video/mpeg4 | Video MPEG-4 | .mp4, .m4p | Sì |
| video/mpeg | Video MPEG | .mpeg | Sì |
| video/webm | Video WEBM | .webm | Sì |
Suggerimenti
L'agente invia suggerimenti (risposte suggerite e azioni suggerite) in elenchi di chip di suggerimenti (massimo 11 suggerimenti) o in schede avanzate (massimo 4 suggerimenti).
Ogni suggerimento può contenere un massimo di 25 caratteri.
Risposte suggerite
Le risposte suggerite guidano gli utenti nelle conversazioni fornendo risposte a cui l'agente sa come reagire.
Quando un utente tocca una risposta suggerita, il tuo agente riceve un evento che contiene il testo della risposta e i dati di postback. Il payload ha un massimo di 2048 caratteri.
Esempio
Il seguente codice invia un testo con due risposte suggerite. Per le opzioni di formattazione e
valore, consulta
SuggestedReply.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with suggestion chips to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggested replies for the message to send to the user cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1')) cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')) # Send a simple message with suggestion chips to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; // Send simple text message with suggestions to user rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Azioni suggerite
Le azioni suggerite guidano gli utenti nelle conversazioni sfruttando la funzionalità integrata dei loro dispositivi. L'agente può suggerire agli utenti di chiamare un numero, aprire una posizione su una mappa, condividere una posizione, aprire un URL o creare un evento di calendario.
Per ogni azione suggerita, puoi fornire facoltativamente un URL di riserva (massimo 2048 caratteri). Questo URL si aprirà in una nuova finestra del browser se il dispositivo dell'utente non supporta l'azione suggerita.
Quando un utente tocca un'azione suggerita, il tuo agente riceve un evento che contiene i dati di postback dell'azione.
Per le opzioni di formattazione e valore, vedi
SuggestedAction.
Componi un numero
L'azione Chiamata guida l'utente a comporre un numero di telefono specificato dall'agente.
I numeri di telefono possono includere solo cifre (0-9), segno più (+), asterisco (*)
e cancelletto (#). Il formato internazionale E.164 (ad esempio,
+14155555555) è supportato, ma non obbligatorio. ovvero sia +14155555555 che
1011 sono voci valide.
Esempio
Il seguente codice invia un'azione di chiamata. Per le opzioni di formattazione e valore, vedi
DialAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Call", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/contact/", "dialAction": { "phoneNumber": "+15556667777" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a dial suggested action let suggestions = [ { action: { text: 'Call', postbackData: 'postback_data_1234', dialAction: { phoneNumber: '+15556667777' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a dial suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a dial suggested action DialAction dialAction = new DialAction(); dialAction.setPhoneNumber("+15556667777"); // creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Call"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setDialAction(dialAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a dial suggested action suggestions = [ messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a dial an agent suggested action DialAction dialAction = new DialAction { PhoneNumber = "+15556667777" }; // Creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction { Text = "Call", PostbackData = "postback_data_1234", DialAction = dialAction }; // Attach action to a suggestion Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Visualizzare una posizione
L'azione Visualizza posizione mostra una posizione nell'app di mappe predefinita dell'utente. Puoi specificare la posizione in base alla latitudine e alla longitudine o con una query basata sulla posizione attuale dell'utente. Puoi anche impostare un'etichetta personalizzata per il segnaposto visualizzato nell'app di mappe.
Esempio
Il seguente codice invia un'azione di visualizzazione della posizione. Per le opzioni di formattazione e valore, vedi
ViewLocationAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "View map", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z", "viewLocationAction": { "latLong": { "latitude": "37.4220188", "longitude": "-122.0844786" }, "label": "Googleplex" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a view location suggested action let suggestions = [ { action: { text: 'View map', postbackData: 'postback_data_1234', viewLocationAction: { latLong: { latitude: 37.4220188, longitude: -122.0844786 }, label: 'Googleplex' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a view location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a view location suggested action ViewLocationAction viewLocationAction = new ViewLocationAction(); viewLocationAction.setQuery("Googleplex, Mountain View, CA"); // creating a suggested action based on a view location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("View map"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setViewLocationAction(viewLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a view location suggested action suggestions = [ messages.ViewLocationAction('View map', 'reply:postback_data_1234', query='Googleplex, Mountain View, CA') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // create an view location action ViewLocationAction viewLocationAction = new ViewLocationAction { Query = "Googleplex Mountain View, CA" }; // Attach the view location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ViewLocationAction = viewLocationAction, Text = "View map", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Condivisione della posizione
L'azione Condividi posizione consente all'utente di condividere una posizione con il tuo agente. L'utente può condividere la sua posizione attuale o una posizione selezionata manualmente dall'app Maps.
Esempio
Il seguente codice invia un'azione di condivisione della posizione. Per le opzioni di formattazione e valore, vedi
ShareLocationAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Share your location", "postbackData": "postback_data_1234", "shareLocationAction": {} } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a share location suggested action let suggestions = [ { action: { text: 'Share your location', postbackData: 'postback_data_1234', shareLocationAction: { } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a share location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a share location suggested action ShareLocationAction shareLocationAction = new ShareLocationAction(); // creating a suggested action based on a share location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Share location"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setShareLocationAction(shareLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a share location suggested action suggestions = [ messages.ShareLocationAction('Share location', 'reply:postback_data_1234') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a share location action ShareLocationAction shareLocationAction = new ShareLocationAction(); // Attach the share location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ShareLocationAction = shareLocationAction, Text = "Share location", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Aprire un URL
L'azione Apri URL ti consente di indirizzare gli utenti a una pagina web specificata dall'agente. Per impostazione predefinita, la pagina web si apre nel browser dell'utente. Se un utente ha configurato un'app predefinita per la pagina web, verrà aperta l'app. In questo caso, l'icona sul pulsante dell'azione suggerita sarà l'icona dell'app.
L'azione Apri URL supporta anche le webview integrate. Consulta Apri URL con webview.
Esempio
Il seguente codice invia un'azione di apertura dell'URL. Per le opzioni di formattazione e valore,
vedi
OpenUrlAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define an open URL suggested action let suggestions = [ { action: { text: 'Open Google', postbackData: 'postback_data_1234', openUrlAction: { url: 'https://www.google.com' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with an open URL suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating an open url suggested action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl("https://www.google.com"); // creating a suggested action based on an open url action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Open Google"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setOpenUrlAction(openUrlAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create an open url suggested action suggestions = [ messages.OpenUrlAction('Open Google', 'reply:postback_data_1234', 'https://www.google.com') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create an open url action OpenUrlAction openUrlAction = new OpenUrlAction { Url = "https://www.google.com" }; // Attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { OpenUrlAction = openUrlAction, Text = "Open Google", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Aprire un URL con WebView
L'azione Apri URL con visualizzazione web carica la pagina web specificata
all'interno dell'app di messaggistica con il motore di rendering del browser predefinito. In questo modo
l'utente può interagire con la pagina web senza uscire dalla conversazione
RBM. Se il dispositivo dell'utente non supporta le webview, la pagina web si apre
nel browser dell'utente. Per attivare le webview, consulta
OpenURLApplication.
Le webview hanno tre modalità di visualizzazione. Per le opzioni di formattazione e valore, vedi
WebviewViewMode.
- Completo:la pagina web occupa tutto lo schermo.
- Metà:la pagina web occupa metà dello schermo
- Verticale:la pagina web occupa tre quarti dello schermo
Esempio
Il seguente codice invia un'azione Apri URL con webview. Per le opzioni di formattazione e
valore, vedi OpenURLAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com", "application": "WEBVIEW", "webviewViewMode": "FULL", "description": "Accessibility description" } } } ] } }'
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { String URL = "https://www.google.com"; // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // Create suggestion to view webpage in full mode Suggestion viewInFullMode = getUrlActionInWebview(URL, "FULL") suggestions.add(viewInFullMode); // create suggestion to view webpage in half mode Suggestion viewInHalfMode = getUrlActionInWebview(URL, "HALF") suggestions.add(viewInHalfMode); // create suggestion to view webpage in tall mode Suggestion viewInTallMode = getUrlActionInWebview(URL, "TALL") suggestions.add(viewInTallMode); // Send simple text message with the suggested action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); } /** * Creates a suggested action to open URL in webview. * * @return a suggestion object for an open URL in webview action . */ private Suggestion getUrlActionInWebview(String url, String viewMode) { // create an open url action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl(url); openUrlAction.setApplication("WEBVIEW"); openUrlAction.setWebviewViewMode(viewMode); openUrlAction.setDescription("Accessibility description"); // attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setOpenUrlAction(openUrlAction); suggestedAction.setText('display_text'); suggestedAction.setPostbackData('postback_data_123'); // attach the action to a suggestion object Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); return suggestion; }
Creare un evento nel calendario
L'azione Crea evento nel calendario apre l'app di calendario dell'utente e inizia a creare un nuovo evento con le informazioni specificate.
È obbligatorio un titolo per l'evento nel calendario. Contiene un massimo di 100 caratteri. La descrizione dell'evento del calendario è facoltativa e può contenere al massimo 500 caratteri.
Esempio
Il seguente codice invia un'azione di creazione di un evento nel calendario. Per le opzioni di formattazione e
valore, consulta
CreateCalendarEventAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Save to calendar", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/calendar", "createCalendarEventAction": { "startTime": "2020-06-30T19:00:00Z", "endTime": "2020-06-30T20:00:00Z", "title": "My calendar event", "description": "Description of the calendar event" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a create calendar event suggested action let suggestions = [ { action: { text: 'Save to calendar', postbackData: 'postback_data_1234', createCalendarEventAction: { startTime: '2020-06-30T19:00:00Z', endTime: '2020-06-30T20:00:00Z', title: 'My calendar event', description: 'Description of the calendar event', }, } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a create calendar event suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a create calendar event suggested action CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction(); calendarEventAction.setTitle("My calendar event"); calendarEventAction.setDescription("Description of the calendar event"); calendarEventAction.setStartTime("2020-06-30T19:00:00Z"); calendarEventAction.setEndTime("2020-06-30T20:00:00Z"); // creating a suggested action based on a create calendar event action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Save to calendar"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setCreateCalendarEventAction(createCalendarEventAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a calendar event suggested action suggestions = [ messages.CreateCalendarEventAction('Save to Calendar', 'reply:postback_data_1234', '2020-06-30T19:00:00Z', '2020-06-30T20:00:00Z', 'My calendar event', 'Description of the calendar event') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a calendar event action CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction { Title = "My calendar event", Description = "Description of the calendar event", StartTime = "2020-06-30T19:00:00Z", EndTime = "2020-06-30T20:00:00Z" }; // Attach the calendar event action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { CreateCalendarEventAction = calendarEventAction, Text = "Save to calendar", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Elenco dei chip di suggerimento
L'agente invia elenchi di chip di suggerimenti con i messaggi per guidare le azioni successive degli utenti. L'elenco dei chip viene visualizzato solo quando il messaggio associato si trova in fondo alla conversazione. I messaggi successivi nella conversazione (inviati da un utente o dal tuo agente) sovrascrivono l'elenco di chip.
I chip nell'elenco sono risposte suggerite e azioni suggerite.
Gli elenchi di chip contengono un massimo di 11 chip di suggerimento e ogni etichetta del chip può contenere un massimo di 25 caratteri.
Per le opzioni di formattazione e valore, vedi
AgentContentMessage.
Schede informative
Quando devi inviare un blocco di informazioni, contenuti multimediali o suggerimenti correlati, devi inviare una scheda informativa. Le schede avanzate consentono all'agente di inviare più unità di informazioni in un unico messaggio.
Le schede avanzate possono contenere i seguenti elementi:
- Un'immagine o un video
- Testo titolo
- Testo descrizione
- Risposte suggerite e azioni suggerite (massimo 4)
Una scheda avanzata può contenere tutti gli elementi elencati, ma una scheda deve contenere almeno un'immagine, un video o un titolo per essere valida. Una scheda avanzata può contenere un massimo di quattro azioni suggerite e risposte suggerite.
L'agente può inviare più schede informative insieme in un carosello di schede informative.
La dimensione massima di un payload di scheda avanzata è 250 KB. Consulta le best practice per i consigli e i limiti relativi alle dimensioni dei file multimediali.
Puoi trovare le specifiche delle schede interattive in Schede interattive.
Altezza scheda
Le schede si espandono verticalmente per adattarsi ai contenuti. Le schede avanzate hanno un'altezza minima di 112 dp e un'altezza massima di 344 dp. Se i contenuti di una scheda non sono sufficientemente grandi da riempire l'altezza minima della scheda, la scheda si espande e riempie l'altezza aggiuntiva con uno spazio vuoto.
I contenuti multimediali nelle schede avanzate devono rientrare in una delle tre altezze:
- Breve: 112 dp
- Media: 168 dp
- Grandi: 264 dp
Se i contenuti multimediali non rientrano nelle dimensioni della scheda in base all'altezza selezionata, l'anteprima dei contenuti multimediali viene scelta tramite zoom e ritaglio.
Esempio
Il seguente codice invia una scheda informativa con un'immagine e risposte
suggerite. Per le opzioni di formattazione e valore, vedi
RichCard.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "richCard": { "standaloneCard": { "thumbnailImageAlignment": "RIGHT", "cardOrientation": "VERTICAL", "cardContent": { "title": "Hello, world!", "description": "RBM is awesome!", "media": { "height": "TALL", "contentInfo":{ "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } }, "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Suggested replies to be used in the card let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; // Image to be displayed by the card let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; // Definition of the card parameters let params = { messageText: 'Hello, world!', messageDescription: 'RBM is awesome!', msisdn: '+12223334444', suggestions: suggestions, imageUrl: imageUrl, height: 'TALL', }; // Send rich card to device rbmApiHelper.sendRichCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create a standalone rich card to send to the user StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard( "Hello, world!", "RBM is awesome!", imageUrl, MediaHeight.MEDIUM, CardOrientation.VERTICAL, suggestions ); rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Suggested replies to be used in the card suggestions = [ messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'), messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2') ] # Image to be displayed by the card image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; # Define rich card structure rich_card = messages.StandaloneCard('VERTICAL', 'Hello, world!', 'RBM is awesome!', suggestions, image_url, None, None, 'MEDIUM') # Append rich card and send to the user cluster = messages.MessageCluster().append_message(rich_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create rich card with suggestions StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard( "Hello, world!", "RBM is awesome", imageUrl, MediaHeight.TALL, CardOrientation.VERTICAL, suggestions ); // Send rich card to user rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
Caroselli di schede interattive
Quando devi presentare a un utente più opzioni tra cui scegliere, utilizza un carosello di schede avanzate. I caroselli uniscono più schede avanzate, consentendo agli utenti di confrontare gli elementi e reagire a ciascuno individualmente.
I caroselli possono contenere un minimo di due e un massimo di dieci schede avanzate. Le schede avanzate all'interno dei caroselli devono rispettare i requisiti generali delle schede avanzate per contenuti e altezza. Puoi trovare le specifiche del carosello in Schede avanzate.
La dimensione massima di un payload del carosello di schede avanzate è 250 KB. Consulta le best practice per i consigli e i limiti relativi alle dimensioni dei file multimediali.
Troncamento
Proprio come le schede avanzate, molti fattori (come la risoluzione dello schermo, la densità di pixel e le preferenze dell'utente) influiscono sull'aspetto delle schede per gli utenti finali. In un carosello, tuttavia, l'altezza delle prime schede definisce l'altezza di tutte le schede del carosello e l'altezza delle schede influisce sul troncamento di titolo, descrizione e suggerimenti.
Se un dispositivo non può visualizzare tutti gli elementi di una scheda a causa di vincoli di visualizzazione o dell'altezza della scheda, RBM tronca la scheda finché non può essere visualizzata sul dispositivo, utilizzando la seguente logica:
- Riduci la descrizione a una riga.
- Riduci il titolo a una riga.
- Ometti i suggerimenti che non rientrano nella scheda, a partire dalla fine dell'elenco definito.
- Ometti la descrizione.
- Ometti il titolo.
Per evitare il troncamento, mantieni titoli e descrizioni il più brevi possibile. Per i contenuti multimediali verticali, utilizza un titolo e una descrizione o un suggerimento. Per i media di medie dimensioni, utilizza fino a due suggerimenti. Per i contenuti multimediali brevi, utilizza fino a tre suggerimenti. Per inserire quattro suggerimenti, non includere contenuti multimediali nella scheda.
Mantieni le schede più o meno equivalenti in termini di dimensioni e lunghezza dei contenuti e, se necessario, carica le schede più grandi nel carosello per evitare il troncamento nelle schede successive.
Esempio
Il seguente codice invia un carosello di schede interattive. Per le opzioni di formattazione e valore,
vedi
RichCard.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_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 '{ "contentMessage": { "richCard": { "carouselCard": { "cardWidth": "MEDIUM", "cardContents": [ { "title": "Card #1", "description": "The description for card #1", "suggestions": [ { "reply": { "text": "Card #1", "postbackData": "card_1" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg", "forceRefresh": false } } }, { "title": "Card #2", "description": "The description for card #2", "suggestions": [ { "reply": { "text": "Card #2", "postbackData": "card_2" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg", "forceRefresh": false } } } ] } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Images for the carousel cards let card1Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg'; let card2Image = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg'; // Define the card contents for a carousel with two cards, each with one suggested reply let cardContents = [ { title: 'Card #1', description: 'The description for card #1', suggestions: [ { reply: { text: 'Card #1', postbackData: 'card_1', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card1Image, forceRefresh: false, }, }, }, { title: 'Card #2', description: 'The description for card #2', suggestions: [ { reply: { text: 'Card #2', postbackData: 'card_2', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card2Image, forceRefresh: false, }, }, }, ]; // Definition of carousel card let params = { msisdn: '+12223334444', cardContents: cardContents, }; // Send the device the carousel card defined above rbmApiHelper.sendCarouselCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.CardWidth; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); List cardContents = new ArrayList(); // Images for the carousel cards String card1Image = "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg"; // Create suggestions for first carousel card List card1Suggestions = new ArrayList(); card1Suggestions.add( new SuggestionHelper("Card #1", "card_1")); cardContents.add( new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, card1Suggestions) .getCardContent(MediaHeight.SHORT) ); // Images for the carousel cards String card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg"; // Create suggestions for second carousel card List card2Suggestions = new ArrayList(); card2Suggestions.add( new SuggestionHelper("Card #2", "card_2")); cardContents.add( new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, card2Suggestions) .getCardContent(MediaHeight.SHORT) ); // Send the carousel to the user rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Images for the carousel cards card_image_1 = 'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg'; card_image_2 = 'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg'; # Suggested replies to be used in the cards suggestions1 = [ messages.SuggestedReply('Card #1', 'reply:card_1') ] suggestions2 = [ messages.SuggestedReply('Card #2', 'reply:card_2') ] # Define the card contents for a carousel with two cards, # each with one suggested reply card_contents = [] card_contents.append(messages.CardContent('Card #1', 'The description for card #1', card_image_1, 'MEDIUM', suggestions1)) card_contents.append(messages.CardContent('Card #2', 'The description for card #2', card_image_2, 'MEDIUM', suggestions2)) # Send the device the carousel card defined above carousel_card = messages.CarouselCard('MEDIUM', card_contents) cluster = messages.MessageCluster().append_message(carousel_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Image references to be used in the carousel cards string card1Image = "https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg"; string card2Image = "https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg"; // Suggestion chip lists to be used in carousel cards List<Suggestion> suggestions1 = new List<Suggestion> { new SuggestionHelper("Card #1", "card_1").SuggestedReply() }; List<Suggestion> suggestions2 = new List<Suggestion> { new SuggestionHelper("Card #2", "card_2").SuggestedReply() }; // Create the card content for the carousel List<CardContent> cardContents = new List<CardContent> { // Add items as card content new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, suggestions1).GetCardContent(), new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, suggestions2).GetCardContent() }; // Send the carousel to the user rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);