RCS

API Envío de RCS (7.0)

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').

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.

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.

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"
         },
      ]
    }
   ]

Plantilla
required
integer
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.

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
integer
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

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. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-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 


curl --location --request POST 'https://api.mensatek.com/v7/EnviarRCS' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Destinatarios="[{\"Nombre\":\"Pedro Pérez\",\"Telefono\":\"34600000001\",\"Variables\":[{\"Nombre\":\"Motivo\",\"Valor\":\"Verificación\"},{\"Nombre\":\"Codigo\",\"Valor\":\"847291\"}]}]"' \ 
--form 'Plantilla="1234567"' \

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. Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA

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.

Estado
required
integer

Estado del mensaje RCS enviado. 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.
Agente
required
string

Identificador del agente RCS utilizado en el envío.

Destinatario
required
string

Número de teléfono del destinatario al que se refiere el report, en formato internacional.

RefCampaign
required
string

Referencia genérica de la campaña. Es la referencia genérica que ha indicado en el envío.

RefMensaje
required
string

Referencia específica del destinatario. Es la referencia que ha indicado en el envío para este destinatario.

Fecha
required
string

Fecha del report

idCampaign
required
integer

Identificador único recibido como respuesta en la función de envío (idEnvio recibido en la función de envío).

idMensaje
required
integer

Identificador único recibido como respuesta en la función de envío (idMensaje recibido en la función de envío).

Request samples

Content type
{
  • "Servicio": "RCS",
  • "Estado": 11,
  • "Agente": "mi-agente-rcs",
  • "Destinatario": 34600000001,
  • "RefCampaign": "12333-4545-23233",
  • "RefMensaje": "36578294H",
  • "Fecha": "2020-12-03 11:14:24",
  • "idCampaign": 10573758,
  • "idMensaje": 33434444443
}