Les agents RCS for Business communiquent avec les utilisateurs en envoyant et en recevant des messages. Pour envoyer des messages aux utilisateurs, votre agent envoie des requêtes à l'API de messagerie RCS Business. Une seule requête peut inclure du texte , des cartes enrichies , des fichiers multimédias et PDF , des suggestions de réponses et des suggestions d'actions .
La plateforme RCS for Business renvoie des erreurs dans certaines situations pour vous aider à gérer la distribution des messages :
- Si vous envoyez un message à un utilisateur dont l'appareil ne prend pas en charge RCS ou sur lequel RCS n'est pas activé, la plateforme RCS for Business renvoie une erreur 404 NOT_FOUND. Dans ce cas, vous pouvez tenter de contacter l'utilisateur via les méthodes de secours définies dans votre infrastructure.
- Si vous envoyez un message à un utilisateur RCS sur un réseau où votre agent n'est pas encore lancé, ou sur un réseau qui n'a pas activé le trafic RCS, la plateforme RCS for Business renvoie une erreur 404 NOT_FOUND.
- Si vous envoyez un message comportant des fonctionnalités non prises en charge par l'appareil de l'utilisateur, la plateforme RCS for Business renvoie une erreur 400 INVALID_ARGUMENT et ne transmet pas votre message.
Dans le cadre de votre stratégie de messagerie multicanal, il est préférable de révoquer les messages non distribués après un délai raisonnable et de les envoyer par un autre canal. Pour révoquer automatiquement les messages à une date prédéfinie, définissez une date d'expiration .
Le destinataire est hors ligne
La plateforme RCS for Business accepte toujours les messages, même si le destinataire est hors ligne. Vous recevez une réponse 200 OK, et la plateforme conserve le message pendant 30 jours avant de tenter une nouvelle livraison. Il est inutile de relancer RCS for Business.
RCS for Business supprime tout message non distribué 30 jours après son envoi.
Selon le cas d'utilisation de votre agent, vous pouvez révoquer un message non distribué avant l'expiration du délai de 30 jours. La révocation permet d'éviter que les utilisateurs hors ligne ne reçoivent un message obsolète à leur retour en ligne. Il existe plusieurs façons de révoquer un message :
- Envoyez une demande de révocation pour déclencher la révocation.
- Définissez une date d'expiration pour que le message soit automatiquement révoqué au moment opportun.
Définir une date d'expiration pour les messages
Les messages de vos agents sont-ils sensibles au facteur temps ? Par exemple, les codes OTP ne sont valides que pendant une courte période. Les offres à durée limitée expirent. Et les rappels de rendez-vous ne sont plus pertinents après la date du rendez-vous. Pour que les messages restent pertinents et envoyés en temps opportun, définissez une date d'expiration. Cela évite aux utilisateurs hors ligne de recevoir des informations obsolètes à leur retour en ligne. L'expiration est également un bon indicateur pour activer votre stratégie de messagerie de secours afin que les utilisateurs reçoivent les informations dont ils ont besoin en temps voulu.
Pour définir une expiration de message, spécifiez l'un des champs suivants dans le message de l'agent :
-
expireTime: l'heure exacte en UTC à laquelle le message expire. -
ttl(durée de vie) : la durée avant l’expiration du message.
Pour les options de formatage et de valeur, voir AgentMessage .
La valeur maximale pour ttl et expireTime est de 15 jours après l'envoi du message.
Bien qu'il n'y ait pas de valeur minimale ttl et expireTime , il est recommandé d'attendre au moins 10 secondes après l'envoi du message afin de réduire considérablement les chances de recevoir une notification de révocation et de livraison.
Durée de vie (TTL) d'un message
Lorsque vous définissez une durée de vie (TTL) pour un message RCS for Business, vous spécifiez la durée pendant laquelle le message est considéré comme valide et distribuable. Si le message n'est pas distribué avec succès à l'appareil de l'utilisateur dans ce délai, la plateforme RCS for Business tente automatiquement de le révoquer.
Lorsque vous demandez la révocation d'un message, vous indiquez à la plateforme RCS for Business d'interrompre la tentative de distribution de ce message. Toutefois, cette action n'affecte que les tentatives de distribution ultérieures. Si l'appareil de l'utilisateur a déjà reçu le message, celui-ci est en cours de traitement et la plateforme RCS for Business ne peut pas le supprimer de l'appareil de l'utilisateur.
Voici ce à quoi vous pouvez vous attendre concernant les notifications :
Message délivré dans les délais impartis : si l’appareil de l’utilisateur se connecte et reçoit le message avant l’expiration du délai imparti, vous recevez une notification
DELIVERED. Aucune notification de révocation ne sera envoyée, car le message a été délivré avec succès. Il s’agit du scénario le plus courant et le plus attendu.Message non distribué avant expiration du TTL : si le TTL expire avant que le message n’atteigne l’appareil de l’utilisateur (par exemple, si l’appareil est hors ligne), la plateforme RCS for Business tente de révoquer le message. Vous recevez alors une notification
TTL_EXPIRATION_REVOKEDindiquant que le message a été retiré de la file d’attente de distribution. Dans ce cas, l’utilisateur ne recevra pas le message.
Recommandations pour la gestion des cas limites
Notre système traite la livraison des messages RCS for Business et l'expiration de la durée de vie (TTL) en parallèle. De ce fait, il peut arriver, très rarement, que le moment des notifications soit inattendu. Par exemple, vous pourriez recevoir à la fois une notification de livraison et une notification TTL, ou n'en recevoir aucune.
Voici nos recommandations pour la gestion des notifications de messages RCS for Business :
Notification
DELIVERED: Si vous recevez une notificationDELIVEREDpour un message, cela confirme que le message est bien parvenu à son destinataire. Vous pouvez ignorer sans risque les notifications de durée de vie (TTL) ultérieures concernant ce message.Notification
TTL_EXPIRATION_REVOKED: Si vous recevez une notification TTL avec le statutTTL_EXPIRATION_REVOKED, cela signifie que le système RCS for Business cesse de tenter de remettre ce message. Vous devez considérer ce message comme non remis et appliquer votre stratégie de repli si nécessaire.Notification TTL avec un autre statut : si vous recevez une notification TTL avec un autre statut, cela indique une tentative de révocation non concluante.
- Pour les messages critiques, tels que les mots de passe à usage unique (OTP), lancez votre méthode de repli.
- Pour les messages non critiques, décidez s'il convient ou non de déclencher le mécanisme de repli.
- Absence de notifications : Dans de très rares cas, le système peut ne pas envoyer de notification TTL et le client peut également ne pas générer de notification de livraison. Ce cas est extrêmement rare.
Définir le type de trafic de messages
L'API RBM inclut un champ messageTrafficType pour catégoriser les messages. Si les cas d'utilisation des agents définissent toujours leur comportement et les règles métier applicables, messageTrafficType permet une catégorisation plus fine du contenu des messages. Ainsi, un seul agent peut gérer plusieurs cas d'utilisation. À l'heure actuelle, cela n'a aucun impact sur les cas d'utilisation ou les règles métier existants.
Ce champ est facultatif, mais il est recommandé de le renseigner dès maintenant afin d'éviter toute erreur lorsqu'il deviendra obligatoire.
Pour définir le type de trafic des messages, attribuez à chaque message le messageTrafficType approprié en fonction de son contenu. RCS for Business prend en charge les types de trafic suivants.
| Type de trafic | Contenu du message | Cas d'utilisation de l'agent |
|---|---|---|
AUTHENTICATION | Pour les messages d'authentification. | OTP |
TRANSACTION | Pour les messages relatifs aux services ou produits existants d'un utilisateur. Par exemple : confirmations, reçus de paiement ou détails de réservation. | Transactionnel ou à usage multiple |
PROMOTION | Pour les messages promotionnels tels que les offres, les réductions, les annonces ou tout autre contenu promotionnel. | Promotionnel ou à usage multiple |
SERVICEREQUEST | Pour les messages concernant les services que l'utilisateur a explicitement demandés. | Code OTP, transactionnel, promotionnel ou multi-usage |
ACKNOWLEDGEMENT | Pour les messages servant à accuser réception d'une action de l'utilisateur, notamment une demande de désabonnement. Ceci confirme que la demande de l'utilisateur a bien été reçue et est en cours de traitement. | Code OTP, transactionnel, promotionnel ou multi-usage |
Si aucun type de trafic n'est défini, le système attribue le type par défaut pour le cas d'utilisation de l'agent .
| Cas d'utilisation de l'agent | type de trafic par défaut |
|---|---|
| OTP | AUTHENTICATION |
| transactionnel | TRANSACTION |
| Promotionnel | PROMOTION |
| Multi-usage | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Les agents multi-usages n'ont pas de type de trafic par défaut. Vous devez définir explicitement le type de trafic pour chaque message en fonction de son contenu. Si vous ne remplacez pas la valeur MESSAGE_TRAFFIC_TYPE_UNSPECIFIED , une erreur se produira.
Limites de taille des messages
La taille maximale de l'ensemble du message AgentMessage converti en chaîne de caractères est de 250 Ko. La partie texte du message est limitée à 3 072 caractères.
Pour éviter toute consommation de données inattendue pour les utilisateurs, la taille maximale d'un fichier pouvant être envoyé via RCS for Business est de 100 Mio, et la taille totale combinée de tous les fichiers multimédias et pièces jointes PDF dans un même message RCS for Business ne doit pas dépasser 100 Mio (1 Mio = 1 048 576 octets). Pour plus d'informations, consultez la documentation relative aux fichiers multimédias et PDF .
Texte
Les messages les plus simples sont textuels. Les SMS sont parfaitement adaptés pour communiquer des informations sans nécessiter d'éléments visuels, d'interactions complexes ou de réponses.
Exemple
Le code suivant envoie un message en texte brut. Pour les options de formatage et de valeur, consultez phones.agentMessages.create .
boucle
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", );
Contenu du message de base - conversion des SMS
Les opérateurs ont mis en place des modèles de facturation pour accompagner la migration des SMS vers le système RCS pour les entreprises. Un message RCS pour les entreprises contenant jusqu'à 160 caractères UTF-8 est appelé un message de base.
Lors de la rédaction d'une requête pour l'envoi d'un message de base, n'oubliez pas que chaque caractère compte pour 1 octet (UTF-8). Si votre message contient des caractères spéciaux, comme des émojis ou des caractères multi-octets, chaque caractère compte pour 2 à 4 caractères UTF-8, voire plus.
Saisissez du texte dans la case pour vérifier sa longueur :
Aperçu du contenu et des liens des SMS
Les clients RCS peuvent implémenter des aperçus de liens. Si un message RCS for Business en texte brut inclut une URL de site web avec des balises openGraph , le client peut générer un aperçu (image, titre, etc.), offrant ainsi une expérience plus riche. Par exemple, consultez un message simple avec aperçu d'URL .
Notez que le client RCS peut permettre à l'utilisateur de désactiver les aperçus des liens.
Mots de passe à usage unique pour la vérification des utilisateurs
Vous pouvez utiliser RCS for Business pour envoyer des mots de passe à usage unique (OTP) afin de vérifier automatiquement l'identité des utilisateurs grâce à l'API SMS Retriever. Il n'existe pas d'API dédiée pour lire les OTP reçus via RCS for Business.
Comment ça marche pour Android
Pour les applications Android enregistrées auprès de l' API SMS Retriever , celle-ci attend un message RCS for Business correctement formaté. Ce message doit contenir le code OTP et un hachage unique identifiant votre application.
Lorsqu'un message RCS for Business est reçu au format correct, l'API SMS Retriever le traite comme un code OTP par SMS. Une fois le hachage associé à votre application, le code OTP est extrait et transmis à votre application pour la vérification automatique de l'utilisateur.
- Exemple de SMS RCS for Business pour la vérification de l'utilisateur :
Your code is <OTP><app hash>. - Exemple :
Your code is 123456 M8tue43FGT.
Pour en savoir plus sur SMS Retriever et les API associées, consultez la documentation de SMS Retriever . Pour plus de détails sur la vérification automatique des utilisateurs dans les applications enregistrées auprès de l'API SMS Retriever, consultez ce diagramme de flux .
Comment ça fonctionne sur iOS
Sous iOS, la gestion intégrée des mots de passe à usage unique (OTP) détecte et propose automatiquement les OTP RCS pour entreprises pour le remplissage automatique, comme pour les OTP envoyés par SMS. Aucune intégration API spécifique n'est requise pour que l'application iOS puisse lire l'OTP.
Fichiers multimédias et PDF
Lorsque vous envoyez un message contenant une image, une vidéo, un fichier audio ou un fichier PDF, votre agent doit fournir une URL accessible publiquement pour le contenu ou télécharger directement le fichier.
La taille maximale d'un fichier pouvant être envoyé est de 100 Mio, et la taille totale combinée de tous les fichiers multimédias et pièces jointes PDF dans un seul message ne doit pas dépasser 100 Mio.
Compression et transcodage des médias
La plateforme RCS for Business transcode et compresse automatiquement les fichiers multimédias (tels que les images et les vidéos) avant de les envoyer afin de garantir un chargement rapide et un bon fonctionnement sur différents réseaux et appareils.
La compression repose sur la qualité du média d'entrée plutôt que sur la seule limite de taille des fichiers. Ainsi, un fichier peut être compressé même si sa taille est largement inférieure à la limite maximale de 100 Mio. Les normes de transcodage évoluant constamment, il n'existe pas de limite de taille fixe déterminant le moment où le transcodage est ignoré. Testez différents formats, dimensions et taux de compression pour trouver le compromis optimal pour vos données.
Spécifications des miniatures
Pour les fichiers multimédias, vous pouvez également spécifier une vignette permettant aux utilisateurs de prévisualiser le contenu avant de cliquer dessus. Pour les fichiers audio, le widget audio par défaut est utilisé comme espace réservé.
- La taille maximale d'une vignette est de 100 ko. Pour une expérience utilisateur optimale, nous recommandons une taille de 50 ko ou moins.
- Le format de la miniature doit correspondre à celui du fichier original.
Gestion des caches et des URL
La plateforme RCS for Business met les fichiers en cache pendant 60 jours et l'API renvoie un identifiant de fichier que votre agent peut inclure dans les messages aux utilisateurs. Au bout de 60 jours, RCS for Business supprime les fichiers du cache.
Lorsqu'on spécifie des fichiers par URL, il est recommandé de définir contentMessage.forceRefresh sur false . Définir contentMessage.forceRefresh sur true force RCS for Business à récupérer le nouveau contenu à partir de l'URL spécifiée, même si le contenu de l'URL est en cache, ce qui augmente les délais de livraison des messages pour les utilisateurs.
Exemple d'URL de fichier
Le code suivant envoie une image. Pour les options de formatage et de valeur, consultez AgentContentMessage .
boucle
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");
Vous pouvez également télécharger les fichiers multimédias avant de les envoyer dans un message avec files.create .
Exemple de téléchargement de fichiers
Le code suivant télécharge un fichier vidéo et une vignette, puis envoie les deux fichiers dans un message. Pour les options de formatage et de valeur, consultez files.create et AgentContentMessage .
boucle
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" } } }'
Types de médias pris en charge
RCS for Business prend en charge les types de médias suivants. Pour les vignettes, seuls les formats image/jpeg, image/jpg, image/gif et image/png sont pris en charge.
| Type de média | Type de document | Extension | Fonctionne avec des cartes enrichies |
|---|---|---|---|
| application/ogg | Audio OGG | .ogx | Non |
| application/pdf | Oui (uniquement pour Google Messages en Inde) | ||
| audio/aac | Audio AAC | .aac | Non |
| audio/mp3 | Audio MP3 | .mp3 | Non |
| audio/mpeg | Audio MPEG | .mpeg | Non |
| audio/mpg | Audio MPG | .mp3 | Non |
| audio/mp4 | Audio MP4 | .mp4 | Non |
| audio/mp4-latm | Audio MP4-latm | .mp4 | Non |
| audio/3gpp | Audio 3GPP | .3gp | Non |
| image/jpeg | JPEG | .jpeg, .jpg | Oui |
| image/gif | GIF | .gif | Oui |
| image/png | PNG | .png | Oui |
| vidéo/h263 | Vidéo H263 | .h263 | Oui |
| vidéo/m4v | Vidéo M4V | .m4v | Oui |
| vidéo/mp4 | Vidéo MP4 | .mp4 | Oui |
| vidéo/mpeg4 | Vidéo MPEG-4 | .mp4, .m4p | Oui |
| vidéo/mpeg | Vidéo MPEG | .mpeg | Oui |
| vidéo/webm | Vidéo WEBM | .webm | Oui |
Suggestions
Votre agent envoie des suggestions (réponses suggérées et actions suggérées) dans des listes de suggestions ou dans des fiches enrichies .
Réponses suggérées
Les réponses suggérées guident les utilisateurs dans les conversations en fournissant des réponses auxquelles votre agent sait comment réagir.
Lorsqu'un utilisateur sélectionne une réponse suggérée, votre agent reçoit un événement contenant le texte de la réponse et les données de renvoi . La charge utile ne peut excéder 2 048 caractères.
Exemple
Le code suivant envoie un texte avec deux réponses suggérées. Pour les options de mise en forme et de valeur, consultez SuggestedReply .
boucle
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 );
actions suggérées
Les actions suggérées guident les utilisateurs dans les conversations en tirant parti des fonctionnalités intégrées de leurs appareils. Votre agent peut leur suggérer de composer un numéro, d'ouvrir un lieu sur une carte, de partager une position, d'ouvrir une URL ou de créer un événement dans leur calendrier.
Pour chaque action suggérée, vous pouvez éventuellement fournir une URL de repli (2 048 caractères maximum). Cette URL s’ouvre dans une nouvelle fenêtre de navigateur si l’appareil de l’utilisateur ne prend pas en charge l’action suggérée.
Lorsqu'un utilisateur appuie sur une action suggérée, votre agent reçoit un événement contenant les données de retour de l'action .
Pour les options de mise en forme et de valeur, consultez SuggestedAction .
Affichage des suggestions
Il existe deux façons d'afficher les suggestions :
- Persistant : Actions ou réponses suggérées affichées dans la bulle de message et qui restent fixes tout au long de la conversation.
- Éphémères : Suggestions affichées en dehors de la bulle de message et qui disparaissent lorsque la conversation se poursuit.
Formats de messages pris en charge
- Suggestions récurrentes : travaillez avec des messages texte autonomes et des cartes enrichies.
- Suggestions temporaires : Utilisez des SMS, des messages multimédias et des cartes enrichies.
Combiner les suggestions
Vous pouvez combiner suggestions permanentes et temporaires dans un même message ou une même carte enrichie.
- Messages texte : les suggestions sont temporaires par défaut. Pour qu’elles restent dans la bulle, vous devez les configurer comme persistantes.
- Cartes enrichies : celles-ci prennent en charge par défaut jusqu’à quatre suggestions permanentes. Vous pouvez ensuite ajouter des suggestions temporaires sous forme de « liste de suggestions » en dessous de la carte.
Limites de suggestion
Un seul SMS peut contenir jusqu'à 11 suggestions. Les suggestions permanentes sont comptabilisées dans cette limite. Par exemple, si vous incluez 4 suggestions permanentes, vous pouvez ajouter jusqu'à 7 suggestions temporaires.
| Type de suggestion | Limite | Là où ils apparaissent |
|---|---|---|
| Persistant | Jusqu'à 4 | À l'intérieur de la bulle de message |
| Transitoire | Jusqu'à 11 | En dehors de la bulle (comme des chips) |
Limite de caractères
Chaque suggestion est limitée à 25 caractères.
Transparence des URL dans les actions suggérées
Pour instaurer la confiance des utilisateurs, l'URL sous-jacente est affichée sur une deuxième ligne de texte à l'intérieur du bouton de suggestion pour l'action « Ouvrir une URL ». Ce comportement uniforme s'applique aux messages texte, aux cartes enrichies et aux carrousels.
Soutien apporté aux clients pour leurs suggestions persistantes
- Compatible avec : Google Messages (version
20260225.00ou ultérieure). - Non pris en charge : les versions de Google Messages antérieures à
20260225.00, iOS et Samsung Messages.
Composez un numéro
L'action « Composer » permet à l'utilisateur de composer un numéro de téléphone indiqué par votre agent. Les numéros de téléphone ne peuvent contenir que des chiffres ( 0-9 ), le signe plus ( + ), l'astérisque ( * ) et le dièse ( # ). Le format international E.164 (par exemple, +14155555555 ) est pris en charge, mais non obligatoire. Autrement dit, +14155555555 et 1011 sont tous deux valides.
Exemple
Le code suivant envoie une action de numérotation. Pour les options de formatage et de valeur, consultez DialAction .
boucle
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 );
Afficher un emplacement
L'action « Afficher la position » permet d'afficher une position dans l'application de cartes par défaut de l'utilisateur. Vous pouvez spécifier la position par latitude et longitude ou à l'aide d'une requête basée sur la position actuelle de l'utilisateur. Vous pouvez également définir un libellé personnalisé pour l'épingle affichée dans l'application de cartes.
Exemple
Le code suivant envoie une action de localisation de vue. Pour les options de formatage et de valeur, consultez ViewLocationAction .
boucle
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 );
Partager un lieu
L'action « Partager ma position » permet à l'utilisateur de partager sa position avec votre agent. Il peut partager sa position actuelle ou une position sélectionnée manuellement dans l'application Cartes.
Exemple
Le code suivant envoie une action de partage de position. Pour les options de formatage et de valeur, consultez ShareLocationAction .
boucle
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 );
Ouvrir une URL
L'action Ouvrir une URL permet de diriger les utilisateurs vers une page web spécifiée par votre agent. Par défaut, la page s'ouvre dans le navigateur de l'utilisateur. Vous pouvez également configurer l'ouverture de la page web dans une vue web. Consultez la section Ouvrir une URL avec une vue web pour plus d'informations.
Uniquement dans Google Messages
Affichage de l'URL sous-jacente : pour une meilleure transparence dans la messagerie A2P, Google Messages affiche l'adresse URL sous-jacente dans les suggestions d'actions « Ouvrir une URL ». Cette modification concerne les suggestions d'actions dans les cartes enrichies standard et les carrousels de cartes enrichies .
Affichage de l'icône de l'application pour les liens Web : si l'utilisateur a configuré une application par défaut pour la page Web, c'est cette application qui s'ouvre à la place du navigateur ou de la vue Web, et le bouton de suggestion affiche son icône. Pour que l'icône de l'application apparaisse dans Google Messages, vous devez fournir l'URL complète et directe. Si vous utilisez une URL raccourcie, l'icône par défaut « Ouvrir l'URL » s'affiche.
Exemple
Le code suivant envoie une action d'ouverture d'URL. Pour les options de formatage et de valeur, consultez OpenUrlAction .
boucle
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 );
Ouvrir une URL avec une vue Web
L'action « Ouvrir l'URL avec vue Web » charge la page Web spécifiée dans l'application de messagerie, en utilisant le moteur de rendu de votre navigateur par défaut. L'utilisateur peut ainsi interagir avec la page Web sans quitter la conversation RCS for Business. Si l'appareil de l'utilisateur ne prend pas en charge les vues Web, la page s'ouvre dans son navigateur. Pour activer les vues Web, consultez la documentation OpenURLApplication .
Les vues Web proposent trois modes d'affichage. Pour plus d'informations sur les options de mise en forme et de valeurs, consultez WebviewViewMode .
- Plein écran : La page web occupe tout l'écran
- Moitié : La page web occupe la moitié de l'écran
- Format allongé : La page web occupe les trois quarts de l'écran
Exemple
Le code suivant envoie une URL ouverte avec une action WebView. Pour les options de formatage et de valeur, consultez OpenURLAction .
boucle
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; }
Créer un événement de calendrier
L'action « Créer un événement dans le calendrier » ouvre l'application calendrier de l'utilisateur et lance la création d'un nouvel événement avec les informations spécifiées.
Un titre est obligatoire pour l'événement. Il ne doit pas dépasser 100 caractères. La description de l'événement est facultative et ne doit pas dépasser 500 caractères.
Exemple
Le code suivant envoie une action de création d'événement de calendrier. Pour les options de formatage et de valeur, consultez CreateCalendarEventAction .
boucle
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 );
Liste de suggestions
Votre agent envoie des listes de suggestions accompagnées de messages pour guider les utilisateurs dans leurs actions suivantes. Ces listes s'affichent uniquement lorsque le message correspondant se trouve en bas de la conversation. Tout message ultérieur (qu'il provienne d'un utilisateur ou de votre agent) remplace ces listes.
Les éléments de la liste sont des suggestions de réponses et d'actions .
Les listes de puces contiennent un maximum de 11 puces de suggestion, et chaque étiquette de puce peut comporter un maximum de 25 caractères.
Pour les options de formatage et de valeur, consultez AgentContentMessage .
Cartes riches
Les cartes enrichies combinent médias, texte et suggestions interactives en un seul message. Elles sont idéales pour présenter des informations connexes (par exemple, un produit avec son image, son nom et son prix) et guider les utilisateurs avec une suggestion claire d'étape suivante, comme « Voir les détails ».
Une carte riche peut contenir les éléments suivants :
- Média (image, GIF ou vidéo)
- Texte du titre
- Texte descriptif
- Réponses et actions suggérées (maximum 4)
Chacun de ces champs est facultatif, mais au moins un des champs 1 à 3 doit être inclus dans la carte enrichie.
Plusieurs cartes peuvent être envoyées ensemble dans un carrousel à défilement horizontal.
Notez que la charge utile totale pour une carte riche est de 250 Ko.
Pour plus de détails techniques, consultez la documentation des cartes Rich .
Hauteur de la carte
Les cartes enrichies s'étendent verticalement pour afficher leur contenu. Leur hauteur minimale est de 112 DP et leur hauteur maximale de 344 DP. Si le contenu d'une carte ne remplit pas sa hauteur minimale, la carte s'étend et comble l'espace disponible avec de l'espace blanc.
Les supports multimédias des cartes enrichies doivent correspondre à l'une des trois hauteurs suivantes :
- Court : 112 DP
- Moyen : 168 DP
- Hauteur : 264 DP
Si le contenu multimédia ne correspond pas aux dimensions de la carte compte tenu de la hauteur sélectionnée, l'aperçu du contenu multimédia est choisi en zoomant et en le recadrant.
Exemple
Le code suivant envoie une carte enrichie avec une image et des suggestions de réponses. Pour les options de mise en forme et de valeurs, consultez RichCard .
boucle
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");
Carrousels de cartes riches
Les carrousels regroupent plusieurs cartes interactives , permettant aux utilisateurs de comparer les articles et de réagir à chacun individuellement.
Un carrousel peut contenir de deux à dix cartes enrichies. Ces cartes doivent respecter les exigences générales relatives à leur contenu et à leur hauteur, telles que décrites dans la documentation correspondante . Pour plus d'informations sur la mise en page et les spécifications des carrousels, consultez la documentation Carrousel .
Exemple
Le code suivant envoie un carrousel de cartes enrichies. Pour les options de mise en forme et de valeurs, consultez RichCard .
boucle
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);