Mensaje RCS

Esta documentación ofrece una visión general de los tipos de mensajes y acciones que son compatibles con nuestra API de mensajería. Cada tipo se presenta con una descripción y un ejemplo en JSON para facilitar la integración y el uso.

Esta descripción exhaustiva y los ejemplos en JSON ofrecen una visión profunda de las posibilidades de la API RCS. Al utilizar estos diferentes tipos de mensajes y acciones, los desarrolladores pueden crear una experiencia de usuario rica e interactiva que mejora la comunicación entre empresas y clientes.

Estructura del mensaje

Básicamente, cada mensaje puede consistir en un solo tipo de contenido (text, carousel, richcard o file) y opcionalmente contener respuestas sugeridas.

Propiedades

Name
suggestions
Type
array
Optional
Optional
Description
Una lista de sugerencias de respuesta y sugerencias de acción que se muestran como una lista debajo del último mensaje del agente. Máximo 11 sugerencias.
Name
text
Type
string
Union
Description
Un mensaje de texto simple. Solo tiene sentido aquí en combinación con respuestas sugeridas, ya que de lo contrario puede enviar el texto directamente como una cadena simple a nuestra API.
carousel
objectUnion
Un carrusel es una colección de varias Richcards.
Name
richcard
Type
object
Union
Description
Una Richcard es un mensaje enriquecido con Rich Content. Puede contener texto, videos, una ubicación y mucho más. También es posible incluir botones con los que el destinatario puede interactuar directamente, por ejemplo, para confirmar una reserva o realizar una compra.
Name
file
Type
object
Union
Description
Envíe un archivo, como por ejemplo una imagen, un archivo de audio o un documento, al destinatario.

{
    "suggestions": [
    // ...
    ],

    // Es kann nur der folgenden Eigenschaften angegeben werden
    // Entweder...
    "text": "Ihr Code lautet 1234",

    // ...oder...
    "carousel": {
        "width": "SMALL",
        "richcards": [
            {
                // richcard Objekt...
            },
            // ...
        ]
    },

    // ...oder...
    "richcard": {
        "orientation": "horizontal",
        "thumbnailImageAlignment": "right",
        // ...
    },

    // ...oder...
    "file": {
        "fileUrl": "https://acme.inc/images/image.png",
        "thumbnailUrl": "https://acme.inc/images/thumbnail.png",
        "forceRefresh": false
    }
}

Richcard

Name
title
Type
string
Description
Título de la Richcard
Name
description
Type
string
Description
Descripción de la Richcard
Name
orientation
Type
enum
Optional
Optional
Description
Esta propiedad solo debe especificarse al enviar Richcards individuales. Puede contener horizontal o vertical.
Name
thumbnailImageAlignment
Type
enum
Optional
Optional
Description
Esta propiedad solo debe especificarse al enviar Richcards individuales en el diseño horizontal. Puede contener left o right.
Name
file
Type
object
Optional
Optional
Description
Un objeto de archivo.
Name
suggestions
Type
array
Optional
Optional
Description
Una lista de sugerencias de respuesta y sugerencias de acción que se mostrarán en la tarjeta correspondiente. Máximo 4 sugerencias.

{
    "title": "Titel der Richcard",
    "description": "Beschreibung der Richcard",
    "orientation": "horizontal",
    "thumbnailImageAlignment": "left",
    "file": {
        // Dateiobjekt
        // ...
    },
    "suggestions": [
        // Liste vorgeschlagener Antworten
    ]
}

Enviar archivo

Nuestra API almacena automáticamente archivos y miniaturas en caché. Si desea que nuestra API vuelva a cargar la imagen, simplemente cámbiela ligeramente. Podría agregar un parámetro de consulta como ?timestamp=12345 o un hashtag.

Los tipos MIME permitidos son: image/jpeg, image/jpg, image/gif, image/png, video/h263, video/m4v, video/mp4, video/mpeg, video/mpeg4, video/webm

Si el archivo no es parte de una tarjeta enriquecida, sino que se especifica en el elemento raíz, también se permite el tipo MIME application/pdf.

Propiedades

Name
height
Type
enum
Optional
Optional
Description
Solo debe especificarse cuando se utiliza en una tarjeta enriquecida en diseño vertical. Puede ser short, medium o tall.
Name
fileUrl
Type
string
Union
Description
URL accesible públicamente del archivo. La plataforma RBM determina el tipo MIME del archivo a partir del encabezado HTTP Content-Type cuando se recupera el archivo. Tamaño máximo de archivo recomendado de 100 MB.
Name
fileContents
Type
string
Union
Description
Contenido del archivo codificado en base64.
Name
thumbnailUrl
Type
string
Optional
Optional
Union
Description
Solo para archivos de imagen y video. URL de la miniatura. Tamaño máximo de 100 kB.
Name
thumbnailContents
Type
string
Optional
Optional
Union
Description
Solo para archivos de imagen y video. Contenido de la miniatura codificado en base64. Tamaño máximo de 100 kB.

Si no proporciona una miniatura para la vista previa, se mostrará una miniatura de marcador de posición vacía hasta que el dispositivo del usuario descargue el archivo. Dependiendo de la configuración del usuario, el archivo puede no descargarse automáticamente, y el usuario deberá tocar un botón para descargar.

{
    "height": "medium",
    "fileUrl": "https://example.com/bild.jpg",
    "thumbnailUrl": "https://example.com/thumbnail.jpg"
}

Respuestas y acciones

Las sugerencias solo se muestran cuando el mensaje del agente correspondiente es el mensaje más reciente dentro de la conversación (incluyendo mensajes de agentes y mensajes de usuarios). El usuario puede tocar una respuesta sugerida para enviar la respuesta de texto al agente, o tocar una acción sugerida para iniciar una acción propia en el dispositivo.

Propiedades

Name
type
Type
enum
Description
El tipo de respuesta o acción sugerida. Puede tener uno de los siguientes valores:
- reply
- dial
- viewLocation
- createCalendarEvent
- openUrl
- shareLocation
Name
text
Type
string
Description
Texto del botón a mostrar.
Name
postbackData
Type
string
Description
Datos que se devuelven cuando se desencadena una acción.
Name
phoneNumber
Type
string
Optional
Optional
Description
Solo para el tipo dial. El número de teléfono que se debe llamar.
location
objectOptional
Solo para viewLocation. Incluye los datos de la ubicación.
- Name
  latitude
  Type
  string
  Description
  latitude
- Name
  longitude
  Type
  string
  Description
  longitude
- Name
  label
  Type
  string
  Description
  label
calendarEvent
objectOptional
Solo para createCalendarEvent. Incluye los datos del evento.
- Name
  startTime
  Type
  timestamp
  Description
  La hora de inicio del evento. Se aceptan formatos comunes como 19.06.2024 17:23 o 2024-06-19 17:23.
- Name
  endTime
  Type
  timestamp
  Description
  La hora de finalización del evento. Se aceptan formatos comunes como 19.06.2024 17:23 o 2024-06-19 17:23.
- Name
  title
  Type
  string
  Description
  El título del evento del calendario.
- Name
  description
  Type
  string
  Description
  La descripción del evento del calendario.
Name
url
Type
string
Optional
Optional
Description
Solo para el tipo openUrl. La URL que se debe abrir.
Name
webviewMode
Type
string
Optional
Optional
Description
Solo para el tipo openUrl. Puede ser tall, half o full. full abre la URL en vista web a pantalla completa, half ocupa la mitad de la pantalla y tall ocupa dos cuartos de la pantalla.

La propiedad webviewMode actualmente no es compatible con todos los dispositivos. Si no es compatible, la URL se abrirá en un navegador externo.

[
    // Vorgeschlagene Antwort
    {
        "type": "reply",
        "text": "Ja",
        "postbackData": "clicked_yes"
    },

    // Vorgeschlagener Anruf
    {
        "type": "dial",
        "text": "Anrufen",
        "postbackData": "clicked_call_button",
        "phoneNumber": "49176123456789"
    },

    // Standort ansehen
    {
        "type": "viewLocation",
        "text": "Standort anzeigen",
        "postbackData": "clicked_view_location_button",
        "location": {
            "latitude": 54.3233,
            "longitude": 10.1228,
            "label": "Kiel"
        }
    },

    // Kalenderereignis erstellen
    {
        "type": "createCalendarEvent",
        "text": "Termin erstellen",
        "postbackData": "clicked_call_button",
        "calendarEvent": {
            "startTime": "",
            "endTime": "",
            "title": "Ein wichtiger Termin",
            "description": "Wir freuen uns auf Ihren Besuch."
        }
    },

    // URL öffnen
    {
        "type": "openUrl",
        "text": "Öffnen",
        "postbackData": "clicked_url_button",
        "url": "https://www.example.com"
    },

    // Standort teilen
    {
        "type": "shareLocation",
        "text": "Standort teilen",
        "postbackData": "clicked_share_location_button"
    }
]

Ejemplos

Mensaje de texto con respuestas sugeridas

Envía un mensaje de texto simple con tres respuestas sugeridas al destinatario. Los mensajes de texto son los tipos de mensajes más básicos que se pueden usar para la comunicación directa de información, preguntas o instrucciones. Recibirás en el Webhook el valor de postbackData de la respuesta elegida.

Técnicamente, aquí se envían dos mensajes RCS y se cobran en consecuencia.

{
  "text": "Hi there, would you like to click a button?",
  "suggestions": [
    {
      "type": "reply",
      "text": "Yes",
      "postbackData": "clicked_yes"
    },
    {
      "type": "reply",
      "text": "No",
      "postbackData": "clicked_no"
    },
    {
      "type": "reply",
      "text": "I don't know",
      "postbackData": "clicked_dont_know"
    }
  ]
}

Ver vista previa de RCS

Richcard simple con una imagen

Este ejemplo envía una imagen con la acción sugerida de ver la imagen en el navegador. Ten en cuenta que las suggestions aquí están en la Richcard en lugar de en el nivel principal. Si estuvieran en el nivel principal, el mensaje RCS contaría como dos mensajes y sería más costoso.

{
  "richcard": {
    "title": "Dog",
    "description": "Here is the picture of a dog.",
    "orientation": "vertical",
    "file": {
      "height": "tall",
      "fileUrl": "https://picsum.photos/id/237/200/300",
      "thumbnailUrl": "https://picsum.photos/id/237/50"
    },
    "suggestions": [
      {
        "type": "openUrl",
        "text": "Show picture",
        "postbackData": "clicked_url",
        "url": "https://picsum.photos/id/237/800"
      }
    ]
  }
}

Ver vista previa de RCS

Un carrusel vertical

Este ejemplo muestra un carrusel de tres tarjetas individuales y estrechas en un diseño horizontal, cada una con diferentes alturas.

Cada una de las tres tarjetas tiene una acción sugerida. Por razones de espacio, en la primera tarjeta no se muestra completamente el texto de la respuesta sugerida y en la última tarjeta no se muestra la acción sugerida.

{
    "carousel":
    {
        "width": "SMALL",
        "richcards": [
            {
                "title": "Dog",
                "description": "Short picture of a dog.",
                "file":
                {
                    "height": "short",
                    "fileUrl": "https://picsum.photos/id/237/300",
                    "thumbnailUrl": "https://picsum.photos/id/237/50"
                },
                "suggestions": [
                  {
                      "type": "reply",
                      "text": "Yes, this is a dog.",
                      "postbackData": "yes_this_is_a_dog_clicked"
                  }
                ]
            },
             {
                "title": "Dog",
                "description": "Medium picture of a dog.",
                "file":
                {
                    "height": "medium",
                    "fileUrl": "https://picsum.photos/id/237/300",
                    "thumbnailUrl": "https://picsum.photos/id/237/50"
                },
                "suggestions": [
                  {
                      "type": "reply",
                      "text": "Sweet",
                      "postbackData": "sweet_dog_clicked"
                  }
                ]
            },
            {
                "title": "Dog",
                "description": "Tall picture of a dog.",
                "file":
                {
                    "height": "tall",
                    "fileUrl": "https://picsum.photos/id/237/300",
                    "thumbnailUrl": "https://picsum.photos/id/237/50"
                },
                "suggestions": [
                  {
                      "type": "reply",
                      "text": "Yes",
                      "postbackData": "yes_clicked"
                  }
                ]
            }
        ]
    }
}

Ver vista previa de RCS