RCS

RCS Sending API (7.0)

Download OpenAPI specification:Download

URL: /contacto.php Terms of Service

INTRODUCTION

Integration API for sending RCS (Rich Communication Services) messages from your applications through https requests.

AUTHENTICATION

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.

IMPORTANT NOTES

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

basicAuth

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.

Security Scheme Type: HTTP
HTTP Authorization Scheme: basic

Send RCS

/EnviarRCS

Function 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.

Authorizations:
basicAuth
query Parameters
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:


                  [
                    {
                        "Nombre": "Pedro Aicart",
                         "Telefono": "34600000001",
                         "Variables": [
                                 {
                                      "Nombre": "Action",
                                       "Valor": "Transfer"
                              },
                               {
                                      "Nombre": "Amount",
                                       "Valor": "10,000"
                              },
                       ]
                     },
                     {
                         "Nombre": "Ana Aguado",
                         "Telefono": "34600000002",
                         "Variables": [
                                 {
                                      "Nombre": "Action",
                                       "Valor": "Refund"
                              },
                               {
                                      "Nombre": "Amount",
                                       "Valor": "127"
                              },
                        ]
                     }
                  ]
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:


                    {
                        "HoraInicio": "22:00",
                         "HoraFin": "8:00",
                         "Accion": "1"
                     },
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.
JSON - The response will be returned in JSON
XML - The response will be returned in XML
TXT - The response will be returned in Text format

Request Body schema:

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

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function


>0 Number of messages sent.
-1 Authentication error.
-2 Not enough credits.
-3 Error in the call data. Required parameters are missing or some template variable was not sent for some recipient (it is checked that ALL the template variables — except Destinatario, which is automatic — are sent in VARIABLES for each recipient). In this case, you will get an additional parameter called Error with the error description, indicating which variable is missing and for which recipient.
-4 Template not found or not valid.
-5 You do not have enough credits.

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.

Request samples

Content type
{
  • "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"
}

Response samples

Content type
[
  • {
    }
]

List RCS templates

/GetPlantillasRCS

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.

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

Type of response to return as the result of the call.
JSON - The response will be returned in JSON
XML - The response will be returned in XML
TXT - The response will be returned in Text format

Request Body schema:

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

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function
1 Success.
-1 Authentication error.
-3 Error in the call data.

Total
integer

Number of RCS templates returned.

Plantillas
object

Object with all the non-certified RCS templates of the account, in idPlantilla => Nombre format.

Request samples

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

Response samples

Content type
[
  • {
    }
]

Variables of an RCS template

/GetVariablesPlantillaRCS

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.

Authorizations:
basicAuth
query Parameters
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.
JSON - The response will be returned in JSON
XML - The response will be returned in XML
TXT - The response will be returned in Text format

Request Body schema:

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

Responses

Response Schema:
Array
Res
required
integer <int32>

Response of the requested function
1 Success.
-1 Authentication error.
-3 Error in the call data. Required parameters are missing.
-4 Template not found or not valid.

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 Nombre and Tipo. The Tipo can be: DESTINATARIO (reserved system variable, filled in with the mobile number), TEXTO (text personalization variable), or QRCODE/IMAGEN/VIDEO/FILE (variable used inside a dynamic resource of that type).

Request samples

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

Response samples

Content type
[
  • {
    }
]

Reception of delivery reports and status changes of sent RCS messages

https://{YourDomain}/path/to/your/report/reception/script

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 or the recipient interacts with it.

You can configure the requests to be received with basic authentication and in JSON or FORM-DATA format.

IMPORTANT - You will receive TWO types of request, both of them with Servicio = RCS:

1) STATUS REPORT - sent on every status change of the message. You can tell it apart because it includes the MessageID field and does NOT include 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":"your-reference"}

2) EVENT REPORT - sent on every interaction of the recipient (delivery, read, button tap, reply). You can tell it apart because it includes the idEvento field.

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

In both requests the numeric status code travels in the Resultado field, using the same status table. The simplest way to integrate is to process Resultado in both of them and use idEvento/TipoEvento only if you are interested in the detail of the interactions.

Authorizations:
basicAuth
Request Body schema:

Parameters received by your script in a POST request, with the settings specified in your user panel under API configuration.

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 RCS if the report refers to an RCS message.

Resultado
required
integer

Status of the sent RCS message. It is received in both types of request (status report and event report). The possible statuses are:

STATUS DESCRIPTION MEANING
`8` Received The RCS message has been received by the recipient's device.
`9` Received and read The RCS message has been received and the recipient has read it.
`10` Sent The RCS message has been sent from the platform.
`11` Delivered The RCS message has been delivered correctly to the recipient's device.
`12` Opened The recipient has opened and read the RCS message.
`50` Carrier error The carrier has rejected the message. Check the agent configuration or the destination number.
`400` Template error The payload sent is not valid or the requested functionality is not supported by the agent or the carrier.
`401` Connection error The agent credentials or token are not valid. Review the agent configuration.
`402` Not allowed on this agent The requested operation is not allowed for the configured agent.
`404` The destination does not have RCS The destination number does not have RCS enabled or is not compatible with this service.
`409` Duplicate at carrier The carrier has detected a duplicate message identifier.
`429` Request limit exceeded The allowed request limit has been exceeded. Reduce the sending frequency.
`500` Carrier failure Internal error at the carrier. Retry the send later.
`502` Upstream error Error in the carrier's upstream system. Retry the send later.
`503` Service temporarily unavailable The carrier service is temporarily out of service.
`504` Carrier timeout The carrier did not respond within the established time limit.
`1000` Delivered to carrier The RCS message has been sent and delivered to the carrier for distribution to the recipient.
`1001` Scheduled The message has been scheduled and will be sent at the indicated time.
`1002` Sending The RCS message is being processed and sent right now.
`1003` Retrying There was a delivery problem; the system is automatically retrying the send.
Fecha
required
string

Date of the report or of the event. It is received in both types of request.

Movil
required
string

Phone number of the recipient the report refers to, without prefix. It is received in both types of request.

Prefijo
required
string

International prefix of the recipient. It is received in both types of request.

Remitente
required
string

Identifier of the RCS agent used in the send. It is received in both types of request.

idMensaje
required
integer

Campaign identifier, received as a response in the send function (idMensaje). It is received in both types of request.

idReport
required
integer

Identifier of the recipient within the campaign, received as a response in the send function (idReport). The pair idMensaje + idReport uniquely identifies each message. It is received in both types of request.

Referencia
required
string

Reference you provided in the send (REFERENCIAUSUARIO parameter). It is received in both types of request.

MessageID
string

Status report only. Identifier of the message at the carrier.

Operador
integer

Status report only. Internal identifier of the recipient's carrier (0 if it could not be determined).

idEvento
integer

Event report only. Unique identifier of the event. Its presence is what tells an event request apart from a status one.

TipoEvento
string

Event report only. Type of interaction:
estado - status change of the message (the numeric code is in Resultado and the detail in Subtipo).
boton - the recipient tapped a button of the template.
respuesta - the recipient replied to the message.

Subtipo
string

Event report only. Textual detail of the event as reported by the carrier. For TipoEvento = estado the usual values are delivered (equivalent to Resultado = 11) and displayed (equivalent to Resultado = 12).

TipoBoton
string

Event report only. Type of the tapped button when TipoEvento = boton. Empty in the rest of the events.

OrdenBoton
integer

Event report only. Position of the tapped button within the template when TipoEvento = boton. 0 in the rest of the events.

Valores
string

Event report only. Content associated with the event: the text of the recipient's reply or the value of the tapped button. Empty in status events.

CreditosEnvio
string

Credits consumed by the WHOLE sending this report belongs to (the one identified by idMensaje), not by this particular recipient. For a single-recipient sending it equals the cost of the message; for a multi-recipient sending it is the total of the sending and the same value is repeated in every recipient's report, so do not add them up. Present in both the status report and the event report.

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": "",
  • "CreditosEnvio": "2.5"
}