Download OpenAPI specification:Download
Integration API for sending WHATSAPP BUSINESS 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.
Recommended workflow:
The recommended workflow, being both the simplest and the most professional, is as follows:
- PROCESS 1: Sending a WhatsApp message: Described in the EnviarWHATSAPP 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 WhatsApp messages from applications. Definition of the required parameters.
NOTE: You must have your WhatsApp account enabled in your user panel. Also 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.
| Destinatarios required | Array of arrays Example: Destinatarios=[{"Telefono":"34600000001","Nombre":"Pedro Pérez","Email":"recipient@thedomain.com"}] JSON array with the WhatsApp recipients (Telefono parameter) and their associated variables if you want to personalize. You can add variables to personalize Header, footer, buttons, etc. per recipient. Only the phone is mandatory, plus the template variables when sending that message type; the other variables are added to personalize other message types and must be included in the message sections as {{Variable}} (for example in the header, body or footer of the message) For example:
At minimum you must provide each recipient phone; you can also include idMensajeRespondido if the message is a direct reply to one you have received. In certain message types such as Reaccion it is mandatory to provide the idMensajeRespondido parameter per recipient, since it is a direct reaction to a received message. The additional Variables (besides Telefono and any variables you include to personalize the DatosMensaje parameter) to include per recipient depend on the message type. NOTE: To send emojis (for example in the "REACCION" message type or anywhere in the text of other message types), you can do it directly with the emoji 😃 or by using UTF-16 codes, for example: \uD83D\uDE01
|
| Tipomensaje required | string Enum: "PLANTILLA" "TEXTO" "IMAGEN" "DOCUMENTO" "UBICACION" "SOLICITARUBICACION" "LISTA" "BOTONESRESPUESTA" "REACCION" "BOTONESCTA" Example: Tipomensaje=Plantilla Type of message to send. Once you receive a message from a customer or they interact with one of your messages (for example by tapping a button on the template message you sent them), a 24-hour window opens during which you can send that recipient any type of message. Outside that 24-hour window you can only send Template-type messages.
|
| Datosmensaje | Array of arrays Example: Datosmensaje={"Plantilla":"My Template"} JSON array with the data required for each WhatsApp message type
|
| 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). |
| 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 user array. |
| Report | integer Example: Report=0 If you want to receive reports in a script on your website (by enabling the API configuration in your user panel). 1 for Yes, 0 for No. Default 0. |
| Siguientecanal | Array of strings |
| Fixutf8 | integer |
| 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.
| Destinatarios required | Array of any |
| Tipomensaje required | string |
| Datosmensaje | Array of any |
| Fecha | string |
| Referenciausuario | string |
| Report | integer |
| Siguientecanal | Array of any |
| Fixutf8 | integer |
| 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. |
| idMensaje | integer Identifier of the sent message. |
| Cred | double Credits remaining in the user account after the send. |
| Enviados | integer Number of messages effectively sent. |
| NoEnviados | integer Number of erroneous/not-sent recipients. |
{- "Destinatarios": "[{\"Telefono\":\"34600000001\",\"Nombre\":\"Pedro Pérez\",\"Email\":\"recipient@thedomain.com\"}]",
- "Tipomensaje": "Plantilla",
- "Datosmensaje": "{\"Plantilla\":\"My Template\"}",
- "Fecha": "2022-05-01 15:10",
- "Referenciausuario": "Your reference",
- "Report": "0",
- "Siguientecanal": [
- null
], - "Fixutf8": 0,
- "Resp": "JSON"
}[- {
- "Res": "10",
- "Error": "Falta parámetro obligatorio",
- "idMensaje": "123456789",
- "Cred": "12000",
- "Enviados": "2",
- "NoEnviados": "0"
}
]Function that lets you set the typing status in WhatsApp; this way, while you reply, the recipient will see that you are typing.
| Idmensaje required | integer Example: Idmensaje=1288177432 Identifier of the message you are replying to or are going to reply to. The IdMensaje is the identifier you obtain in the message reception webhook |
| Telefono required | string Example: Telefono=34600000000 Phone number from which the message was received and which you are replying to. |
| 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.
| Idmensaje required | integer |
| Telefono required | 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. |
| Cred | double Credits available in the account |
{- "Idmensaje": "1288177432",
- "Telefono": "34600000000",
- "Resp": "JSON"
}[- {
- "Res": "1",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Function that lets you download image files, audio, PDFs, etc. received from your customers.
| Idmensaje required | integer Example: Idmensaje=1288177432 Identifier of the message in which you received the file or media |
| Telefono required | string Example: Telefono=34600000000 Phone number from which the message was received. You must include the prefix. |
| 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.
| Idmensaje required | integer |
| Telefono required | 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. |
| Cred | double Credits available in the account |
{- "Idmensaje": "1288177432",
- "Telefono": "34600000000",
- "Resp": "JSON"
}[- {
- "Res": "1",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Function that lets you change the status of your WhatsApp account. Note that the change is not immediate. It may take seconds to be validated in Meta, or several minutes if it does not pass Meta/Facebook's first validation.
| Estado required | string Example: Estado=I'm using WhatsApp Business with Mensatek New status of your WhatsApp account. Up to 1024 characters. |
| 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.
| Estado required | 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. |
| Cred | double Credits available in the account |
{- "Estado": "I'm using WhatsApp Business with Mensatek",
- "Resp": "JSON"
}[- {
- "Res": "1",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Returns the list of templates (message templates) of your WhatsApp Business account, indexed by idPlantilla. For each template it returns its name, language, category, current status in Meta (APPROVED, PENDING, REJECTED, DISABLED, PAUSED, ...) and a Verificada indicator that equals 1 when the status is APPROVED (i.e. the template is approved by Meta and can be used to send messages to your recipients).
This function is the first step of the flow to send a Template-type message via API: with the idPlantilla you obtain here you can then query the expected variables using the GetVariablesPlantillaWhatsapp function, and then call EnviarWHATSAPP with TIPOMENSAJE=Plantilla passing the template name in DATOSMENSAJE.PLANTILLA and the variables in DESTINATARIOS.
| 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 <int32> Total number of templates returned in the Plantillas parameter. |
| Plantillas | object Object whose keys are the idPlantilla of your account and each value an object with the following fields:
|
| Error | string In the case of a negative Res, you will get a descriptive error of the problem in this parameter. |
| Cred | double Credits available in the account |
{- "Resp": "JSON"
}[- {
- "Res": "1",
- "Total": "3",
- "Plantillas": "{\n\\\"572863982585983\\\": {\n\\\"Nombre\\\": \\\"customer_welcome\\\",\n\\\"Idioma\\\": \\\"es\\\",\n\\\"Categoria\\\": \\\"MARKETING\\\",\n\\\"Estado\\\": \\\"APPROVED\\\",\n\\\"Verificada\\\": 1,\n\\\"FormatoParametros\\\": \\\"POSITIONAL\\\"\n},\n\\\"572863982585984\\\": {\n\\\"Nombre\\\": \\\"appointment_reminder\\\",\n\\\"Idioma\\\": \\\"es\\\",\n\\\"Categoria\\\": \\\"UTILITY\\\",\n\\\"Estado\\\": \\\"PENDING\\\",\n\\\"Verificada\\\": 0,\n\\\"FormatoParametros\\\": \\\"POSITIONAL\\\"\n}\n}\n",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Returns the variables that a specific template expects in order to be personalized correctly when sent. It receives the idPlantilla as input (as returned by GetPlantillasWhatsapp) and returns a Variables object indexed by variable number, with the variable name, where it appears within the template (header, body or buttons) and the expected format of the value (text, image URL, document URL, etc.).
Variable 1 is always the Destinatario (Campo=Telefono, Formato=TELEFONO), corresponding to the phone of the customer you are going to send the message to. The rest of the variables are the ones you defined when creating the template in Meta (placeholders {{1}}, {{2}}, ... or {{Nombre}} if you use the NAMED format) plus the special variables that Meta requires for image/document/video headers or for URL buttons.
When calling EnviarWHATSAPP with TIPOMENSAJE=Plantilla, you must pass inside DESTINATARIOS, for each recipient, a value for each variable using the name indicated in the Campo field (preferred) or in Nombre.
| Idplantilla required | string Example: Idplantilla=572863982585983 Numeric identifier of the template whose variables you want to query. You obtain it from the keys of the Plantillas object returned by /GetPlantillasWhatsapp. |
| 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.
| Idplantilla required | string |
| Resp | string |
| Res required | integer <int32> Response of the requested function
|
| IdPlantilla | string Identifier of the queried template (the same IDPLANTILLA passed as input). |
| Nombre | string Name of the template. It is the value you must pass in DATOSMENSAJE.PLANTILLA when calling EnviarWHATSAPP. |
| Idioma | string Language code of the template. |
| Categoria | string Category of the template in Meta: MARKETING, UTILITY or AUTHENTICATION. |
| Estado | string Current status of the template in Meta (APPROVED, PENDING, REJECTED, DISABLED, PAUSED). |
| Verificada | integer <int32> 1 if the status is APPROVED (the template can be used), 0 otherwise. |
| FormatoParametros | string POSITIONAL if the variables go in order ({{1}}, {{2}}, ...) or NAMED if the template uses named variables ({{Nombre}}, {{Producto}}, ...). |
| Total | integer <int32> Total number of variables returned in the Variables parameter (including variable 1 "Destinatario"). |
| Variables | object Object whose keys are the variable number (1, 2, 3, ...) and each value an object with the following fields:
|
| Error | string In the case of a negative Res, you will get a descriptive error of the problem in this parameter. |
| Cred | double Credits available in the account |
{- "Idplantilla": "572863982585983",
- "Resp": "JSON"
}[- {
- "Res": "1",
- "IdPlantilla": "572863982585983",
- "Nombre": "customer_welcome",
- "Idioma": "es",
- "Categoria": "MARKETING",
- "Estado": "APPROVED",
- "Verificada": "1",
- "FormatoParametros": "POSITIONAL",
- "Total": "4",
- "Variables": "{\n\\\"1\\\": {\n\\\"Nombre\\\": \\\"Destinatario\\\",\n\\\"Campo\\\": \\\"Telefono\\\",\n\\\"Donde\\\": \\\"\\\",\n\\\"Formato\\\": \\\"TELEFONO\\\",\n\\\"Ejemplo\\\": \\\"34600000000\\\"\n},\n\\\"2\\\": {\n\\\"Nombre\\\": \\\"Nombre\\\",\n\\\"Campo\\\": \\\"Nombre\\\",\n\\\"Donde\\\": \\\"BODY\\\",\n\\\"Formato\\\": \\\"TEXTO\\\",\n\\\"Ejemplo\\\": \\\"Sample value\\\"\n},\n\\\"3\\\": {\n\\\"Nombre\\\": \\\"Header IMAGE\\\",\n\\\"Campo\\\": \\\"Variable_Cabecera_image\\\",\n\\\"Donde\\\": \\\"HEADER\\\",\n\\\"Formato\\\": \\\"URL_IMAGEN\\\",\n\\\"Ejemplo\\\": \\\"https://www.yourdomain.com/img/banner.jpg\\\"\n},\n\\\"4\\\": {\n\\\"Nombre\\\": \\\"Producto\\\",\n\\\"Campo\\\": \\\"Valor-URL-Boton-0\\\",\n\\\"Donde\\\": \\\"BUTTONS\\\",\n\\\"Formato\\\": \\\"URL\\\",\n\\\"Ejemplo\\\": \\\"https://www.yourdomain.com/offer/REF123\\\"\n}\n}\n",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]REAL-TIME DELIVERY OF STATUS CHANGES OF SENT AND RECEIVED MESSAGES TO 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 a sent message changes status, or when you receive a message or a reply to your messages.
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
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Direccion required | string Type of report you are receiving (the goal is to distinguish between reports of incoming and outgoing messages).
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado required | integer Status of the sent or received message. The possible statuses are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Telefono required | string Phone number of the recipient (or of the sender if it is a received message) the report refers to. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| NombreDestinatario required | string Name of the WhatsApp profile the message is sent to or received from. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Fecha required | string Report date | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| idMensaje required | integer Unique identifier received as a response in the send function (idMensaje received in the send function) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Referencia required | string User reference that was sent during the send request. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Tipo required | string Type of the sent or received message. They are the message types indicated in the 'Send' function | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Mensaje | string Received message, only available when Direccion=INPUT |
{- "Servicio": "WHATSAPP",
- "Direccion": "INPUT",
- "Estado": "8",
- "Telefono": "34600000001",
- "NombreDestinatario": "Pedro Pérez",
- "Fecha": "2020-12-03 11:14:24",
- "idMensaje": "10573758",
- "Referencia": "Your reference if you provided it",
- "Tipo": "text",
- "Mensaje": "{\"type\":\"text\",\"text\":\"This is the message you have received\"}"
}