Gli agenti RCS for Business 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 interattive, file multimediali e PDF, risposte suggerite e azioni suggerite.
In determinate situazioni, la piattaforma RCS for Business 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 attivato, la piattaforma RCS for Business restituisce un errore
404 NOT_FOUND. In questo caso, puoi provare a contattare l'utente tramite i metodi di riserva 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 RCS for Business restituisce un errore
404 NOT_FOUND. - Se invii un messaggio con funzionalità non supportate dal dispositivo di un utente,
la piattaforma RCS for Business restituisce l'errore
400 INVALID_ARGUMENTe 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 dei messaggi.
Il destinatario è offline
La piattaforma RCS for Business accetta comunque un messaggio per la consegna se il destinatario è offline. Ricevi una risposta 200 OK e la piattaforma RCS for Business trattiene il messaggio e tenta di inviarlo nuovamente per 30 giorni. Non è necessario chiedere a RCS for Business di inviare nuovamente il messaggio.
RCS for Business elimina tutti i messaggi non recapitati 30 giorni dopo l'invio.
A seconda del caso d'uso dell'agente, potresti voler revocare un messaggio non recapitato 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 attivare la revoca.
- Imposta una scadenza per revocare automaticamente il messaggio al momento opportuno.
Imposta la scadenza di un messaggio
Il messaggio dell'agente è urgente? Ad esempio, le OTP sono valide solo per un breve periodo. Le offerte a tempo limitato scadono. Inoltre, i promemoria degli appuntamenti non sono pertinenti dopo la data dell'appuntamento. Per mantenere i messaggi tempestivi e pertinenti, imposta una scadenza. In questo modo, gli utenti offline non riceveranno contenuti obsoleti quando torneranno online. La scadenza è anche un buon indicatore per attivare la tua 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 scade il messaggio.ttl(durata TTL): il periodo di tempo prima della scadenza del messaggio.
Per le opzioni di formattazione e valore, consulta AgentMessage.
Il valore massimo per ttl e expireTime è 15 giorni dopo l'invio del messaggio.
Il valore minimo per ttl e expireTime è sei secondi dopo l'invio del messaggio.
Consigli per l'impostazione della scadenza dei messaggi
Per i messaggi di autenticazione (OTP): imposta
ttlsu 15 secondi o più dopo l'invio del messaggio per ridurre in modo significativo la probabilità di race condition di consegna e revoca.Per i messaggi transazionali e promozionali: imposta scadenze più lunghe (almeno 60 secondi o minuti/ore a seconda del caso d'uso) perché i dispositivi richiedono più tempo per la scansione dei messaggi e il download o l'elaborazione di contenuti rich media e gli utenti potrebbero riscontrare brevi interruzioni della connettività (ad esempio, in un ascensore o in un tunnel).
Durata (TTL) di un messaggio
Quando imposti un TTL per un messaggio RCS for Business, specifichi per quanto tempo il messaggio deve essere considerato valido e recapitabile. Se il messaggio non viene recapitato correttamente al dispositivo dell'utente entro questo periodo di TTL, la piattaforma RCS for Business tenta automaticamente di revocarlo.
Quando avvii la revoca di un messaggio, richiedi alla piattaforma RCS for Business di interrompere i tentativi di recapito di quel messaggio specifico. Tuttavia, questa azione influisce solo sui futuri tentativi di consegna. Se il dispositivo di un utente ha già recuperato il messaggio, quest'ultimo è in fase di elaborazione e la piattaforma RCS for Business non può revocarlo dal dispositivo dell'utente.
Ecco cosa aspettarsi per quanto riguarda le notifiche:
Messaggio recapitato entro il TTL: se il dispositivo dell'utente si connette e riceve il messaggio prima della scadenza del TTL, ricevi una notifica
DELIVERED. Non verrà inviata alcuna notifica di revoca, poiché il messaggio è stato recapitato correttamente. Questo è lo scenario più comune e previsto.Messaggio non recapitato prima della scadenza del TTL: se il TTL scade prima che il messaggio raggiunga il dispositivo dell'utente (ad esempio, il dispositivo è offline), la piattaforma RCS for Business tenta di revocare il messaggio. Riceverai una notifica
TTL_EXPIRATION_REVOKEDche indica che il messaggio è stato rimosso correttamente dalla coda di invio. In questo caso, l'utente non riceverà il messaggio.
Suggerimenti per la gestione dei casi limite
Il nostro sistema elabora in parallelo la consegna dei messaggi RCS for Business e le scadenze del TTL. Per questo motivo, molto raramente, potresti riscontrare casi limite in cui le notifiche vengono inviate in momenti imprevisti. Ad esempio, potresti ricevere sia una notifica di consegna sia una notifica TTL oppure nessuna delle due.
Ecco i nostri consigli per la gestione delle notifiche dei messaggi RCS for Business:
Notifica
DELIVERED: se ricevi una notificaDELIVEREDper un messaggio, significa che il messaggio ha raggiunto l'utente. Puoi ignorare tranquillamente eventuali notifiche TTL successive per quel messaggio specifico.Notifica
TTL_EXPIRATION_REVOKED: se ricevi una notifica TTL con lo statoTTL_EXPIRATION_REVOKED, significa che il sistema RCS for Business interrompe i tentativi di consegna di quel messaggio specifico. Devi considerare questo messaggio come non consegnato e procedere con la tua strategia di riserva, se necessario.Notifica TTL con qualsiasi altro stato: se ricevi una notifica TTL con qualsiasi altro stato, significa che il tentativo di revoca non è stato conclusivo.
- Per i messaggi critici, come le password monouso (OTP), avvia il metodo di fallback.
- Per i messaggi non critici, decidi se avviare o meno il fallback.
- Nessuna notifica: in rari casi limite, il sistema potrebbe non riuscire a inviare una notifica TTL e il client potrebbe non riuscire a generare una notifica di consegna. Si tratta di un caso estremamente raro.
Imposta il tipo di traffico dei messaggi
L'API RBM include un campo messageTrafficType per classificare i messaggi.
Sebbene i casi d'uso dell'agente definiscano ancora il comportamento dell'agente e le regole aziendali applicabili, messageTrafficType consente una categorizzazione più dettagliata dei contenuti dei messaggi. In definitiva, questo consente a un singolo agente di gestire più casi d'uso. Al momento non ci sono impatti sui casi d'uso o sulle regole aziendali degli agenti esistenti.
Questo campo è facoltativo, ma ti consigliamo di impostarlo ora per evitare di ricevere un errore quando diventerà obbligatorio.
Per impostare il tipo di traffico dei messaggi, assegna l'attributo messageTrafficType appropriato a ogni messaggio in base ai relativi contenuti. La tabella seguente elenca i tipi di traffico supportati e i relativi casi d'uso previsti per l'agente. Questa mappatura è un'indicazione consigliata sull'utilizzo previsto, non una limitazione applicata dall'API al momento.
| Tipo di traffico | Contenuto messaggio | Caso d'uso dell'agente consigliato |
|---|---|---|
AUTHENTICATION |
Per i messaggi di autenticazione. | OTP |
TRANSACTION |
Per i messaggi relativi ai servizi o ai 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 richiesti esplicitamente dall'utente. | OTP, transazionale, promozionale o multiuso |
ACKNOWLEDGEMENT |
Per i messaggi utilizzati per confermare un'azione dell'utente, in particolare una richiesta di annullamento dell'iscrizione. In questo modo, l'utente riceve la conferma che la sua richiesta è stata ricevuta ed è in fase di elaborazione. | OTP, transazionale, promozionale o multiuso |
Se non viene 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 |
| Transazionali | TRANSACTION |
| Promozionale | PROMOTION |
| Multiuso | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Gli agenti multiuso non hanno un tipo di traffico predefinito. Devi impostare esplicitamente il tipo di traffico per ogni messaggio in base ai suoi contenuti. Se non sostituisci il valore MESSAGE_TRAFFIC_TYPE_UNSPECIFIED, il messaggio viene comunque accettato e recapitato senza una classificazione specifica del tipo di traffico.
Limiti di dimensione dei messaggi
La dimensione massima dell'intero AgentMessage convertito in stringa è di 250 kB. La parte di testo del messaggio ha un limite di 3072 caratteri.
Per evitare un consumo di dati imprevisto per gli utenti, la dimensione massima di un file che può essere inviato tramite RCS for Business è di 100 MiB e la dimensione totale combinata di tutti i contenuti multimediali e gli allegati PDF all'interno di un singolo messaggio RCS for Business non deve superare i 100 MiB. (1 MiB = 1.048.576 byte). Per saperne di più, consulta la sezione File multimediali e PDF.
Testo
I messaggi più semplici sono costituiti 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, consulta 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", );
Contenuto del messaggio di base - Conversione di SMS
Gli operatori hanno introdotto modelli di fatturazione per supportare il passaggio dai messaggi SMS a RCS for Business. Un messaggio RCS for Business 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 multi-byte, ogni carattere viene conteggiato come 2-4 caratteri UTF-8 o più.
Inserisci del testo nella casella per verificarne la lunghezza:
Contenuti dei messaggi e anteprime dei link
I client RCS possono implementare le anteprime dei link. Se un messaggio RCS for Business di solo testo include un URL di un sito web con tag openGraph, il client può generare un'anteprima (immagine, titolo e così via), offrendo un'esperienza più completa. Ad esempio, vedi un messaggio di base con un'anteprima dell'URL.
Tieni presente che il client RCS potrebbe consentire all'utente di disattivare le anteprime dei link.
Password monouso per la verifica degli utenti
Puoi utilizzare RCS for Business per inviare password monouso (OTP) per la verifica automatica degli utenti con l'API SMS Retriever. Non esiste un'API dedicata per la lettura delle OTP che arrivano tramite RCS for Business.
Come funziona per Android
Per le app per Android registrate con l'API SMS Retriever, l'API ascolta un messaggio RCS for Business formattato correttamente. Questo messaggio deve contenere sia la OTP sia un hash univoco che identifica la tua app.
Quando viene ricevuto un messaggio RCS for Business con il formato corretto, l'API SMS Retriever lo elabora esattamente come farebbe con un SMS OTP. Dopo che l'hash è stato abbinato alla tua app, l'OTP viene estratto e inoltrato alla tua app per la verifica automatica dell'utente.
- Esempio di messaggio RCS for Business 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 delle OTP integrata nel sistema rileva e suggerisce automaticamente le OTP di RCS for Business per la compilazione automatica, proprio come le OTP degli SMS. Non è richiesta alcuna integrazione API specifica per consentire all'app per iOS di leggere l'OTP.
File multimediali e PDF
Quando invii un messaggio con un'immagine, un video, un audio o un file PDF, l'agente deve fornire un URL accessibile pubblicamente per i contenuti o caricare direttamente il file.
La dimensione massima di un file che può essere inviato è di 100 MiB e la dimensione totale combinata di tutti gli allegati multimediali e PDF all'interno di un singolo messaggio non deve superare i 100 MiB.
Compressione e transcodifica dei contenuti multimediali
La piattaforma RCS for Business transcodifica e comprime automaticamente i file multimediali (come immagini e video) prima di inviarli per garantire che vengano caricati rapidamente e funzionino bene su reti e dispositivi diversi.
La compressione si basa sulla qualità dei contenuti multimediali di input anziché rigorosamente sui limiti di dimensione dei file. Ciò significa che un file può essere compresso anche se le sue dimensioni sono molto inferiori al limite massimo di 100 MiB. Gli standard di transcodifica cambiano costantemente, pertanto non esiste un limite fisso per le dimensioni dei file che determina quando la transcodifica viene ignorata. Sperimenta diversi formati, dimensioni e tassi di compressione dei contenuti multimediali per trovare l'equilibrio ottimale per i tuoi payload.
Specifiche delle miniature
Per i file multimediali, puoi anche specificare un'immagine in miniatura che consenta agli utenti di visualizzare l'anteprima dei contenuti prima di fare clic. Per i file audio, viene utilizzato il widget audio predefinito come segnaposto.
- La dimensione massima del file di una miniatura è 100 kB. Per un'esperienza utente ottimale, consigliamo di non superare i 50 kB.
- Le proporzioni della miniatura devono corrispondere a quelle del file originale.
Memorizzazione nella cache e gestione degli URL
La piattaforma RCS for Business memorizza i file nella cache per 60 giorni e l'API restituisce un ID file che l'agente può includere nei messaggi agli utenti. Dopo 60 giorni, RCS for Business rimuove i file dalla cache.
Quando specifichi i file tramite URL, è buona norma impostare contentMessage.forceRefresh su false. Se imposti contentMessage.forceRefresh su true, RCS for Business recupera i 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.
Esempio di URL del file
Il seguente codice invia un'immagine. Per le opzioni di formattazione e valore, consulta 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 file
Il seguente codice carica un file video e un file di miniatura, quindi invia entrambi i file in un messaggio. Per le opzioni di formattazione e valore, consulta 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
RCS for Business supporta i seguenti tipi di contenuti multimediali. Per le miniature, sono supportati solo image/jpeg, image/jpg, image/gif e image/png.
| Tipo multimediale | Tipo di documento | Estensione | Funziona con le schede interattive |
|---|---|---|---|
| application/ogg | Audio OGG | .ogx | No |
| application/pdf | Sì (solo per Google Messaggi in India) | ||
| audio/aac | Audio AAC | .aac | No |
| audio/mp3 | Audio MP3 | .mp3 | No |
| audio/mpeg | Audio MPEG | .mpeg | No |
| audio/mpg | Audio MPG | .mp3 | No |
| audio/mp4 | Audio MP4 | .mp4 | No |
| audio/mp4-latm | Audio MP4-latm | .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 suggerimento o in schede interattive.
Risposte suggerite
Le risposte suggerite guidano gli utenti attraverso le conversazioni fornendo risposte a cui l'agente sa come reagire.
Quando un utente tocca una risposta suggerita, l'agente riceve un evento contenente 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 attraverso le conversazioni sfruttando la funzionalità integrata dei loro dispositivi. L'agente può suggerire agli utenti di comporre un numero, aprire una posizione su una mappa, condividere una posizione, aprire un URL o creare un evento nel calendario.
Per ogni azione suggerita, puoi facoltativamente fornire un URL di riserva (massimo 2048 caratteri). Questo URL si apre in una nuova finestra del browser se il dispositivo dell'utente non supporta l'azione suggerita.
Quando un utente tocca un'azione suggerita, l'agente riceve un evento contenente i dati di postback dell'azione.
Per le opzioni di formattazione e valore, consulta SuggestedAction.
Visualizzazione dei suggerimenti
Esistono due modi per visualizzare i suggerimenti:
- Persistent: azioni o risposte suggerite che vengono visualizzate all'interno del fumetto del messaggio e rimangono fisse per tutta la conversazione.
- Temporanei: suggerimenti visualizzati all'esterno del fumetto del messaggio che scompaiono quando la conversazione continua.
Formati dei messaggi supportati
- Suggerimenti persistenti: funzionano con messaggi di testo autonomi e schede interattive.
- Suggerimenti temporanei: funzionano con messaggi di testo autonomi, messaggi multimediali e schede interattive.
Combina i suggerimenti
Puoi combinare suggerimenti persistenti e temporanei nello stesso messaggio o nella stessa scheda interattiva.
- Messaggi: i suggerimenti sono temporanei per impostazione predefinita. Per fare in modo che rimangano all'interno della bolla, devi configurarli come persistenti.
- Schede interattive: supportano fino a quattro suggerimenti persistenti per impostazione predefinita. Puoi quindi aggiungere suggerimenti temporanei come "elenco di chip" sotto la scheda.
Limiti dei suggerimenti
Un singolo messaggio supporta un massimo di 11 suggerimenti in totale. Tutti i suggerimenti persistenti che includi vengono conteggiati ai fini di questo limite totale. Ad esempio, se includi 4 suggerimenti persistenti, puoi aggiungere fino a 7 suggerimenti temporanei.
| Tipo di suggerimento | Limite | Dove vengono visualizzati |
|---|---|---|
| Permanente | Fino a 4 | All'interno del fumetto del messaggio |
| Temporaneo | Fino a 11 | Al di fuori del fumetto (come chip) |
Limite di caratteri
Ogni suggerimento può contenere un massimo di 25 caratteri.
Trasparenza URL nelle azioni suggerite
Per creare fiducia negli utenti, l'URL sottostante viene visualizzato come seconda riga di testo all'interno del pulsante di suggerimento per le azioni suggerite "Apri un URL". Questo comportamento coerente si applica a messaggi di testo autonomi, schede interattive e caroselli.
Client supportati per i suggerimenti permanenti
- Supportate: Google Messaggi (versione
20260225.00o successive). - Non supportate: versioni di Google Messaggi precedenti alla
20260225.00, iOS e Messaggi di Samsung.
Suggerimenti nelle notifiche di sistema
Quando un utente riceve un messaggio, Google Messaggi mostra il primo suggerimento idoneo direttamente nella notifica di sistema Android. Gli utenti possono toccare questo suggerimento per inviare una risposta o attivare un'azione senza dover aprire l'app.
Quando progetti i messaggi, tieni presente il seguente comportamento:
- L'ordine è importante: per ogni notifica viene mostrato un solo suggerimento. Per massimizzare il coinvolgimento, posiziona la risposta suggerita o l'azione suggerita con la priorità più alta all'inizio dell'elenco dei suggerimenti.
- Azioni escluse: l'azione Condividi posizione non viene mai mostrata nelle notifiche di sistema. Gli utenti devono aprire la conversazione per condividere la propria posizione.
Componi un numero
L'azione Chiama guida l'utente a comporre un numero di telefono specificato dall'agente.
I numeri di telefono possono includere solo cifre (0-9), il segno più (+), l'asterisco (*) e il cancelletto (#). Il formato internazionale E.164 (ad esempio +14155555555) è supportato, ma non obbligatorio. In altre parole, sia +14155555555 sia 1011 sono voci valide.
Esempio
Il seguente codice invia un'azione di composizione. Per le opzioni di formattazione e valore, consulta 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 );
Visualizza una sede
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 Maps.
Esempio
Il seguente codice invia un'azione di visualizzazione della posizione. Per le opzioni di formattazione e valore, consulta 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 );
Condividi la posizione
L'azione Condividi posizione consente all'utente di condividere una posizione con l'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, consulta 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 );
Apri 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. Puoi anche impostare la pagina web in modo che si apra in una visualizzazione web. Per maggiori dettagli, consulta Apri un URL con webview.
Solo in Google Messaggi
Visualizzazione dell'URL sottostante: per una maggiore trasparenza nella messaggistica A2P, Google Messaggi mostra l'indirizzo URL sottostante nelle azioni suggerite "Apri un URL". Questa modifica influisce sulle azioni suggerite nelle schede interattive standard e nei caroselli di schede interattive.
Visualizzazione dell'icona dell'app per i link web: se un utente ha configurato un'app predefinita per la pagina web, viene aperta l'app anziché il browser o la webview e il pulsante dei suggerimenti mostra l'icona dell'app. Affinché l'icona dell'app venga visualizzata in Google Messaggi, devi fornire l'URL diretto completo. Se utilizzi un URL abbreviato, viene visualizzata l'icona Apri URL predefinita.
Esempio
Il seguente codice invia un'azione di apertura dell'URL. Per le opzioni di formattazione e valore, consulta 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 );
Apri 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 RCS for Business. Se il dispositivo dell'utente non supporta le visualizzazioni web,
la pagina web si apre nel browser dell'utente. Per attivare le visualizzazioni web, consulta
OpenURLApplication.
Le visualizzazioni web hanno tre modalità di visualizzazione. Per le opzioni di formattazione e valore, consulta WebviewViewMode.
- Schermo intero: la pagina web occupa l'intero schermo.
- Metà: la pagina web occupa metà dello schermo
- Alta: 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, consulta 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.
Il titolo dell'evento nel calendario è obbligatorio. Ha un massimo di 100 caratteri. La descrizione dell'evento nel calendario è facoltativa e può contenere un massimo di 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 di chip di suggerimento
L'agente invia elenchi di chip di suggerimento con messaggi per guidare le azioni successive degli utenti. L'elenco di chip viene visualizzato solo quando il messaggio associato si trova in fondo alla conversazione. Tutti i messaggi successivi della conversazione (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 di chip può avere un massimo di 25 caratteri.
Per le opzioni di formattazione e valore, consulta AgentContentMessage.
Schede interattive
Le schede interattive combinano contenuti multimediali, testo e suggerimenti interattivi in un unico messaggio. Sono ideali per presentare informazioni correlate (ad esempio, un prodotto con la relativa immagine, il nome e il prezzo) e guidare gli utenti con un passaggio successivo chiaro, come un suggerimento "Visualizza dettagli".
Una scheda interattiva può contenere:
- Contenuti multimediali (immagine, GIF o video)
- Testo titolo
- Testo descrizione
- Risposte suggerite e azioni suggerite (massimo 4)
Ognuno di questi campi è facoltativo, ma almeno uno dei campi 1-3 deve essere incluso nella scheda interattiva.
È possibile inviare più schede insieme in un carosello a scorrimento orizzontale.
Tieni presente che il payload totale di una scheda interattiva è di 250 kB.
Per i dettagli tecnici completi, consulta la documentazione relativa alle schede interattive.
Altezza scheda
Le schede interattive si espandono verticalmente per adattarsi ai contenuti. Hanno un'altezza minima di 112 DP e un'altezza massima di 344 DP. Se i contenuti della scheda non sono abbastanza grandi da riempire l'altezza minima della scheda, questa si espande e riempie l'altezza aggiuntiva con uno spazio vuoto.
I contenuti multimediali nelle schede interattive devono avere una delle tre altezze seguenti:
- Short: 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 lo zoom e il ritaglio dei contenuti multimediali.
Esempio
Il seguente codice invia una scheda interattiva con un'immagine e risposte suggerite. Per le opzioni di formattazione e valore, consulta 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
I caroselli raggruppano più schede interattive, consentendo agli utenti di confrontare gli elementi e reagire a ciascuno singolarmente.
I caroselli possono contenere un minimo di due e un massimo di dieci schede interattive. Le schede interattive all'interno dei caroselli devono essere conformi ai requisiti generali delle schede interattive per i contenuti e l'altezza, come descritto nella documentazione relativa alle schede interattive. Per ulteriori informazioni sul layout e sulle specifiche del carosello, consulta la documentazione relativa al carosello.
Esempio
Il seguente codice invia un carosello di schede interattive. Per le opzioni di formattazione e valore, consulta 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/welcome-bot-sample-images/200.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/welcome-bot-sample-images/201.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/welcome-bot-sample-images/200.jpg'; let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.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/welcome-bot-sample-images/200.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/welcome-bot-sample-images/201.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/welcome-bot-sample-images/200.jpg'; card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.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/welcome-bot-sample-images/200.jpg"; string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.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);