Integration API for sending RCS (Rich Communication Services) messages from your applications through https requests.
In your user account you will find the API User and the API Token; both are required to make the REST API requests to the API functions. For security reasons, requests must be made using POST and the secure HTTPS protocol.
To use Basic Authentication you must include a header in your requests of the type: Authorization: Basic Base64StringAPI where Base64StringAPI is the Base64 encoding of the string APIUser:APIToken. You can find your API User and API Token in your user account under Your Data -> Configure Account.
To generate the Base64-encoded string, simply build the string APIUser:APIToken and encode it in base64 using any base64encode function.
Empty connections: Please note that a repeatedly failed connection will be treated by the system as spam and may end up temporarily blocking the connection.
It is advisable to avoid repeated connections with incorrect data, or fast 'empty' connections (without actually sending anything) using the same data just to obtain the number of credits or the same report.
To obtain reports optimally in real time, we recommend configuring the API in your panel to receive them in a script on your website.
Request response:
Most functions have a parameter called 'Resp'. This parameter defines the format of the response that will be returned. It can be TXT, JSON, XML or undefined.
We always recommend setting this parameter because, for backward compatibility with previous API versions, all functions respond by default (if this parameter is not set) the way they did in older versions. Those older API-version results omit some of the variables included in this API version, which we consider important to ease integration and account information.
The included examples always assume you have set this parameter. If you are working directly with API version >= 5, we will assume you have set the parameter in every request.
RCS Agent:
Before you can use this API, you must have registered and validated your RCS Agent with your assigned account manager. The RCS Agent is the verified identity from which messages will be sent, including the company name, logo and description.
This allows the system to send RCS messages correctly identified and enriched to the recipients. Please note that the recipient must have an RCS-compatible device and carrier in order to receive them; otherwise the system can perform a fallback to SMS if it is configured.
Recommended workflow:
The recommended workflow, being both the simplest and the most professional, is as follows:
- PROCESS 1: Sending RCS: Described in the EnviarRCS function of this document.
- PROCESS 2: Automatic reception of reports on your website (process described in the 'Reception of delivery reports' section).
HTTP Basic authentication. Use your API User as the username and your API Token as the password (you will find them in your panel, under Your Data → Configure Account). The resulting header is Authorization: Basic base64(APIUser:APIToken). Most HTTP libraries build it automatically (curl -u, requests auth=, Ruby's basic_auth, etc.) without needing to encode the base64 by hand.
basicFunction for sending RCS messages from applications. Definition of the required parameters.
NOTE: Check the real-time report reception section if you want to receive the status of the messages and the recipient's interactions in real time in a script on your website.
| Agente | string Example: Agente=my-rcs-agent Identifier of the RCS Agent from which the send is made. If you have a single agent configured in your account, you can omit this parameter. |
| Plantilla required | string Example: Plantilla=1234567 The Id of the RCS template created in the user panel. This is a required parameter. Variables inside the template must be of the form ###Variable###, which are then personalized per recipient. |
| Destinatarios required | Array of arrays Example: Destinatarios=[{"Nombre":"Pedro Pérez","Telefono":"34600000001","Variables":[{"Nombre":"Reason","Valor":"Verification"},{"Nombre":"Code","Valor":"847291"}]}] JSON array with the recipients of the RCS message. You can add variables if you want to personalize the message per recipient. For example: |
| Fecha | string Example: Fecha=2022-05-01 15:10 Date on which the send is scheduled; the message will be sent on that date. Default "", which means send immediately. Format Year-Month-day hour:minute. The time reference is CET/CEST (Spain time zone). |
| Intervaloprohibido | Array of arrays Example: Intervaloprohibido=[{"HoraInicio":"22:00","HoraFin":"9:00","Accion":"1"}] JSON array with the start and end times of the forbidden sending interval. For example: |
| Referenciausuario | string Example: Referenciausuario=Your reference Parameter used as a reference for the whole campaign on the user side. If you choose to receive the report at a URL, you will receive this parameter in the send result, along with the reference of each recipient if you provided it in the recipients array. |
| Report | string Enum: 0 1 Example: Report=0 If you want to receive reports in a script on your website (by enabling the API configuration in your user panel), set this to 1. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Type of response to return as the result of the call.
|
Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.
| Agente | string |
| Plantilla required | string |
| Destinatarios required | Array of any |
| Fecha | string |
| Intervaloprohibido | Array of any |
| Referenciausuario | string |
| Report | string |
| Resp | string |
| Res required | integer <int32> Response of the requested function
|
| Error | string In the case of Res -3, you will get a descriptive error of the problem in this parameter. |
| idEnvio | integer Campaign identifier, equivalent to the idCampaign received in the report. |
| Destinatarios | integer Number of recipients processed. |
| Enviados | Array of arrays Recipient data in an array to which idMensaje is added for each recipient. The idMensaje is the message identifier. It serves, for example, as an identifier to obtain the report of the sent message. |
| NoEnviados | Array of arrays Erroneous or not-sent recipients. |
| Duplicados | integer Number of recipients not sent because they were duplicated. |
{- "Agente": "my-rcs-agent",
- "Plantilla": "1234567",
- "Destinatarios": "[{\"Nombre\":\"Pedro Pérez\",\"Telefono\":\"34600000001\",\"Variables\":[{\"Nombre\":\"Reason\",\"Valor\":\"Verification\"},{\"Nombre\":\"Code\",\"Valor\":\"847291\"}]}]",
- "Fecha": "2022-05-01 15:10",
- "Intervaloprohibido": "[{\"HoraInicio\":\"22:00\",\"HoraFin\":\"9:00\",\"Accion\":\"1\"}]",
- "Referenciausuario": "Your reference",
- "Report": "0",
- "Resp": "JSON"
}[- {
- "Res": "10",
- "Error": "Falta parámetro obligatorio",
- "idEnvio": "1228853777",
- "Destinatarios": "2",
- "Enviados": "[{\"Telefono\": \"34600000001\",\"idMensaje\": \"108366478\"}]",
- "NoEnviados": "[{\"Nombre\": \"Ana Gonzalez\",\"Telefono\": \"34600000002\"}]",
- "Duplicados": "0"
}
]Returns all the RCS templates (non-certified) configured in your account, as an idPlantilla => Nombre object. Use the idPlantilla obtained as the PLANTILLA parameter in the EnviarRCS function.
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Type of response to return as the result of the call.
|
Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.
| Resp | string |
| Res required | integer <int32> Response of the requested function
|
| Total | integer Number of RCS templates returned. |
| Plantillas | object Object with all the non-certified RCS templates of the account, in |
{- "Resp": "JSON"
}[- {
- "Res": "1",
- "Total": "3",
- "Plantillas": "{\"1234567\":\"Customer welcome\",\"1234568\":\"Shipping notice\"}"
}
]Given the identifier of an RCS template, returns the variables detected in the template along with the type of each one. Use these variable names in the Variables array of each recipient when calling EnviarRCS.
| Plantilla required | string Example: Plantilla=1234567 The Id of the RCS template created in the user panel. This is a required parameter. |
| Resp | string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Type of response to return as the result of the call.
|
Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.
| Plantilla required | string |
| Resp | string |
| Res required | integer <int32> Response of the requested function
|
| Nombre | string Name of the RCS template. |
| Total | integer Number of variables detected in the template. |
| Variables | Array of arrays Array with the template variables. Each element includes |
{- "Plantilla": "1234567",
- "Resp": "JSON"
}[- {
- "Res": "1",
- "Nombre": "Customer welcome",
- "Total": "2",
- "Variables": "[{\"Nombre\":\"Destinatario\",\"Tipo\":\"DESTINATARIO\"},{\"Nombre\":\"Importe\",\"Tipo\":\"TEXTO\"}]"
}
]REAL-TIME RECEPTION OF DELIVERY STATUSES IN A SCRIPT ON YOUR SERVER.
By enabling the option to receive reports in real time in a script on your server from your user panel, you will receive a POST request with the indicated format every time each sent message changes status.
You can configure the requests to be received with basic authentication and in JSON or FORM-DATA format.
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 Type of report you are receiving (the goal is to distinguish between the reports of the different services). The services referred to in this specification may receive | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado required | integer Status of the sent RCS message. The possible statuses are:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Agente required | string Identifier of the RCS agent used in the send. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Destinatario required | string Phone number of the recipient the report refers to, in international format. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| RefCampaign required | string Generic reference of the campaign. It is the generic reference you provided in the send. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| RefMensaje required | string Specific reference of the recipient. It is the reference you provided in the send for this recipient. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Fecha required | string Report date | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| idCampaign required | integer Unique identifier received as a response in the send function (idEnvio received in the send function). | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| idMensaje required | integer Unique identifier received as a response in the send function (idMensaje received in the send function). |
{- "Servicio": "RCS",
- "Estado": "11",
- "Agente": "my-rcs-agent",
- "Destinatario": "34600000001",
- "RefCampaign": "12333-4545-23233",
- "RefMensaje": "36578294H",
- "Fecha": "2020-12-03 11:14:24",
- "idCampaign": "10573758",
- "idMensaje": "33434444443"
}