Sugerencias RCS Chips

Las Sugerencias RCS le permiten usar respuestas y acciones sugeridas en sus mensajes RCS. Pueden incluirse en varios tipos de mensajes, como Tarjetas, Carruseles y Mensajes de texto, y se definen en la carga útil JSON de esos mensajes como una matriz de objetos de sugerencia.

Estos objetos de sugerencia pueden ser respuestas sugeridas, acciones sugeridas o una combinación de ambas. La estructura exacta de los objetos varía en función del tipo de sugerencia.

Sugerencias

Las sugerencias son elementos interactivos de la interfaz de usuario que se muestran como botones o "fichas" en las aplicaciones de mensajería RCS compatibles. Cada sugerencia representa una respuesta rápida o una acción que el usuario puede tocar. Estos chips aparecen debajo del cuerpo principal del mensaje y desaparecen cuando el usuario interactúa con ellos o cuando se recibe un nuevo mensaje.

Hay dos tipos de sugerencias:

  • Respuestas sugeridas: Respuestas de usuario predefinidas que desencadenan un mensaje entrante de tipo reply a la URL definida para su Webhook de mensajes entrantes.
  • Acciones sugeridas: Botones que realizan una acción, por ejemplo abrir una URL o llamar a un número, y desencadenan un mensaje entrante de tipo button a la URL definida para su Webhook de mensajes entrantes.

Nota: También puede incluir una matriz de sugerencias en un mensaje de tarjeta enriquecida. Dado que un carrusel es una colección de tarjetas, cada tarjeta de un carrusel puede contener también su propia matriz de sugerencias. Véase Tarjetas ricas y carruseles para más información.

Respuestas sugeridas

Utilice las respuestas sugeridas cuando espere una respuesta que pueda procesarse mediante programación. Cada respuesta incluye:

  • text: Se muestra en el chip.
  • postback_data: Un identificador devuelto en la entrada reply como id parámetro.

Este es un ejemplo de un mensaje RCS de tipo text con dos sugerencias de respuesta:

{
   "to": "447700900000",
   "from": "Vonage",
   "channel": "rcs",
   "message_type": "text",
   "text": "Hello, world!",
   "suggestions": [
       {
           "type": "reply",
           "text": "Suggestion #1",
           "postback_data": "suggestion_1"
       },
       {
           "type": "reply",
           "text": "Suggestion #2",
           "postback_data": "suggestion_2"
       }
   ]
}

Si el destinatario pulsa sobre una de las sugerencias, se enviará un mensaje de entrada del tipo replyen este caso, el valor de id variaría en función del chip de sugerencia seleccionado por el usuario:

{
  "to": "Vonage",
  "from": "447900000000",
  "channel": "rcs",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "timestamp": "2024-02-08T10:12:44Z",
  "message_type": "reply",
  "reply": {
    "id": "suggestion_1",
    "title": "Suggestion #1"
  }
}

Acciones sugeridas

Las acciones sugeridas realizan una función y devuelven datos estructurados a través de un mensaje de botón. Todas las acciones requieren:

  • type: Define el tipo de acción
  • text: Etiqueta chip (máx. 25 caracteres)
  • postback_data: Un identificador devuelto en la entrada button como payload parámetro.

La mayoría de los tipos de acción también requieren uno o más parámetros adicionales para apoyar la acción específica. Algunos tipos también tienen otros parámetros opcionales. Estos parámetros se detallan a continuación en las descripciones de los tipos específicos:

Abrir una URL

Este objeto de acción tiene un type de open_url y tiene las siguientes propiedades adicionales:

  • url: La URL que debe abrirse. Nota: los únicos esquemas permitidos son http:// y https://otros tipos de regímenes como tel, mailtoetc.
  • description: Una descripción opcional de la URL con fines de accesibilidad.
  • url (Cadena): es la URL que se abrirá.

Si se toca este chip de acción, el dispositivo del destinatario abre la URL especificada en el navegador predeterminado del dispositivo o en una aplicación instalada (si hay una aplicación registrada como gestor para el dominio de la URL).

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description"
   }
  ]
 }

Abrir una URL en Webview

Este objeto de acción tiene un type de open_url_in_webview y tiene las siguientes propiedades adicionales:

  • url: La URL que debe abrirse. Nota: los únicos esquemas permitidos son http:// y https://otros tipos de regímenes como tel, mailtoetc.
  • description: Una descripción opcional de la URL con fines de accesibilidad.
  • view_mode: Modo de visualización de la URL en la ventana webview. Puede ser FULL, TALLo HALF.

Si se toca este chip de acción, el dispositivo del destinatario abre la URL especificada dentro de la propia aplicación de mensajería, con el tamaño de la página web dentro de la interfaz de la aplicación determinado por el valor del parámetro view_mode parámetro.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
"message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
  {
     "type": "open_url_in_webview",
     "text": "Open Google",
     "postback_data": "postback_data_1234",
     "url": "https://www.google.com",
     "description": "Accessibility description",
     "view_mode": "FULL"
   }
  ]
 }

Marcar un número

Este objeto de acción tiene un type de dial y tiene las siguientes propiedades adicionales:

  • phone_number (Cadena): es el número de teléfono que debe marcarse. Debe estar en formato E.164, incluir el prefijo del país e ir precedido de un +por ejemplo +447900000000
  • fallback_url (Cadena): se trata de una URL que se abrirá si no es posible que se inicie la acción de marcado.

Si se pulsa este chip de acción, se indicará al destinatario que llame al número de teléfono especificado.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "dial",
     "text": "Call",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/contact/",
     "phone_number": "+15556667777"
   }
 ]
}

Ver una ubicación

Este objeto de acción tiene un type de view_location y tiene las siguientes propiedades adicionales:

  • latitude (Cadena): La latitud en grados. Debe estar en el intervalo [-90,0, +90,0].
  • longitude (Cadena): La longitud en grados. Debe estar en el rango [-180.0, +180.0].
  • pin_label (Cadena): propiedad opcional que añade una etiqueta al pin mostrado en el mapa.
  • fallback_url (Cadena): es una URL que se abrirá si no es posible iniciar la acción de localización de la vista.

Si se toca este chip de acción, el dispositivo del destinatario muestra la ubicación especificada en la aplicación de mapas predeterminada del dispositivo.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "view_location",
     "text": "View map",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/maps/@37.4220188,-122.0844786,15z",
     "latitude": "37.4220188",
     "longitude": "-122.0844786",
     "pin_label": "Googleplex"
   }
 ]
}

Compartir una ubicación

Este objeto de acción tiene un type de share_location y sólo tiene tres parámetros obligatorios: type, texty postback_data.

Si se toca este chip de acción, el dispositivo del destinatario abre el selector de ubicación predeterminado para que el destinatario pueda elegir una ubicación para enviar de vuelta.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
   {
     "type": "share_location",
     "text": "Share your location",
     "postback_data": "postback_data_1234"
   }
 ]
}

Crear un evento del calendario

Este objeto de acción tiene un type de create_calendar_event y tiene las siguientes propiedades adicionales:

  • start_time (Cadena en formato Timestamp): define la hora de inicio del evento. Una marca de tiempo en RFC3339 Formato UTC "Zulu", por ejemplo 2024-06-28T19:00:00Z
  • end_time (Cadena en formato Timestamp): define la hora de finalización del evento. Una marca de tiempo en formato RFC3339 Formato UTC "Zulu", por ejemplo 2024-06-28T19:00:00Z.
  • title (Cadena): define el título del evento.
  • description (Cadena): define la descripción del evento.
  • fallback_url (Cadena): es una URL que se abrirá si no es posible iniciar la acción de crear evento de calendario.

Si se toca este chip de acción, el dispositivo del destinatario abre la aplicación de calendario predeterminada y comienza a crear un nuevo evento de calendario con los datos definidos en el objeto de acción.

{
 "to": "447900000000",
 "from": "Vonage",
 "channel": "rcs",
 "message_type": "text",
 "text": "Hello, world!",
 "suggestions": [
         {
     "type": "create_calendar_event",
     "text": "Save to calendar",
     "postback_data": "postback_data_1234",
     "fallback_url": "https://www.google.com/calendar",
     "start_time": "2020-06-30T19:00:00Z",
     "end_time": "2020-06-30T20:00:00Z",
     "title": "My calendar event",
     "description": "Description of the calendar event"
   }
 ]
}

Fragmentos de código

A continuación se muestra una lista de fragmentos de código para enviar solicitudes de mensajes para diferentes tipos de mensajes:

Lecturas complementarias