RCS

API Envío de RCS (7.0)

Download OpenAPI specification:Download

URL: /contacto.php Terms of Service

INTRODUCCION

API de integración de envío de mensajes RCS (Rich Communication Services) desde aplicaciones mediante peticiones https.

AUTENTICACIÓN

En su cuenta de usuario encontrará el Usuario API y el API Token, ambos son necesarios para realizar las peticiones API REST a las funciones de la API. Las Peticiones, por seguridad deben realizarse en POST y con protocolo HTTPS Seguro.



Para utilizar la Autenticación Básica debe incluir una cabecera en las peticiones del tipo: Authorization: Basic Base64StringAPI donde Base64StringAPI es la codificación en Base64 de la cadena UsuarioAPI:APIToken, puede encontrar su Usuario API y API Token en su cuenta de usuario en Tus Datos -> Configurar Cuenta.



Para generar el string codificado en Base64, simplemente genere el string UsuarioApi:APIToken y codifíquelo en base64 mediante cualquier función base64encode.

A TENER EN CUENTA

Conexiones en vacío: Es importante tener en cuenta que una conexión errónea de forma repetida será tratada por el sistema como spam y podrá llegar a bloquear temporalmente la conexión.

Es conveniente evitar realizar repetidas conexiones con datos erróneos o conexiones rápidas 'en vacío' (sin realizar envíos) con los mismos datos para obtener el número de créditos o el mismo report.

Para obtener reports de forma óptima en tiempo real se recomienda configurar la API en el panel para recibirlos en un script de su web.


Respuesta de las peticiones: La mayoría de las funciones disponen de un parámetro denominado 'Resp'. Este parámetro define el formato de la respuesta que se devolverá. Puede ser TXT, JSON, XML o no definido.

Se recomienda siempre definir este parámetro ya que todas las funciones, por compatibilidad con versiones anteriores de la API, responden por defecto (si no se define este parámetro) tal y como lo hacían en versiones antiguas. En estos resultados de versiones de API anteriores se obvian algunas de las variables que se incluyen en esta versión de la API y que consideramos importantes para facilitar la integración e información de la cuenta.

En los ejemplos incluidos siempre se tiene en cuenta que ha definido el parámetro. Si está trabajando directamente con la API versión >= 5, asumiremos que ha definido el parámetro en todas las peticiones.


Agente RCS: Antes de poder utilizar esta API, debe haber registrado y validado su Agente RCS con su comercial asignado. El Agente RCS es la identidad verificada desde la que se enviarán los mensajes, incluyendo nombre, logo y descripción de la empresa.

Esto permitirá al sistema enviar mensajes RCS correctamente identificados y enriquecidos hacia los destinatarios. Tenga en cuenta que el destinatario debe disponer de un dispositivo y operadora compatibles con RCS para poder recibirlos; en caso contrario el sistema puede realizar un fallback a SMS si está configurado.


Funcionamiento recomendado: El funcionamiento recomendado, por ser el más sencillo y, a la vez, el más profesional es el siguiente:
- PROCESO 1: Envío de RCS: Descrito en la función EnviarRCS de este documento.
- PROCESO 2: Recepción automática de reports en su web (proceso descrito en la sección 'Recepción de reports de entrega').

basicAuth

Autenticación HTTP Basic. Use su Usuario API como usuario y su API Token como contraseña (los encuentra en su panel, en Tus Datos → Configurar Cuenta). El header resultante es Authorization: Basic base64(UsuarioAPI:APIToken). La mayoría de las librerías HTTP lo construyen automáticamente (curl -u, requests auth=, basic_auth de Ruby, etc.) sin necesidad de codificar el base64 a mano.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Enviar RCS

/EnviarRCS

Función de envío de mensajes RCS desde aplicaciones. Definición de parámetros necesarios.

ATENCIÓN: Chequee la sección de recepción de reports en tiempo real si desea recibir el estado de los mensajes y las interacciones del destinatario en tiempo real en un script de su web.

Authorizations:
basicAuth
query Parameters
Agente
string
Example: Agente=mi-agente-rcs

Identificador del Agente RCS desde el que se realiza el envío. Si dispone de un único agente configurado en su cuenta, puede omitir este parámetro.

Plantilla
required
string
Example: Plantilla=1234567

El Id de la plantilla RCS creada en el panel de usuario. Es un parámetro obligatorio. Las variables dentro de la plantilla deben ser del tipo ###Variable### que luego se personalizarán por destinatario.

Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Nombre":"Pedro Pérez","Telefono":"34600000001","Variables":[{"Nombre":"Motivo","Valor":"Verificación"},{"Nombre":"Codigo","Valor":"847291"}]}]

Array JSON con los destinatarios del mensaje RCS. Puede añadir variables si desea personalizar el mensaje por destinatario. Por ejemplo:


                  [
                    {
                        "Nombre": "Pedro Aicart",
                         "Telefono": "34600000001",
                         "Variables": [
                                 {
                                      "Nombre": "Accion",
                                       "Valor": "Transferencia"
                              },
                               {
                                      "Nombre": "Importe",
                                       "Valor": "10.000"
                              },
                       ]
                     },
                     {
                         "Nombre": "Ana Aguado",
                         "Telefono": "34600000002",
                         "Variables": [
                                 {
                                      "Nombre": "Accion",
                                       "Valor": "Devolución"
                              },
                               {
                                      "Nombre": "Importe",
                                       "Valor": "127"
                              },
                        ]
                     }
                  ]
Fecha
string
Example: Fecha=2022-05-01 15:10

Fecha en la que queda programado el envío; el mensaje se enviará en esa fecha. Por defecto "" que significa enviar inmediatamente. Formato Año-Mes-dia hora:minuto. La referencia horaria es CET/CEST (Zona horaria de España).

Intervaloprohibido
Array of arrays
Example: Intervaloprohibido=[{"HoraInicio":"22:00","HoraFin":"9:00","Accion":"1"}]

Array JSON con las horas de inicio y fin del intervalo de envío prohibido. Por ejemplo:


                    {
                        "HoraInicio": "22:00",
                         "HoraFin": "8:00",
                         "Accion": "1"
                     },
Referenciausuario
string
Example: Referenciausuario=Tu referencia

Parámetro que se utiliza como referencia de toda la campaña para el usuario. Si se selecciona recibir el report en una URL, recibirá este parámetro en el resultado del envío y también la referencia de cada uno de los destinatarios si la ha indicado en el array de destinatarios.

Report
string
Enum: 0 1
Example: Report=0

Si desea recibir reports en un script de su web (activando en panel de usuario la configuración API), indique 1.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Agente
string
Plantilla
required
string
Destinatarios
required
Array of any
Fecha
string
Intervaloprohibido
Array of any
Referenciausuario
string
Report
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada


>0 Número de mensajes enviados.
-1 Error de autenticación.
-2 No hay créditos suficientes.
-3 Error en los datos de la llamada. Faltan parámetros obligatorios o alguna variable de la plantilla no se ha enviado para algún destinatario (se comprueba que TODAS las variables de la plantilla — salvo Destinatario, que es automática — se envían en VARIABLES para cada destinatario). En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error, indicando qué variable falta y para qué destinatario.
-4 Plantilla no encontrada o no válida.
-5 No dispone de créditos suficientes.

Error
string

En caso de Res -3, obtendrá un error descriptivo del problema en este parámetro.

idEnvio
integer

Identificador de la campaña, equivalente a idCampaign recibido en el report.

Destinatarios
integer

Número de destinatarios procesados.

Enviados
Array of arrays

Datos de los destinatarios en un array en el que se añade idMensaje por cada destinatario. El idMensaje es el identificador del mensaje. Sirve, por ejemplo, como identificación para obtener el report del mensaje enviado.

NoEnviados
Array of arrays

Destinatarios erróneos o no enviados.

Duplicados
integer

Número de destinatarios no enviados debido a que estaban duplicados.

Request samples

Content type
{
  • "Agente": "mi-agente-rcs",
  • "Plantilla": "1234567",
  • "Destinatarios": "[{\"Nombre\":\"Pedro Pérez\",\"Telefono\":\"34600000001\",\"Variables\":[{\"Nombre\":\"Motivo\",\"Valor\":\"Verificación\"},{\"Nombre\":\"Codigo\",\"Valor\":\"847291\"}]}]",
  • "Fecha": "2022-05-01 15:10",
  • "Intervaloprohibido": "[{\"HoraInicio\":\"22:00\",\"HoraFin\":\"9:00\",\"Accion\":\"1\"}]",
  • "Referenciausuario": "Tu referencia",
  • "Report": "0",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Listar plantillas RCS

/GetPlantillasRCS

Devuelve todas las plantillas RCS (no certificadas) configuradas en su cuenta, en un objeto idPlantilla => Nombre. Utilice el idPlantilla obtenido como parámetro PLANTILLA en la función EnviarRCS.

Authorizations:
basicAuth
query Parameters
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
1 Correcto.
-1 Error de autenticación.
-3 Error en los datos de la llamada.

Total
integer

Número de plantillas RCS devueltas.

Plantillas
object

Objeto con todas las plantillas RCS no certificadas de la cuenta, en formato idPlantilla => Nombre.

Request samples

Content type
{
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Variables de una plantilla RCS

/GetVariablesPlantillaRCS

Dado el identificador de una plantilla RCS, devuelve las variables detectadas en la plantilla junto con el tipo de cada una. Use estos nombres de variable en el array Variables de cada destinatario al llamar a EnviarRCS.

Authorizations:
basicAuth
query Parameters
Plantilla
required
string
Example: Plantilla=1234567

El Id de la plantilla RCS creada en el panel de usuario. Es un parámetro obligatorio.

Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Request Body schema:

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Plantilla
required
string
Resp
string

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
1 Correcto.
-1 Error de autenticación.
-3 Error en los datos de la llamada. Faltan parámetros obligatorios.
-4 Plantilla no encontrada o no válida.

Nombre
string

Nombre de la plantilla RCS.

Total
integer

Número de variables detectadas en la plantilla.

Variables
Array of arrays

Array con las variables de la plantilla. Cada elemento incluye Nombre y Tipo. El Tipo puede ser: DESTINATARIO (variable reservada del sistema, se rellena con el móvil), TEXTO (variable de personalización de texto), o QRCODE/IMAGEN/VIDEO/FILE (variable usada dentro de un recurso dinámico de ese tipo).

Request samples

Content type
{
  • "Plantilla": "1234567",
  • "Resp": "JSON"
}

Response samples

Content type
[
  • {
    }
]

Recepción de reports de entrega y cambios de estado de mensajes RCS enviados

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

RECEPCIÓN EN TIEMPO REAL DE LOS ESTADOS DE ENTREGA EN UN SCRIPT DE SU SERVIDOR.

Activando la opción de recibir los reports en tiempo real en un script en su servidor desde su panel de usuario, recibirá una petición POST con el formato indicado cada vez que cada mensaje enviado cambie de estado o el destinatario interactúe con él.

Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA.

IMPORTANTE - Recibirá DOS tipos de petición, ambas con Servicio = RCS:

1) REPORT DE ESTADO - se envía en cada cambio de estado del mensaje. Se distingue porque incluye el campo MessageID y NO incluye idEvento.

{"Servicio":"RCS","Resultado":"11","Fecha":"2026-07-11 12:49:03","Movil":"34600000001","Prefijo":"34","Remitente":"10002","idMensaje":"7911","idReport":"3497","MessageID":"e092e3e8-bc4b-46ee-98a4-8a3fe2752711","Operador":"0","Referencia":"su-referencia"}

2) REPORT DE EVENTO - se envía en cada interacción del destinatario (entrega, lectura, pulsación de un botón, respuesta). Se distingue porque incluye el campo idEvento.

{"Servicio":"RCS","Resultado":"11","Fecha":"2026-07-11 12:49:03","idMensaje":"7911","idReport":"3497","idEvento":"128","Referencia":"su-referencia","Movil":"34600000001","Prefijo":"34","Remitente":"10002","TipoEvento":"estado","Subtipo":"delivered","TipoBoton":"","OrdenBoton":"0","Valores":""}

En las dos peticiones el código numérico de estado viaja en el campo Resultado, con la misma tabla de estados. La forma más sencilla de integrar es procesar Resultado en las dos y usar idEvento/TipoEvento sólo si le interesa el detalle de las interacciones.

Authorizations:
basicAuth
Request Body schema:

Parámetros recibidos en su script en petición POST con la configuración especificada en su panel de usuario/configuración API.

Servicio
required
string

Tipo de report que está recibiendo (el objetivo es distinguir entre los reports de los diferentes servicios). Los servicios a los que se refiere esta especificación pueden recibir RCS si el report se refiere a un mensaje RCS.

Resultado
required
integer

Estado del mensaje RCS enviado. Se recibe en los dos tipos de petición (report de estado y report de evento). Los estados posibles son:

ESTADO DESCRIPCION SIGNIFICADO
`8` Recibido El mensaje RCS ha sido recibido por el dispositivo del destinatario.
`9` Recibido y leído El mensaje RCS ha sido recibido y el destinatario lo ha leído.
`10` Enviado El mensaje RCS ha sido enviado desde la plataforma.
`11` Entregado El mensaje RCS ha sido entregado correctamente al dispositivo del destinatario.
`12` Abierto El destinatario ha abierto y leído el mensaje RCS.
`50` Error de operadora La operadora ha rechazado el mensaje. Compruebe la configuración del agente o el número de destino.
`400` Error en Plantilla El payload enviado no es válido o la funcionalidad solicitada no está soportada por el agente o la operadora.
`401` Error en Conexión Las credenciales o el token del agente no son válidos. Revise la configuración del agente.
`402` No permitido en este agente La operación solicitada no está permitida para el agente configurado.
`404` El destino no tiene RCS El número de destino no tiene RCS habilitado o no es compatible con este servicio.
`409` Duplicado en operadora La operadora ha detectado un identificador de mensaje duplicado.
`429` Num peticiones excedidas Se ha superado el límite de peticiones permitidas. Reduzca la frecuencia de envío.
`500` Fallo en operadora Error interno en la operadora. Reintente el envío más tarde.
`502` Upstream error Error en el sistema upstream de la operadora. Reintente el envío más tarde.
`503` Servicio temporalmente no disponible El servicio de la operadora está temporalmente fuera de servicio.
`504` Timeout en operadora La operadora no ha respondido en el tiempo límite establecido.
`1000` Entregado a Operadora El mensaje RCS ha sido enviado y entregado a la operadora para su distribución al destinatario.
`1001` Programado El mensaje ha sido programado y se enviará a la hora indicada.
`1002` Enviando El mensaje RCS está siendo procesado y enviado en este momento.
`1003` Reintentando Ha habido un problema en la entrega; el sistema está reintentando el envío automáticamente.
Fecha
required
string

Fecha del report o del evento. Se recibe en los dos tipos de petición.

Movil
required
string

Número de teléfono del destinatario al que se refiere el report, sin prefijo. Se recibe en los dos tipos de petición.

Prefijo
required
string

Prefijo internacional del destinatario. Se recibe en los dos tipos de petición.

Remitente
required
string

Identificador del agente RCS utilizado en el envío. Se recibe en los dos tipos de petición.

idMensaje
required
integer

Identificador de la campaña, recibido como respuesta en la función de envío (idMensaje). Se recibe en los dos tipos de petición.

idReport
required
integer

Identificador del destinatario dentro de la campaña, recibido como respuesta en la función de envío (idReport). El par idMensaje + idReport identifica de forma única cada mensaje. Se recibe en los dos tipos de petición.

Referencia
required
string

Referencia que ha indicado en el envío (parámetro REFERENCIAUSUARIO). Se recibe en los dos tipos de petición.

MessageID
string

Sólo en el report de estado. Identificador del mensaje en la operadora.

Operador
integer

Sólo en el report de estado. Identificador interno de la operadora del destinatario (0 si no se ha podido determinar).

idEvento
integer

Sólo en el report de evento. Identificador único del evento. Su presencia es lo que distingue una petición de evento de una de estado.

TipoEvento
string

Sólo en el report de evento. Tipo de interacción:
estado - cambio de estado del mensaje (el código numérico va en Resultado y el detalle en Subtipo).
boton - el destinatario ha pulsado un botón de la plantilla.
respuesta - el destinatario ha respondido al mensaje.

Subtipo
string

Sólo en el report de evento. Detalle textual del evento tal y como lo reporta la operadora. Para TipoEvento = estado los valores habituales son delivered (equivale a Resultado = 11) y displayed (equivale a Resultado = 12).

TipoBoton
string

Sólo en el report de evento. Tipo del botón pulsado cuando TipoEvento = boton. Vacío en el resto de eventos.

OrdenBoton
integer

Sólo en el report de evento. Posición del botón pulsado dentro de la plantilla cuando TipoEvento = boton. 0 en el resto de eventos.

Valores
string

Sólo en el report de evento. Contenido asociado al evento: el texto de la respuesta del destinatario o el valor del botón pulsado. Vacío en los eventos de estado.

Request samples

Content type
{
  • "Servicio": "RCS",
  • "Resultado": "11",
  • "Fecha": "2026-07-11 12:49:03",
  • "Movil": "600000001",
  • "Prefijo": "34",
  • "Remitente": "10002",
  • "idMensaje": "7911",
  • "idReport": "3497",
  • "Referencia": "36578294H",
  • "MessageID": "e092e3e8-bc4b-46ee-98a4-8a3fe2752711",
  • "Operador": "0",
  • "idEvento": "128",
  • "TipoEvento": "estado",
  • "Subtipo": "delivered",
  • "TipoBoton": "",
  • "OrdenBoton": "0",
  • "Valores": ""
}