Inviare messaggi

Gli agenti RBM comunicano con gli utenti inviando e ricevendo messaggi. Per inviare messaggi agli utenti, il tuo agente invia richieste di messaggi all'API RCS Business Messaging. Una singola richiesta può includere testo, una scheda informativa, un'immagine o un video, nonché risposte suggerite e azioni suggerite.

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. In questo caso, puoi provare a raggiungere l'utente tramite i metodi di fallback definiti nella tua infrastruttura.

Se invii un messaggio a un utente RCS su una rete in cui l'agente non è ancora stato avviato o su una rete che non ha abilitato il traffico RCS, la piattaforma RBM restituisce un errore 403.

Se invii un messaggio con funzionalità non supportate dal dispositivo di un utente, la piattaforma RBM restituisce un errore e non recapita il messaggio.

Nota: nell'ambito della tua strategia di messaggistica multicanale, l'ideale è revocare i messaggi che non vengono recapitati dopo un periodo di tempo ragionevole e inviarli tramite un altro canale. Per revocare automaticamente i messaggi in un momento predefinito, imposta una scadenza dei messaggi.

La dimensione massima dell'intero AgentMessage sotto forma di stringa è 250 kB.

Invio a un utente offline

La piattaforma RBM accetta comunque un messaggio per la consegna se il destinatario è offline. Ricevi una risposta di tipo "200 OK" e la piattaforma RBM trattiene il messaggio e tenta di inviarlo nuovamente per 30 giorni. Non è necessario chiedere a RBM di inviare di nuovo il messaggio.

RBM elimina tutti i messaggi non recapitati 30 giorni dopo l'invio.

A seconda del caso d'uso dell'agente, potrebbe essere opportuno 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 una scadenza per i messaggi per revocarli automaticamente al momento opportuno.

Impostare la scadenza di un messaggio

Il messaggio dell'agente è sensibile al momento? Ad esempio, le OTP sono valide solo per un breve periodo. Le offerte a tempo limitato scadono. I promemoria degli appuntamenti non sono pertinenti dopo la data dell'appuntamento. Per garantire messaggi tempestivi e pertinenti, imposta una scadenza per i messaggi. In questo modo, gli utenti offline non riceveranno contenuti obsoleti quando tornano online. La scadenza è anche un buon spunto per richiamare la tua strategia di messaggistica di riserva in modo che gli utenti ricevano in tempo le informazioni di cui hanno bisogno.

Per impostare la scadenza di un messaggio, specifica uno dei seguenti campi nel messaggio dell'agente:

• expireTime: l'ora esatta in UTC della scadenza del messaggio.
• ttl(durata): la quantità di tempo prima della scadenza del messaggio.

Per le opzioni di formattazione e di valori, vedi AgentMessage.

Una volta scaduto il messaggio, la piattaforma RBM smette di tentare di recapitarlo e il messaggio viene revocato automaticamente. Tuttavia, potrebbe non riuscire in rare occasioni. Ad esempio, l'API potrebbe attivare la revoca mentre la piattaforma RBM era in fase di recapito del messaggio. Per confermare se il messaggio scaduto è stato revocato, RBM invierà una notifica evento al tuo webhook.

Testo

I messaggi più semplici sono composti da testo. I messaggi di testo sono più adatti a comunicare le informazioni senza bisogno di immagini, interazioni complesse o risposta.

Esempio

Il seguente codice invia un semplice SMS. Per le opzioni di formattazione e dei valori, 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!'
  }
}"

Node.js

// Reference to RBM API helper
const rbmApiHelper = require('@google/rcsbusinessmessaging');

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
};

// Send a simple message to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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!",
      "[phone]"
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

C#

using RCSBusinessMessaging;
…

// Create an instance of the RBM API helper
RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation,
                                             projectId);

rbmApiHelper.SendTextMessage(
    "Hello, world!",
    "[phone]",
);

Questo codice è un estratto da un agente di esempio RBM.

Contenuti di base di Messaggi - Conversione degli SMS

Gli operatori hanno introdotto modelli di fatturazione per supportare il trasferimento dei messaggi SMS al servizio 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 multi-byte, ogni carattere viene conteggiato come 2 caratteri UTF-8.

Inserisci del testo nella casella per verificarne la lunghezza:

Password monouso per la verifica utente

Puoi utilizzare RBM per inviare password monouso (OTP) per la verifica automatica degli utenti con l'API SMS Retriever. Per scoprire di più su SMS Retriever e sulle relative API, 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.

Durante la procedura di verifica, l'API SMS Retriever rimane in ascolto di un messaggio RBM. Questo messaggio deve contenere una OTP e un hash che identifichi l'app. Dopo che l'hash viene abbinato all'app, quest'ultima viene estratta e inoltrata all'app per la verifica automatica dell'utente.

Ecco un esempio di messaggio di testo RBM per la verifica dell'utente: Il tuo codice è <OTP> <hash app>.

Ad esempio, Your code is 123456 M8tue43FGT.

Suggerimento: ricorda di impostare una scadenza dei messaggi per le OTP e gli altri messaggi urgenti.

File multimediali e PDF

Quando invii un messaggio con un'immagine, un video o un file PDF, il tuo agente deve fornire un URL pubblicamente accessibile 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 fare clic.

La piattaforma RBM 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, RBM rimuove i file dalla cache.

Nota: quando specifichi i file tramite URL, è buona norma impostare contentMessage.forceRefresh su false. L'impostazione di contentMessage.forceRefresh su true obbliga RBM a 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 suggerimenti e limiti relativi alle dimensioni dei file.

Esempio di URL del file

Il seguente codice invia un'immagine. Per le opzioni di formattazione e valori, 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: '[phone]',
};

// Send an image/video to a device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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, "[phone]");
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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, "[phone]");

Questo codice è un estratto da un agente di esempio RBM.

In alternativa, puoi caricare 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 valori, 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 JSON


curl -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 JSON


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': {
    '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:

Tipo multimediale	Tipo di documento	Estensione	Funziona con le schede informative
applicazione/pdf	PDF	.pdf	No
image/jpeg	JPEG	.jpeg, .jpg	Sì
image/gif	GIF	.gif	Sì
image/png	PN	.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ì

Risposte suggerite

Le risposte suggerite guidano gli utenti nelle conversazioni fornendo risposte a cui l'agente sa come reagire. L'agente invia risposte suggerite negli elenchi di chip di suggerimento o nelle schede informative.

Quando un utente tocca una risposta suggerita, l'agente riceve un evento contenente il testo della risposta e i dati postback.

Le risposte suggerite possono contenere un massimo di 25 caratteri.

Esempio

Il seguente codice invia un testo con due risposte suggerite. Per le opzioni di formattazione e dei valori, 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with suggestion chips to the device
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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!",
    "[phone]",
   suggestions
);

Questo codice è un estratto da un agente di esempio RBM.

Azioni suggerite

Le azioni suggerite guidano gli utenti nelle conversazioni eliminando le funzionalità native 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 di calendario. L'agente invia azioni suggerite negli elenchi di chip di suggerimento o nelle schede informative.

Quando un utente tocca un'azione suggerita, l'agente riceve un evento contenente i dati postback dell'azione.

Le azioni suggerite possono includere un massimo di 25 caratteri.

Per le opzioni di formattazione e valori, consulta SuggestedAction.

Comporre un numero

L'azione Digitazione guida l'utente a comporre un numero di telefono specificato dall'agente. I numeri di telefono devono includere + iniziale, il codice paese e il prefisso, ma non devono includere separatori. Ad esempio, [phone].

Esempio

Il codice seguente invia un'azione di chiamata. Per le opzioni di formattazione e valori, 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': '[phone]'
          }
        }
      }
    ]
  }
}"

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: '[phone]'
         }
      }
   },
];

let params = {
   messageText: 'Hello, world!',
   msisdn: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a dial suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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("[phone]");

   // 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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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', '[phone]')
]

# 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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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 = "[phone]"
};

// 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!",
    "[phone]",
    suggestions
);

Questo codice è un estratto da un agente di esempio RBM.

Visualizzare una località

L'azione Visualizza posizione mostra una posizione nell'app predefinita delle mappe dell'utente. Puoi specificare la posizione tramite latitudine e longitudine oppure con una query basata sulla posizione attuale dell'utente. Puoi anche impostare un'etichetta personalizzata per il segnaposto visualizzato nell'app della mappa.

Esempio

Il seguente codice invia un'azione di visualizzazione della posizione. Per le opzioni di formattazione e dei valori, 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a view location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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!",
    "[phone]",
    suggestions
);

Questo codice è un estratto da un agente di esempio RBM.

Condivisione della posizione

L'azione Condividi posizione consente all'utente di inviare una posizione all'agente. La località specificata dall'utente non corrisponde necessariamente a quella dell'utente.

Esempio

Il seguente codice invia un'azione di condivisione della posizione. Per le opzioni di formattazione e dei valori, 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a share location suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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!",
    "[phone]",
    suggestions
);

Questo codice è un estratto da un agente di esempio RBM.

Apri un URL

L'azione Apri URL apre il browser web dell'utente all'URL specificato. Se un'app è registrata come gestore predefinito dell'URL, viene aperta l'app e l'icona dell'azione è quella dell'app.

Esempio

Il seguente codice invia un'azione di apertura URL. Per le opzioni di formattazione e valori, 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with an open URL suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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!",
    "[phone]",
    suggestions
);

Questo codice è un estratto da un agente di esempio RBM.

Crea un evento di calendario

L'azione Crea evento di calendario apre l'app di calendario dell'utente e inizia a creare un nuovo evento con le informazioni specificate.

Esempio

Il codice seguente invia un'azione di creazione di evento nel calendario. Per le opzioni di formattazione e dei valori, 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: '[phone]',
   suggestions: suggestions,
};

// Send a simple message with a create calendar event suggested action
rbmApiHelper.sendMessage(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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!",
      "[phone]",
      suggestions
   );
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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!",
    "[phone]",
    suggestions
);

Questo codice è un estratto da un agente di esempio RBM.

Elenco chip di suggerimento

L'agente invia elenchi di chip di suggerimenti con 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. Tutti i messaggi successivi nella 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ò contenere un massimo di 25 caratteri.

Per le opzioni di formattazione e valori, consulta AgentContentMessage.

Schede informative

Quando devi inviare un gruppo di informazioni, contenuti multimediali o suggerimenti correlati, ti consigliamo di inviare una scheda interattiva. Le schede interattive consentono all'agente di inviare più unità di informazioni in un singolo messaggio.

Le schede informative possono contenere i seguenti elementi:

• Immagine/video
• Testo titolo
• Testo descrizione
• Un elenco di risposte e azioni suggerite (massimo 4)

Una scheda informativa può contenere tutti gli elementi elencati, ma per essere valida una scheda deve contenere almeno un'immagine, un video o un titolo. Una scheda informativa può contenere un massimo di quattro azioni suggerite o risposte suggerite. Non può contenere una combinazione di azioni suggerite e risposte suggerite in un'unica scheda.

L'agente può inviare più schede interattive insieme in un carosello di schede informative.

Nota: la dimensione massima del payload di una scheda interattiva è di 250 kB. Consulta le best practice per consigli e limiti relativi alle dimensioni dei file multimediali.

Altezza scheda

Le schede si espandono verticalmente per adattarsi ai relativi contenuti. Le schede interattive hanno un'altezza minima di 112 DP e un'altezza massima di 344 DP. Se i contenuti di una scheda non sono abbastanza grandi da riempire l'altezza minima, la scheda si espande e riempie l'altezza aggiuntiva con uno spazio vuoto.

I contenuti multimediali nelle schede interattive devono rientrare in una delle tre seguenti altezze:

• Breve: 112 DP
• Medio: 168 DP
• Alta: 264 DP

Se le dimensioni dell'elemento multimediale non si adattano all'interno della scheda data l'altezza selezionata, l'anteprima viene scelta aumentando lo zoom e ritagliando l'elemento.

Esempio

Il seguente codice invia una scheda informativa con un'immagine e le risposte suggerite. Per le opzioni di formattazione e valori, 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: '[phone]',
   suggestions: suggestions,
   imageUrl: imageUrl,
   height: 'TALL',
};

// Send rich card to device
rbmApiHelper.sendRichCard(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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, "[phone]");
} catch(Exception e) {
   e.printStackTrace();
}

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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, "[phone]");

Questo codice è un estratto da un agente di esempio RBM.

Caroselli di schede interattive

Quando devi presentare a un utente più opzioni tra cui scegliere, utilizza un carosello di schede interattive. I caroselli mettono insieme diverse schede informative, consentendo agli utenti di confrontare gli elementi e di reagire a ogni singolo articolo.

I caroselli possono contenere da un minimo di due a un massimo di dieci schede informative. Le schede interattive all'interno dei caroselli devono essere conformi ai requisiti generali relativi a contenuti e altezza.

Nota: la dimensione massima del payload di un carosello di schede multifunzione è di 250 kB. Consulta le best practice per consigli e limiti relativi alle dimensioni dei file multimediali.

Troncamento

Proprio come per le schede informative, molti fattori (come la risoluzione dello schermo, la densità dei pixel e le preferenze dell'utente) influiscono sul modo in cui le schede vengono visualizzate dagli utenti finali. In un carosello, tuttavia, l'altezza delle prime schede definisce l'altezza di tutte le schede, mentre l'altezza della scheda influisce sul titolo, sulla descrizione e sul troncamento del suggerimento.

Se un dispositivo non può visualizzare tutti gli elementi di una scheda a causa di vincoli di visualizzazione o altezza della scheda, RBM tronca la scheda fino a quando non può essere visualizzata sul dispositivo, utilizzando la seguente logica:

1. Riduci la descrizione a una riga.
2. Riduci il titolo a una riga.
3. Ometti i suggerimenti che non rientrano nella scheda, a partire dalla fine dell'elenco definito.
4. Ometti la descrizione.
5. Ometti il titolo.

Per evitare che vengano troncati, mantieni i titoli e le descrizioni il più brevi possibile. Per i tall media, usa un titolo e una descrizione oppure un suggerimento. Per contenuti multimediali di medie dimensioni, utilizza fino a due suggerimenti. Per i contenuti multimediali brevi, utilizza fino a tre suggerimenti. Per includere quattro suggerimenti, non includere contenuti multimediali nella scheda.

Mantieni le schede all'incirca equivalenti in termini di dimensioni e lunghezza dei contenuti e, se necessario, carica in primo piano il carosello con schede più grandi per evitare che vengano troncate nelle schede successive.

Esempio

Il seguente codice invia un carosello di schede interattive. Per le opzioni di formattazione e valori, 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/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: '[phone]',
   cardContents: cardContents,
};

// Send the device the carousel card defined above
rbmApiHelper.sendCarouselCard(params, function(response) {
   console.log(response);
});

Questo codice è un estratto da un agente di esempio RBM.

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, "[phone]");
        } catch(Exception e) {
            e.printStackTrace();
        }

Questo codice è un estratto da un agente di esempio RBM.

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('[phone]')

Questo codice è un estratto da un agente di esempio RBM.

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);

Questo codice è un estratto da un agente di esempio RBM.