Los agentes de RCS para empresas se comunican con los usuarios enviando y recibiendo mensajes. Para enviar mensajes a los usuarios, tu agente envía solicitudes de mensajes a la API de RCS Business Messaging. Una sola solicitud puede incluir texto, tarjetas enriquecidas, archivos multimedia y PDF, respuestas sugeridas y acciones sugeridas.
La plataforma de RCS para empresas devuelve errores en ciertas situaciones para ayudarte a administrar la entrega de mensajes:
- Si envías un mensaje a un usuario cuyo dispositivo no admite RCS o no tiene
RCS habilitado, la plataforma de RCS para empresas devuelve
un error
404 NOT_FOUND. En este caso, puedes intentar comunicarte con el usuario a través de los métodos de resguardo definidos en tu infraestructura. - Si envías un mensaje a un usuario de RCS en una red en la que aún no se lanzó tu agente o en una red que no habilitó el tráfico de RCS, la plataforma de RCS para empresas devuelve un error
404 NOT_FOUND. - Si envías un mensaje con funciones que el dispositivo de un usuario no admite,
la plataforma de RCS para empresas devuelve el error
400 INVALID_ARGUMENTy no entrega el mensaje.
Como parte de tu estrategia de mensajería multicanal, se recomienda revocar los mensajes que no se entreguen después de un tiempo razonable y enviarlos a través de un canal diferente. Para revocar mensajes automáticamente en un momento predefinido, establece un vencimiento de mensajes.
El destinatario no está en línea
La plataforma de RCS para empresas sigue aceptando un mensaje para su entrega si el
destinatario no tiene conexión. Recibes una respuesta 200 OK, y la plataforma de RCS para empresas
retiene el mensaje y reintenta la entrega durante 30 días. No es necesario que le pidas a RCS para empresas que vuelva a enviar el mensaje.
RCS para empresas borra los mensajes no entregados 30 días después de que se enviaron.
Según el caso de uso de tu agente, es posible que quieras revocar un mensaje no entregado antes de este tiempo de espera de 30 días. La revocación puede evitar que los usuarios sin conexión reciban un mensaje desactualizado cuando vuelvan a conectarse. Existen varias formas de revocar un mensaje:
- Envía una solicitud de revocación para activar la revocación.
- Establece un vencimiento para el mensaje para revocarlo automáticamente en el momento adecuado.
Establece un vencimiento para los mensajes
¿El mensaje de tu agente es urgente? Por ejemplo, las OTP solo son válidas durante un período breve. Las ofertas por tiempo limitado vencen. Y los recordatorios de citas no son pertinentes después de la fecha de la cita. Para que los mensajes sean oportunos y pertinentes, establece un vencimiento para ellos. Esto puede evitar que los usuarios sin conexión reciban contenido inactivo cuando vuelvan a conectarse. La fecha de vencimiento también es un buen indicador para invocar tu estrategia de mensajería de resguardo, de modo que los usuarios obtengan la información que necesitan a tiempo.
Para establecer un vencimiento de mensaje, especifica uno de los siguientes campos en el mensaje del agente:
expireTime: Es la hora exacta en UTC en la que vence el mensaje.ttl(tiempo de actividad): Es la cantidad de tiempo que transcurre antes de que venza el mensaje.
Para conocer las opciones de formato y valor, consulta AgentMessage.
El valor máximo para ttl y expireTime es de 15 días después del envío del mensaje.
El valor mínimo para ttl y expireTime es de seis segundos después del envío del mensaje.
Recomendaciones para configurar el vencimiento de los mensajes
Para los mensajes de autenticación (OTP): Establece
ttlen 15 segundos o más después del envío del mensaje para reducir significativamente la probabilidad de condiciones de carrera de entrega y revocación.Para mensajes transaccionales y promocionales: Establece vencimientos más largos (al menos 60 segundos, o minutos a horas según el caso de uso) porque los dispositivos requieren tiempo adicional para analizar mensajes y descargar o procesar contenido multimedia enriquecido, y los usuarios pueden experimentar breves caídas de conectividad (por ejemplo, en un ascensor o un túnel).
Tiempo de actividad (TTL) de un mensaje
Cuando estableces un TTL para un mensaje de RCS para empresas, especificas cuánto tiempo se debe considerar válido y entregable. Si el mensaje no se entrega correctamente al dispositivo del usuario dentro de este período de TTL, la plataforma de RCS para empresas intenta revocarlo automáticamente.
Cuando inicias la revocación de un mensaje, solicitas que la plataforma de RCS para empresas detenga el intento de entrega de ese mensaje específico. Sin embargo, esta acción solo afecta los intentos de entrega futuros. Si el dispositivo de un usuario ya recuperó el mensaje correctamente, este se está procesando y la plataforma de RCS para empresas no puede revocarlo del dispositivo del usuario.
Esto es lo que puedes esperar con respecto a las notificaciones:
Mensaje entregado dentro del TTL: Si el dispositivo del usuario se conecta y recibe el mensaje antes de que venza el TTL, recibirás una notificación
DELIVERED. No se enviará ninguna notificación de revocación, ya que el mensaje se entregó correctamente. Esta es la situación más común y esperada.Mensaje no entregado antes del vencimiento del TTL: Si el TTL vence antes de que el mensaje llegue al dispositivo del usuario (por ejemplo, si el dispositivo está sin conexión), la plataforma de RCS para empresas intenta revocar el mensaje. Recibirás una notificación
TTL_EXPIRATION_REVOKED, que indica que el mensaje se quitó correctamente de la cola de entrega. En este caso, el usuario no recibirá el mensaje.
Recomendaciones para controlar casos extremos
Nuestro sistema procesa la entrega de mensajes de RCS para empresas y los vencimientos de TTL en paralelo. Por este motivo, en muy raras ocasiones, es posible que veas casos extremos en los que el momento de las notificaciones sea inesperado. Por ejemplo, podrías recibir una notificación de entrega y una de TTL, o ninguna de las dos.
Estas son nuestras recomendaciones para controlar las notificaciones de mensajes de RCS para empresas:
Notificación
DELIVERED: Si recibes una notificaciónDELIVEREDpara un mensaje, se confirma que el mensaje llegó al usuario. Puedes ignorar sin problemas las notificaciones de TTL posteriores para ese mensaje específico.Notificación de
TTL_EXPIRATION_REVOKED: Si recibes una notificación de TTL con el estadoTTL_EXPIRATION_REVOKED, significa que el sistema de RCS para empresas deja de intentar entregar ese mensaje específico. Debes tratar este mensaje como no entregado y continuar con tu estrategia de resguardo si es necesario.Notificación de TTL con cualquier otro estado: Si recibes una notificación de TTL con cualquier otro estado, esto indica un intento de revocación no concluyente.
- Para los mensajes críticos, como las contraseñas de un solo uso (OTP), inicia tu método de resguardo.
- En el caso de los mensajes no críticos, decide si iniciar o no el resguardo.
- Sin notificaciones: En casos extremos excepcionales, es posible que el sistema no envíe una notificación de TTL y que el cliente tampoco genere una notificación de entrega. Este es un caso extremadamente raro.
Establece el tipo de tráfico de mensajes
La API de RBM incluye un campo messageTrafficType para categorizar los mensajes.
Si bien los casos de uso de agentes aún definen el comportamiento de los agentes y qué reglas empresariales se aplican, messageTrafficType permite una categorización más detallada del contenido de los mensajes. En última instancia, esto permite que un solo agente controle
varios casos de uso. Por el momento, no hay ningún impacto en los casos de uso de agentes o las reglas
comerciales existentes.
Este campo es opcional, pero te recomendamos que lo configures ahora para no recibir un error cuando el campo sea obligatorio.
Para establecer el tipo de tráfico de mensajes, asigna el messageTrafficType
adecuado para cada mensaje según su contenido. En la siguiente tabla, se enumeran los tipos de tráfico admitidos y los casos de uso esperados de los agentes. Esta asignación es una guía recomendada sobre el uso esperado, no una restricción que la API aplique de manera forzosa en este momento.
| Tipo de tráfico | Contenido del mensaje | Caso de uso recomendado del agente |
|---|---|---|
AUTHENTICATION |
Para los mensajes de autenticación. | OTP |
TRANSACTION |
Para mensajes sobre los servicios o productos existentes de un usuario. Por ejemplo: confirmaciones, recibos de pago o detalles de la reserva. | Transaccional o multiuso |
PROMOTION |
Para mensajes promocionales, como ofertas, descuentos, anuncios o cualquier otro contenido promocional. | Promocional o multiuso |
SERVICEREQUEST |
Para mensajes sobre servicios que el usuario solicitó de forma explícita. | OTP, Transaccional, Promocional o Multiuso |
ACKNOWLEDGEMENT |
Para los mensajes que se usan para confirmar la acción de un usuario, específicamente una solicitud de anulación de la suscripción. Esto confirma que se recibió la solicitud del usuario y que se está procesando. | OTP, Transaccional, Promocional o Multiuso |
Si no se establece ningún tipo de tráfico, el sistema asigna el tipo predeterminado para el caso de uso del agente.
| Caso de uso del agente | Tipo de tráfico predeterminado |
|---|---|
| OTP | AUTHENTICATION |
| Transaccional | TRANSACTION |
| Promocional | PROMOTION |
| Uso múltiple | MESSAGE_TRAFFIC_TYPE_UNSPECIFIED |
Los agentes de uso múltiple no tienen un tipo de tráfico predeterminado. Debes establecer el tipo de tráfico
de forma explícita para cada mensaje según su contenido. Si no reemplazas el valor MESSAGE_TRAFFIC_TYPE_UNSPECIFIED, el mensaje se aceptará y se entregará sin una clasificación de tipo de tráfico específica.
Límites de tamaño de los mensajes
El tamaño máximo de todo el AgentMessage convertido en cadena es de 250 KB. La parte de texto del mensaje tiene su propio límite de 3,072 caracteres.
Para evitar que los usuarios consuman datos de forma inesperada, el tamaño máximo de un archivo que se puede enviar a través de RCS para empresas es de 100 MiB, y el tamaño total combinado de todos los archivos multimedia y PDF adjuntos en un solo mensaje de RCS para empresas no debe superar los 100 MiB. (1 MiB = 1,048,576 bytes). Para obtener más información, consulta Archivos multimedia y PDF.
Texto
Los mensajes más simples están compuestos de texto. Los mensajes de texto son más adecuados para comunicar información sin necesidad de imágenes, interacción compleja o respuesta.
Ejemplo
El siguiente código envía un mensaje de texto sin formato. Para conocer las opciones de formato y valor, consulta phones.agentMessages.create.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!" }, "messageTrafficType": "PROMOTION" }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { messageText: 'Hello, world!', msisdn: '+12223334444', }; // Send a simple message to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444" ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a simple RBM text message message_text = messages.TextMessage('Hello, world!') # Send text message to the device messages.MessageCluster().append_message(message_text).send_to_msisdn('+12223334444')
C#
using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", );
Contenido de Basic Message: conversión de SMS
Los operadores introdujeron modelos de facturación para respaldar el cambio de los mensajes SMS a RCS para empresas. Un mensaje de RCS para empresas que contiene hasta 160 caracteres UTF-8 se denomina mensaje básico.
Cuando construyas una solicitud para enviar un mensaje básico, recuerda que los caracteres se cuentan como 1 byte (UTF-8). Si envías un mensaje que contiene caracteres especiales, como emojis o un conjunto de caracteres de varios bytes, cada carácter cuenta como 2 o 4 caracteres UTF-8, o más.
Ingresa texto en el cuadro para verificar su longitud:
Contenido de mensajes de texto y vistas previas de vínculos
Los clientes de RCS pueden implementar vistas previas de vínculos. Si un mensaje de RCS para empresas solo de texto incluye una URL para un sitio web con etiquetas de Open Graph, el cliente puede generar una vista previa (imagen, título, etc.), lo que proporciona una experiencia más enriquecida. Por ejemplo, consulta un mensaje básico con una vista previa de la URL.
Ten en cuenta que el cliente de RCS puede permitir que el usuario inhabilite las vistas previas de vínculos.
Contraseñas de un solo uso para la verificación de usuarios
Puedes usar RCS para empresas para enviar contraseñas de un solo uso (OTP) para la verificación automática de usuarios con la API de SMS Retriever. No hay una API dedicada para leer las OTP que llegan a través de RCS para empresas.
Cómo funciona en Android
En el caso de las apps para Android que se registraron con la API de SMS Retriever, la API escucha un mensaje de RCS para empresas con el formato correcto. Este mensaje debe contener la OTP y un hash único que identifique tu app.
Cuando se recibe un mensaje de RCS para empresas con el formato correcto, la API de SMS Retriever lo procesa de la misma manera que lo haría con una OTP por SMS. Después de que el hash coincida con tu app, se extraerá la OTP y se reenviará a tu app para la verificación automática del usuario.
- Ejemplo de mensaje de texto de RCS para empresas para la verificación de usuarios:
Your code is <OTP><app hash>. - Ejemplo:
Your code is 123456 M8tue43FGT.
Para obtener más información sobre el SMS Retriever y las APIs relacionadas, consulta la documentación del SMS Retriever. Para obtener detalles sobre la verificación automática de usuarios en apps que están registradas con la API de SMS Retriever, consulta este diagrama de flujo.
Cómo funciona en iOS
En iOS, el control de OTP integrado del sistema detecta y sugiere automáticamente las OTP de RCS para empresas para el autocompletado, al igual que las OTP por SMS. No se requiere ninguna integración de API específica para que la app para iOS lea la OTP.
Archivos multimedia y PDF
Cuando envías un mensaje con una imagen, un video, un audio o un archivo PDF, tu agente debe proporcionar una URL de acceso público para el contenido o subir el archivo directamente.
El tamaño máximo de un archivo que se puede enviar es de 100 MiB, y el tamaño total combinado de todos los archivos multimedia y PDF adjuntos en un solo mensaje no debe superar los 100 MiB.
Compresión y transcodificación de contenido multimedia
La plataforma de RCS para empresas transcodifica y comprime automáticamente los archivos multimedia (como imágenes y videos) antes de enviarlos para garantizar que se carguen rápido y funcionen bien en diferentes redes y dispositivos.
La compresión se basa en la calidad del contenido multimedia de entrada, no estrictamente en los límites de tamaño de los archivos. Esto significa que un archivo se puede comprimir incluso si su tamaño está muy por debajo del límite máximo de 100 MiB. Los estándares de transcodificación cambian constantemente, por lo que no hay un límite de tamaño de archivo fijo que determine cuándo se omite la transcodificación. Experimenta con diferentes formatos de contenido multimedia, dimensiones y tasas de compresión para encontrar el equilibrio óptimo para tus cargas útiles.
Especificaciones de las miniaturas
En el caso de los archivos multimedia, también puedes especificar una imagen en miniatura que permita a los usuarios obtener una vista previa del contenido antes de hacer clic en él. En el caso de los archivos de audio, se usa el widget de audio predeterminado como marcador de posición.
- El tamaño máximo del archivo de una miniatura es de 100 kB. Para obtener una experiencia del usuario óptima, recomendamos que sea de 50 kB o menos.
- La relación de aspecto de la miniatura debe coincidir con la del archivo original.
Almacenamiento en caché y administración de URLs
La plataforma de RCS para empresas almacena en caché los archivos durante 60 días, y la API devuelve un ID de archivo que tu agente puede incluir en los mensajes para los usuarios. Después de 60 días, RCS para empresas quita los archivos de la caché.
Cuando especifiques archivos por URL, se recomienda establecer
contentMessage.forceRefresh en false. Si configuras contentMessage.forceRefresh
como true, se fuerza a RCS para empresas a recuperar contenido nuevo de la URL especificada,
incluso si el contenido de la URL se almacena en caché, lo que aumenta los tiempos de entrega de los mensajes
para los usuarios.
Ejemplo de URL de archivo
El siguiente código envía una imagen. Para conocer las opciones de formato y valor, consulta
AgentContentMessage.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "contentInfo": { "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let params = { fileUrl: 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif', msisdn: '+12223334444', }; // Send an image/video to a device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.AgentContentMessage; import com.google.api.services.rcsbusinessmessaging.v1.model.AgentMessage; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); String fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // create media only message AgentContentMessage agentContentMessage = new AgentContentMessage(); agentContentMessage.setContentInfo(new ContentInfo().setFileUrl(fileUrl)); // attach content to message AgentMessage agentMessage = new AgentMessage(); agentMessage.setContentMessage(agentContentMessage); rbmApiHelper.sendAgentMessage(agentMessage, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create media file attachment file_message = messages.FileMessage('http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif') messages.MessageCluster().append_message(file_message).send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); string fileUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create content info with the file url ContentInfo contentInfo = new ContentInfo { FileUrl = fileUrl }; // Attach content info to a message AgentContentMessage agentContentMessage = new AgentContentMessage { ContentInfo = contentInfo, }; // Attach content to message AgentMessage agentMessage = new AgentMessage { ContentMessage = agentContentMessage }; rbmApiHelper.SendAgentMessage(agentMessage, "+12223334444");
Como alternativa, puedes subir contenido multimedia antes de enviarlo en un mensaje con files.create.
Ejemplo de carga de archivos
En el siguiente código, se sube un archivo de video y uno de miniatura, y, luego, se envían ambos
archivos en un mensaje. Para conocer las opciones de formato y valor, consulta files.create
y AgentContentMessage.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: video/mp4" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_VIDEO_MEDIA_FILE"# Capture server-specified video file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/upload/v1/files?agentId=AGENT_ID" \ -H "Content-Type: image/jpeg" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ --upload-file "FULL_PATH_TO_THUMBNAIL_MEDIA_FILE"# Capture server-specified image file name from response body JSONcurl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "uploadedRbmFile": { "fileName": "SERVER-SPECIFIED_VIDEO_FILE_NAME", "thumbnailName": "SERVER-SPECIFIED_THUMBNAIL_FILE_NAME" } } }'
Tipos de contenido multimedia compatibles
RCS para empresas admite los siguientes tipos de contenido multimedia. Para las miniaturas, solo se admiten los formatos image/jpeg, image/jpg, image/gif y image/png.
| Tipo de medio | Tipo de documento | Extensión | Funciona con tarjetas enriquecidas |
|---|---|---|---|
| application/ogg | Audio OGG | .ogx | No |
| application/pdf | Sí (solo para Mensajes de Google en India) | ||
| audio/aac | Audio AAC | .aac | No |
| audio/mp3 | audio en MP3 | .mp3 | No |
| audio/mpeg | Audio MPEG | .mpeg | No |
| audio/mpg | Audio MPG | .mp3 | No |
| audio/mp4 | Audio MP4 | .mp4 | No |
| audio/mp4-latm | Audio MP4-latm | .mp4 | No |
| audio/3gpp | Audio 3GPP | .3gp | No |
| image/jpeg | JPEG | .jpeg, .jpg | Sí |
| image/gif | GIF | .gif | Sí |
| image/png | PNG | .png | Sí |
| video/h263 | Video H263 | .h263 | Sí |
| video/m4v | Video M4V | .m4v | Sí |
| video/mp4 | Video MP4 | .mp4 | Sí |
| video/mpeg4 | Video MPEG-4 | .mp4, .m4p | Sí |
| video/mpeg | Video MPEG | .mpeg | Sí |
| video/webm | Video WEBM | .webm | Sí |
Sugerencias
Tu agente envía sugerencias (respuestas sugeridas y acciones sugeridas) en listas de chips de sugerencias o en tarjetas enriquecidas.
Respuestas sugeridas
Las respuestas sugeridas guían a los usuarios a través de las conversaciones, ya que proporcionan respuestas a las que tu agente sabe cómo reaccionar.
Cuando un usuario presiona una respuesta sugerida, tu agente recibe un evento que contiene el texto de la respuesta y los datos de devolución. La carga útil tiene un máximo de 2,048 caracteres.
Ejemplo
El siguiente código envía texto con dos respuestas sugeridas. Para conocer las opciones de formato y valor, consulta SuggestedReply.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with suggestion chips to the device rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); // Send simple text message to user rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggested replies for the message to send to the user cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1')) cluster.append_suggestion_chip(messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2')) # Send a simple message with suggestion chips to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; // Send simple text message with suggestions to user rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Acciones sugeridas
Las acciones sugeridas guían a los usuarios a través de las conversaciones aprovechando la funcionalidad integrada de sus dispositivos. Tu agente puede sugerir que los usuarios marquen un número, abran una ubicación en un mapa, compartan una ubicación, abran una URL o creen un evento de calendario.
Para cada acción sugerida, puedes proporcionar una URL de respaldo (máximo 2,048 caracteres). Esta URL se abre en una ventana nueva del navegador si el dispositivo del usuario no admite la acción sugerida.
Cuando un usuario presiona una acción sugerida, tu agente recibe un evento que contiene los datos de notificación de conversión de la acción.
Para conocer las opciones de formato y valor, consulta SuggestedAction.
Visualización de sugerencias
Existen dos maneras de mostrar sugerencias:
- Persistent: Son acciones o respuestas sugeridas que se muestran dentro de la burbuja de mensaje y permanecen fijas durante toda la conversación.
- Transitorias: Son sugerencias que se muestran fuera del cuadro de mensaje y desaparecen cuando continúa la conversación.
Formatos de mensajes admitidos
- Sugerencias persistentes: Funcionan con mensajes de texto independientes y tarjetas enriquecidas.
- Sugerencias transitorias: Trabajan con mensajes de texto independientes, mensajes multimedia y tarjetas enriquecidas.
Combina sugerencias
Puedes mezclar sugerencias persistentes y transitorias en el mismo mensaje o tarjeta enriquecida.
- Mensajes de texto: Las sugerencias son temporales de forma predeterminada. Para que permanezcan dentro de la burbuja, debes configurarlas como persistentes.
- Tarjetas enriquecidas: Admiten hasta cuatro sugerencias persistentes de forma predeterminada. Luego, puedes agregar sugerencias transitorias como una "lista de chips" debajo de la tarjeta.
Límites de sugerencias
Un solo mensaje de texto admite un máximo de 11 sugerencias en total. Cualquier sugerencia persistente que incluyas se tiene en cuenta para este límite total. Por ejemplo, si incluyes 4 sugerencias persistentes, puedes agregar hasta 7 sugerencias transitorias.
| Tipo de sugerencia | Límite | Dónde aparecen |
|---|---|---|
| Persistente | Hasta 4 | Dentro de la burbuja de mensaje |
| Transitorios | Hasta 11 | Fuera de la burbuja (como chips) |
Límite de caracteres
Cada sugerencia tiene un máximo de 25 caracteres.
Transparencia de la URL en las acciones sugeridas
Para generar confianza en el usuario, la URL subyacente se muestra como una segunda línea de texto dentro del botón de sugerencia para las acciones sugeridas de "Abrir una URL". Este comportamiento coherente se aplica a los mensajes de texto independientes, las tarjetas enriquecidas y los carruseles.
Clientes compatibles con las sugerencias persistentes
- Compatibilidad: Mensajes de Google (versión
20260225.00o posterior). - No se admiten: Las versiones de Mensajes de Google anteriores a la
20260225.00, iOS y Mensajes de Samsung.
Sugerencias en las notificaciones del sistema
Cuando un usuario recibe un mensaje, Mensajes de Google muestra la primera sugerencia apta directamente en la notificación del sistema Android. Los usuarios pueden presionar esta sugerencia para enviar una respuesta o activar una acción sin necesidad de abrir la app.
Cuando diseñes tus mensajes, ten en cuenta el siguiente comportamiento:
- El orden es importante: Solo se muestra una sugerencia por notificación. Para maximizar la participación, coloca la respuesta o acción sugerida de mayor prioridad en primer lugar en tu lista de sugerencias.
- Acciones excluidas: La acción Compartir ubicación nunca se muestra en las notificaciones del sistema. Los usuarios deben abrir la conversación para compartir su ubicación.
Marcar un número
La acción Marcar guía al usuario para que marque un número de teléfono especificado por tu agente.
Los números de teléfono solo pueden incluir dígitos (0-9), el signo más (+), el asterisco (*)
y el signo de número (#). Se admite el formato internacional E.164 (por ejemplo,
+14155555555), pero no es obligatorio. Es decir, tanto +14155555555 como 1011 son entradas válidas.
Ejemplo
El siguiente código envía una acción de marcado. Para conocer las opciones de formato y valor, consulta
DialAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Call", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/contact/", "dialAction": { "phoneNumber": "+15556667777" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a dial suggested action let suggestions = [ { action: { text: 'Call', postbackData: 'postback_data_1234', dialAction: { phoneNumber: '+15556667777' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a dial suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.DialAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a dial suggested action DialAction dialAction = new DialAction(); dialAction.setPhoneNumber("+15556667777"); // creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Call"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setDialAction(dialAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a dial suggested action suggestions = [ messages.DialAction('Call', 'reply:postback_data_1234', '+15556667777') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a dial an agent suggested action DialAction dialAction = new DialAction { PhoneNumber = "+15556667777" }; // Creating a suggested action based on a dial action SuggestedAction suggestedAction = new SuggestedAction { Text = "Call", PostbackData = "postback_data_1234", DialAction = dialAction }; // Attach action to a suggestion Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Cómo ver una ubicación
La acción Ver ubicación muestra una ubicación en la app de mapas predeterminada del usuario. Puedes especificar la ubicación por latitud y longitud, o con una búsqueda basada en la ubicación actual del usuario. También puedes establecer una etiqueta personalizada para el pin que se muestra en la app de mapas.
Ejemplo
El siguiente código envía una acción de ver ubicación. Para conocer las opciones de formato y valor, consulta ViewLocationAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "View map", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/maps/@37.4220188,-122.0844786,15z", "viewLocationAction": { "latLong": { "latitude": "37.4220188", "longitude": "-122.0844786" }, "label": "Googleplex" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a view location suggested action let suggestions = [ { action: { text: 'View map', postbackData: 'postback_data_1234', viewLocationAction: { latLong: { latitude: 37.4220188, longitude: -122.0844786 }, label: 'Googleplex' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a view location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ViewLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a view location suggested action ViewLocationAction viewLocationAction = new ViewLocationAction(); viewLocationAction.setQuery("Googleplex, Mountain View, CA"); // creating a suggested action based on a view location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("View map"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setViewLocationAction(viewLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a view location suggested action suggestions = [ messages.ViewLocationAction('View map', 'reply:postback_data_1234', query='Googleplex, Mountain View, CA') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // create an view location action ViewLocationAction viewLocationAction = new ViewLocationAction { Query = "Googleplex Mountain View, CA" }; // Attach the view location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ViewLocationAction = viewLocationAction, Text = "View map", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Compartir una ubicación
La acción Compartir ubicación permite que el usuario comparta una ubicación con tu agente. El usuario puede compartir su ubicación actual o una ubicación seleccionada manualmente desde la app de Maps.
Ejemplo
El siguiente código envía una acción para compartir la ubicación. Para conocer las opciones de formato y valor, consulta ShareLocationAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Share your location", "postbackData": "postback_data_1234", "shareLocationAction": {} } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a share location suggested action let suggestions = [ { action: { text: 'Share your location', postbackData: 'postback_data_1234', shareLocationAction: { } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a share location suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.ShareLocationAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a share location suggested action ShareLocationAction shareLocationAction = new ShareLocationAction(); // creating a suggested action based on a share location action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Share location"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setShareLocationAction(shareLocationAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a share location suggested action suggestions = [ messages.ShareLocationAction('Share location', 'reply:postback_data_1234') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a share location action ShareLocationAction shareLocationAction = new ShareLocationAction(); // Attach the share location action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { ShareLocationAction = shareLocationAction, Text = "Share location", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Abrir una URL
La acción Abrir URL te permite guiar a los usuarios a una página web especificada por tu agente. De forma predeterminada, la página web se abre en el navegador del usuario. También puedes configurar la página web para que se abra en una vista web. Consulta Abre una URL con WebView para obtener más detalles.
Solo en Mensajes de Google
Mostrar la URL subyacente: Para mejorar la transparencia en los mensajes de A2P, Mensajes de Google muestra la dirección URL subyacente en las acciones sugeridas de "Abrir una URL". Este cambio afecta las acciones sugeridas en las tarjetas enriquecidas estándar y los carruseles de tarjetas enriquecidas.
Visualización del ícono de la app para vínculos web: Si un usuario tiene una app predeterminada configurada para la página web, se abrirá esa app en lugar del navegador o la vista web, y el botón de sugerencia mostrará el ícono de la app. Para que el ícono de la app aparezca en Mensajes de Google, debes proporcionar la URL directa completa. Si usas una URL abreviada, se mostrará el ícono predeterminado de Abrir URL.
Ejemplo
El siguiente código envía una acción de abrir URL. Para conocer las opciones de formato y valor,
consulta OpenUrlAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define an open URL suggested action let suggestions = [ { action: { text: 'Open Google', postbackData: 'postback_data_1234', openUrlAction: { url: 'https://www.google.com' } } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with an open URL suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating an open url suggested action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl("https://www.google.com"); // creating a suggested action based on an open url action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Open Google"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setOpenUrlAction(openUrlAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create an open url suggested action suggestions = [ messages.OpenUrlAction('Open Google', 'reply:postback_data_1234', 'https://www.google.com') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create an open url action OpenUrlAction openUrlAction = new OpenUrlAction { Url = "https://www.google.com" }; // Attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { OpenUrlAction = openUrlAction, Text = "Open Google", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Abrir una URL con WebView
La acción Abrir URL con WebView carga la página web especificada
en la app de mensajería con el motor de renderización de tu navegador predeterminado. Esto
permite que el usuario interactúe con la página web sin salir de la conversación de RCS
para empresas. Si el dispositivo del usuario no admite vistas web,
la página web se abrirá en el navegador del usuario. Para habilitar las WebViews, consulta
OpenURLApplication.
Las vistas web tienen tres modos de visualización. Para conocer las opciones de formato y valor, consulta
WebviewViewMode.
- Completa: La página web ocupa toda la pantalla.
- Mitad: La página web ocupa la mitad de la pantalla.
- Alta: La página web ocupa tres cuartos de la pantalla.
Ejemplo
El siguiente código envía una acción de abrir URL con WebView. Para conocer las opciones de formato y
valor, consulta OpenURLAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Open Google", "postbackData": "postback_data_1234", "openUrlAction": { "url": "https://www.google.com", "application": "WEBVIEW", "webviewViewMode": "FULL", "description": "Accessibility description" } } } ] } }'
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.OpenUrlAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { String URL = "https://www.google.com"; // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // Create suggestion to view webpage in full mode Suggestion viewInFullMode = getUrlActionInWebview(URL, "FULL") suggestions.add(viewInFullMode); // create suggestion to view webpage in half mode Suggestion viewInHalfMode = getUrlActionInWebview(URL, "HALF") suggestions.add(viewInHalfMode); // create suggestion to view webpage in tall mode Suggestion viewInTallMode = getUrlActionInWebview(URL, "TALL") suggestions.add(viewInTallMode); // Send simple text message with the suggested action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); } /** * Creates a suggested action to open URL in webview. * * @return a suggestion object for an open URL in webview action . */ private Suggestion getUrlActionInWebview(String url, String viewMode) { // create an open url action OpenUrlAction openUrlAction = new OpenUrlAction(); openUrlAction.setUrl(url); openUrlAction.setApplication("WEBVIEW"); openUrlAction.setWebviewViewMode(viewMode); openUrlAction.setDescription("Accessibility description"); // attach the open url action to a suggested action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setOpenUrlAction(openUrlAction); suggestedAction.setText('display_text'); suggestedAction.setPostbackData('postback_data_123'); // attach the action to a suggestion object Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); return suggestion; }
Cómo crear un evento de calendario
La acción Crear evento de calendario abre la app de calendario del usuario y comienza a crear un evento nuevo con la información especificada.
Se requiere un título para el evento de calendario. Tiene un máximo de 100 caracteres. La descripción del evento de calendario es opcional y tiene un máximo de 500 caracteres.
Ejemplo
El siguiente código envía una acción para crear un evento de calendario. Para conocer las opciones de formato y valor, consulta CreateCalendarEventAction.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "text": "Hello, world!", "suggestions": [ { "action": { "text": "Save to calendar", "postbackData": "postback_data_1234", "fallbackUrl": "https://www.google.com/calendar", "createCalendarEventAction": { "startTime": "2020-06-30T19:00:00Z", "endTime": "2020-06-30T20:00:00Z", "title": "My calendar event", "description": "Description of the calendar event" } } } ] } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Define a create calendar event suggested action let suggestions = [ { action: { text: 'Save to calendar', postbackData: 'postback_data_1234', createCalendarEventAction: { startTime: '2020-06-30T19:00:00Z', endTime: '2020-06-30T20:00:00Z', title: 'My calendar event', description: 'Description of the calendar event', }, } }, ]; let params = { messageText: 'Hello, world!', msisdn: '+12223334444', suggestions: suggestions, }; // Send a simple message with a create calendar event suggested action rbmApiHelper.sendMessage(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CreateCalendarEventAction; import com.google.api.services.rcsbusinessmessaging.v1.model.SuggestedAction; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.RbmApiHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); // creating a create calendar event suggested action CreateCalendarEventAction createCalendarEventAction = new CreateCalendarEventAction(); calendarEventAction.setTitle("My calendar event"); calendarEventAction.setDescription("Description of the calendar event"); calendarEventAction.setStartTime("2020-06-30T19:00:00Z"); calendarEventAction.setEndTime("2020-06-30T20:00:00Z"); // creating a suggested action based on a create calendar event action SuggestedAction suggestedAction = new SuggestedAction(); suggestedAction.setText("Save to calendar"); suggestedAction.setPostbackData("postback_data_1234"); suggestedAction.setCreateCalendarEventAction(createCalendarEventAction); // attaching action to a suggestion Suggestion suggestion = new Suggestion(); suggestion.setAction(suggestedAction); suggestions.add(suggestion); // Send simple text message with the suggestion action rbmApiHelper.sendTextMessage( "Hello, world!", "+12223334444", suggestions ); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Create a calendar event suggested action suggestions = [ messages.CreateCalendarEventAction('Save to Calendar', 'reply:postback_data_1234', '2020-06-30T19:00:00Z', '2020-06-30T20:00:00Z', 'My calendar event', 'Description of the calendar event') ] # Create text message to send to user text_msg = messages.TextMessage('Hello, world!') cluster = messages.MessageCluster().append_message(text_msg) # Append suggestions for the message to send to the user for suggestion in suggestions: cluster.append_suggestion_chip(suggestion) # Send a simple message with suggested action to the device cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Create a calendar event action CreateCalendarEventAction calendarEventAction = new CreateCalendarEventAction { Title = "My calendar event", Description = "Description of the calendar event", StartTime = "2020-06-30T19:00:00Z", EndTime = "2020-06-30T20:00:00Z" }; // Attach the calendar event action to a suggested action SuggestedAction suggestedAction = new SuggestedAction { CreateCalendarEventAction = calendarEventAction, Text = "Save to calendar", PostbackData = "postback_data_1234" }; // Attach the action to a suggestion object Suggestion suggestion = new Suggestion { Action = suggestedAction }; List<Suggestion> suggestions = new List<Suggestion> { suggestion }; rbmApiHelper.SendTextMessage( "Hello, world!", "+12223334444", suggestions );
Lista de chips de sugerencias
Tu agente envía listas de chips de sugerencias con mensajes para guiar las acciones posteriores de los usuarios. La lista de chips solo se muestra cuando el mensaje asociado está en la parte inferior de la conversación. Cualquier mensaje posterior en la conversación (ya sea de un usuario o de tu agente) reemplaza la lista de chips.
Los chips de la lista son respuestas sugeridas y acciones sugeridas.
Las listas de chips contienen un máximo de 11 chips de sugerencias, y cada etiqueta de chip puede tener un máximo de 25 caracteres.
Para conocer las opciones de formato y valor, consulta AgentContentMessage.
Tarjetas enriquecidas
Las tarjetas enriquecidas combinan contenido multimedia, texto y sugerencias interactivas en un solo mensaje. Son ideales para presentar información relacionada (por ejemplo, un producto con su imagen, nombre y precio) y guiar a los usuarios con un siguiente paso claro, como una sugerencia de "Ver detalles".
Una tarjeta enriquecida puede contener lo siguiente:
- Contenido multimedia (imagen, GIF o video)
- Texto del título
- Texto descriptivo
- Respuestas sugeridas y acciones sugeridas (máximo 4)
Cada uno de estos campos es opcional, pero se debe incluir al menos uno de los campos del 1 al 3 en la tarjeta enriquecida.
Se pueden enviar varias tarjetas juntas en un carrusel de desplazamiento horizontal.
Ten en cuenta que la carga útil total de una tarjeta enriquecida es de 250 KB.
Para obtener todos los detalles técnicos, consulta la documentación sobre las tarjetas enriquecidas.
Altura de la tarjeta
Las tarjetas enriquecidas se expanden verticalmente para adaptarse a su contenido. Tienen una altura mínima de 112 dp y una altura máxima de 344 dp. Si el contenido de la tarjeta no es lo suficientemente grande como para ocupar la altura mínima, la tarjeta se expande y ocupa la altura adicional con espacios en blanco.
El contenido multimedia de las tarjetas enriquecidas debe ajustarse a una de las siguientes tres alturas:
- Pequeña: 112 dp
- Mediano: 168 dp
- Grande: 264 dp
Si el contenido multimedia no se ajusta a las dimensiones de la tarjeta según la altura seleccionada, la vista previa del contenido multimedia se elige acercando y recortando el contenido multimedia.
Ejemplo
En el siguiente código, se envía una tarjeta enriquecida con una imagen y respuestas sugeridas. Para conocer las opciones de formato y valor, consulta RichCard.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "standaloneCard": { "thumbnailImageAlignment": "RIGHT", "cardOrientation": "VERTICAL", "cardContent": { "title": "Hello, world!", "description": "RBM is awesome!", "media": { "height": "TALL", "contentInfo":{ "fileUrl": "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif", "forceRefresh": false } }, "suggestions": [ { "reply": { "text": "Suggestion #1", "postbackData": "suggestion_1" } }, { "reply": { "text": "Suggestion #2", "postbackData": "suggestion_2" } } ] } } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Suggested replies to be used in the card let suggestions = [ { reply: { 'text': 'Suggestion #1', 'postbackData': 'suggestion_1', }, }, { reply: { 'text': 'Suggestion #2', 'postbackData': 'suggestion_2', }, }, ]; // Image to be displayed by the card let imageUrl = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; // Definition of the card parameters let params = { messageText: 'Hello, world!', messageDescription: 'RBM is awesome!', msisdn: '+12223334444', suggestions: suggestions, imageUrl: imageUrl, height: 'TALL', }; // Send rich card to device rbmApiHelper.sendRichCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.StandaloneCard; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); // Create suggestions for chip list List<Suggestion> suggestions = new ArrayList<Suggestion>(); suggestions.add( new SuggestionHelper("Suggestion #1", "suggestion_1").getSuggestedReply()); suggestions.add( new SuggestionHelper("Suggestion #2", "suggestion_2").getSuggestedReply()); String imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create a standalone rich card to send to the user StandaloneCard standaloneCard = rbmApiHelper.createStandaloneCard( "Hello, world!", "RBM is awesome!", imageUrl, MediaHeight.MEDIUM, CardOrientation.VERTICAL, suggestions ); rbmApiHelper.sendStandaloneCard(standaloneCard, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Suggested replies to be used in the card suggestions = [ messages.SuggestedReply('Suggestion #1', 'reply:suggestion_1'), messages.SuggestedReply('Suggestion #2', 'reply:suggestion_2') ] # Image to be displayed by the card image_url = 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif'; # Define rich card structure rich_card = messages.StandaloneCard('VERTICAL', 'Hello, world!', 'RBM is awesome!', suggestions, image_url, None, None, 'MEDIUM') # Append rich card and send to the user cluster = messages.MessageCluster().append_message(rich_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); List<Suggestion> suggestions = new List<Suggestion> { // Create suggestion chips new SuggestionHelper("Suggestion #1", "suggestion_1").SuggestedReply(), new SuggestionHelper("Suggestion #2", "suggestion_2").SuggestedReply() }; string imageUrl = "http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif"; // Create rich card with suggestions StandaloneCard standaloneCard = rbmApiHelper.CreateStandaloneCard( "Hello, world!", "RBM is awesome", imageUrl, MediaHeight.TALL, CardOrientation.VERTICAL, suggestions ); // Send rich card to user rbmApiHelper.SendStandaloneCard(standaloneCard, "+12223334444");
Carruseles de tarjeta enriquecida
Los carruseles encadenan varias tarjetas enriquecidas, lo que permite que los usuarios comparen elementos y reaccionen a cada uno de forma individual.
Los carruseles pueden contener un mínimo de dos y un máximo de diez tarjetas enriquecidas. Las tarjetas enriquecidas dentro de los carruseles deben cumplir con los requisitos generales de contenido y altura de las tarjetas enriquecidas, como se describe en la documentación de tarjetas enriquecidas. Para obtener más información sobre el diseño y las especificaciones del carrusel, consulta la documentación de Carrusel.
Ejemplo
El siguiente código envía un carrusel de tarjetas enriquecidas. Para conocer las opciones de formato y valor,
consulta RichCard.
cURL
curl -X POST "https://REGION-rcsbusinessmessaging.googleapis.com/v1/phones/PHONE_NUMBER/agentMessages?messageId=MESSAGE_ID&agentId=AGENT_ID" \ -H "Content-Type: application/json" \ -H "User-Agent: curl/rcs-business-messaging" \ -H "`oauth2l header --json PATH_TO_SERVICE_ACCOUNT_KEY rcsbusinessmessaging`" \ -d '{ "contentMessage": { "richCard": { "carouselCard": { "cardWidth": "MEDIUM", "cardContents": [ { "title": "Card #1", "description": "The description for card #1", "suggestions": [ { "reply": { "text": "Card #1", "postbackData": "card_1" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg", "forceRefresh": false } } }, { "title": "Card #2", "description": "The description for card #2", "suggestions": [ { "reply": { "text": "Card #2", "postbackData": "card_2" } } ], "media": { "height": "MEDIUM", "contentInfo": { "fileUrl": "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg", "forceRefresh": false } } } ] } } } }'
Node.js
// Reference to RBM API helper const rbmApiHelper = require('@google/rcsbusinessmessaging'); // Images for the carousel cards let card1Image = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; let card2Image = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; // Define the card contents for a carousel with two cards, each with one suggested reply let cardContents = [ { title: 'Card #1', description: 'The description for card #1', suggestions: [ { reply: { text: 'Card #1', postbackData: 'card_1', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card1Image, forceRefresh: false, }, }, }, { title: 'Card #2', description: 'The description for card #2', suggestions: [ { reply: { text: 'Card #2', postbackData: 'card_2', } } ], media: { height: 'MEDIUM', contentInfo: { fileUrl: card2Image, forceRefresh: false, }, }, }, ]; // Definition of carousel card let params = { msisdn: '+12223334444', cardContents: cardContents, }; // Send the device the carousel card defined above rbmApiHelper.sendCarouselCard(params, function(response) { console.log(response); });
Java
import com.google.api.services.rcsbusinessmessaging.v1.model.CardContent; import com.google.api.services.rcsbusinessmessaging.v1.model.Suggestion; import com.google.rbm.cards.CardOrientation; import com.google.rbm.cards.CardWidth; import com.google.rbm.cards.MediaHeight; import com.google.rbm.RbmApiHelper; import com.google.rbm.SuggestionHelper; … try { // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(); List cardContents = new ArrayList(); // Images for the carousel cards String card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; // Create suggestions for first carousel card List card1Suggestions = new ArrayList(); card1Suggestions.add( new SuggestionHelper("Card #1", "card_1")); cardContents.add( new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, card1Suggestions) .getCardContent(MediaHeight.SHORT) ); // Images for the carousel cards String card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Create suggestions for second carousel card List card2Suggestions = new ArrayList(); card2Suggestions.add( new SuggestionHelper("Card #2", "card_2")); cardContents.add( new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, card2Suggestions) .getCardContent(MediaHeight.SHORT) ); // Send the carousel to the user rbmApiHelper.sendCarouselCards(cardContents, CardWidth.MEDIUM, "+12223334444"); } catch(Exception e) { e.printStackTrace(); }
Python
# Reference to RBM Python client helper and messaging object structure from rcs_business_messaging import rbm_service from rcs_business_messaging import messages # Images for the carousel cards card_image_1 = 'https://storage.googleapis.com/welcome-bot-sample-images/200.jpg'; card_image_2 = 'https://storage.googleapis.com/welcome-bot-sample-images/201.jpg'; # Suggested replies to be used in the cards suggestions1 = [ messages.SuggestedReply('Card #1', 'reply:card_1') ] suggestions2 = [ messages.SuggestedReply('Card #2', 'reply:card_2') ] # Define the card contents for a carousel with two cards, # each with one suggested reply card_contents = [] card_contents.append(messages.CardContent('Card #1', 'The description for card #1', card_image_1, 'MEDIUM', suggestions1)) card_contents.append(messages.CardContent('Card #2', 'The description for card #2', card_image_2, 'MEDIUM', suggestions2)) # Send the device the carousel card defined above carousel_card = messages.CarouselCard('MEDIUM', card_contents) cluster = messages.MessageCluster().append_message(carousel_card) cluster.send_to_msisdn('+12223334444')
C#
using Google.Apis.RCSBusinessMessaging.v1.Data; using RCSBusinessMessaging; using RCSBusinessMessaging.Cards; … // Create an instance of the RBM API helper RbmApiHelper rbmApiHelper = new RbmApiHelper(credentialsFileLocation, projectId); // Image references to be used in the carousel cards string card1Image = "https://storage.googleapis.com/welcome-bot-sample-images/200.jpg"; string card2Image = "https://storage.googleapis.com/welcome-bot-sample-images/201.jpg"; // Suggestion chip lists to be used in carousel cards List<Suggestion> suggestions1 = new List<Suggestion> { new SuggestionHelper("Card #1", "card_1").SuggestedReply() }; List<Suggestion> suggestions2 = new List<Suggestion> { new SuggestionHelper("Card #2", "card_2").SuggestedReply() }; // Create the card content for the carousel List<CardContent> cardContents = new List<CardContent> { // Add items as card content new StandaloneCardHelper( "Card #1", "The description for card #1", card1Image, suggestions1).GetCardContent(), new StandaloneCardHelper( "Card #2", "The description for card #2", card2Image, suggestions2).GetCardContent() }; // Send the carousel to the user rbmApiHelper.SendCarouselCards(cardContents, CardWidth.MEDIUM, msisdn);