API de integración de envío de mensajes RCS (Rich Communication Services) desde aplicaciones mediante peticiones https.
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.
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').
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.
| 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: |
| 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: |
| 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.
|
| Res required | integer <int32> Respuesta de la función solicitada
|
| 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. |
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"' \
[- {
- "Res": "10",
- "Error": "Falta parámetro obligatorio",
- "idEnvio": "1228853777",
- "Destinatarios": "2",
- "Enviados": "[{\"Telefono\": \"34600000001\",\"idMensaje\": \"108366478\"}]",
- "NoEnviados": "[{\"Nombre\": \"Ana Gonzalez\",\"Telefono\": \"34600000002\"}]",
- "Duplicados": "0"
}
]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.
| Resp | string Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
| Res required | integer <int32> Respuesta de la función solicitada
|
| Total | integer Número de plantillas RCS devueltas. |
| Plantillas | object Objeto con todas las plantillas RCS no certificadas de la cuenta, en formato |
curl --location --request POST 'https://api.mensatek.com/v7/GetPlantillasRCS' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \
[- {
- "Res": "1",
- "Total": "3",
- "Plantillas": "{\"1234567\":\"Bienvenida clientes\",\"1234568\":\"Aviso de envío\"}"
}
]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.
| Plantilla | string Example: Plantilla=1234567 El Id de la plantilla RCS creada en el panel de usuario. Es un parámetro obligatorio. |
| Resp | string Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada.
|
| Res required | integer <int32> Respuesta de la función solicitada
|
| 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 |
curl --location --request POST 'https://api.mensatek.com/v7/GetVariablesPlantillaRCS' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \
[- {
- "Res": "1",
- "Nombre": "Bienvenida clientes",
- "Total": "2",
- "Variables": "[{\"Nombre\":\"Destinatario\",\"Tipo\":\"DESTINATARIO\"},{\"Nombre\":\"Importe\",\"Tipo\":\"TEXTO\"}]"
}
]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
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 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado required | integer Estado del mensaje RCS enviado. Los estados posibles son:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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). |
{- "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"
}