API de integración de envío de mensajes WHATSAPP BUSINESS 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 ralizarse 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.
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 mensaje Whatsapp : Descrito en la función EnviarWHATSAPP de este documento.
- PROCESO 2: Recepción automática de reports en su web (proceso descrito en el la sección 'Recepción de reports de entrega'.
Función de envío de mensajes Whatsapp desde aplicaciones. Definición de parámetros necesarios.
ATENCIÓN: Debe tener activada la cuenta whatsapp en su panel de usuario. Tambié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.
| Destinatarios required | Array of strings |
| Tipomensaje required | string Enum: "PLANTILLA" "TEXTO" "IMAGEN" "DOCUMENTO" "UBICACION" "SOLICITARUBICACION" "LISTA" "BOTONESRESPUESTA" "REACCION" "BOTONESCTA" Example: Tipomensaje=[{"Telefono":"34600000001","Nombre":"Pedro Pérez","Email":"destinatario@eldominio.com"}] Tipo de mensaje a enviar. Una vez recibas un mensaje de un cliente o éste interactúe con uno de tus mensajes (por ejemplo pulsando un botón del mensaje de la plantilla que le has enviado) se abrirá una ventana de 24 horas en las que podrás enviarle a ese destinatario cualquier tipo de mensaje. Fuera de esa ventana de 24 horas sólo podrás enviar mensajes de tipo Plantillas.
Como mínimo se debe indicar el teléfono de cada destinatario, también puedes incluir el idMensajeRespondido si el mensaje es respuesta directa a uno que hayas recibido. En determinados tipos de mensajes como Reaccion es imperativo indicar el parámetro idMensajeRespondido por destinatario ya que se trata de una reacción directa a un mensaje recibido. Las Variables adicionales (además del Teléfono y las variables que incluyas si quieres personalizar el parámetro DatosMensaje) a incluir por destinatario dependen del tipo de mensaje. ATENCIÓN: Para enviar emojos (por ejemplo en el tipo de mensaje "REACCION" o en cualquier parte del texto de otros tipos de mensajes, puedes haceerlo directamente con el emoji 😃o mediante códigos UTF-16 , por ejemplo: \uD83D\uDE01
|
| Datosmensaje | Array of arrays Example: Datosmensaje={"Plantilla":"Mi Plantilla"} Array JSON con los datos necesarios para cada tipo de mensaje del whatsapp
|
| 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). |
| 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 usuario. |
| Report | integer Example: Report=0 Si desea recibir reports en un script de su web (activando en panel de usuario la configuración API). 1 para Sí, 0 para No. Por defecto 0. |
| Siguientecanal | Array of strings |
| Fixutf8 | integer |
| 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. |
| idMensaje | integer Identificador del mensaje enviado. |
| Cred | double Créditos que restan en la cuenta de usuario tras el envío. |
| Enviados | integer Número de mensajes efectivamente enviados. |
| NoEnviados | integer Número de destinatarios erróneos/no enviados. |
curl --location --request POST 'https://api.mensatek.com/v7/EnviarWHATSAPP' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Destinatarios=""' \ --form 'Tipomensaje="[{\"Telefono\":\"34600000001\",\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\"}]"' \
[- {
- "Res": "10",
- "Error": "Falta parámetro obligatorio",
- "idMensaje": "123456789",
- "Cred": "12000",
- "Enviados": "2",
- "NoEnviados": "0"
}
]Función que permite poner el estado escribiendo en Whatsapp, de esta forma , mientras contestas, el destinatario verá que estas escribiendo.
| Idmensaje required | integer Example: Idmensaje=1288177432 Identificador del mensaje al que estás respondiendo o vas a responder. El IdMensaje es el identificador que obtienes en el webhook de recepción de mensajes |
| Telefono required | string Example: Telefono=34600000000 Teéfon del que ha recibido el mensaje y al que estás respondiendo. |
| 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. |
| Cred | double Créditos que hay en la cuenta |
curl --location --request POST 'https://api.mensatek.com/v7/TypingWHATSAPP' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Idmensaje="1288177432"' \ --form 'Telefono="34600000000"' \
[- {
- "Res": "1",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Función que permite descargar ficheros de imagen, audio, PDFs, etc... recibidos desde tus clientes.
| Idmensaje required | integer Example: Idmensaje=1288177432 Identificador del mensaje en el que has recibido el fichero o multimedia |
| Telefono required | string Example: Telefono=34600000000 Teéfon del que ha recibido el mensaje. Debes incluir el prefijo. |
| 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. |
| Cred | double Créditos que hay en la cuenta |
curl --location --request POST 'https://api.mensatek.com/v7/DescargarFicheroWHATSAPP' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Idmensaje="1288177432"' \ --form 'Telefono="34600000000"' \
[- {
- "Res": "1",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Función que permite cambiar el estado de tu cuenta en whatspp. Debes tener en cuenta que el cambio no es automático. Puede tardar segundos en validarse en Meta o varios minutos si no pasa la primera validación de Meta/Facebook.
| Estado required | string Example: Estado=Estoy usando Whatsapp Business con Mensatek Nuevo estado de tu cuenta de whatsapp. Hasta 1024 caracteres. |
| 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. |
| Cred | double Créditos que hay en la cuenta |
curl --location --request POST 'https://api.mensatek.com/v7/CambiarEstadoWHATSAPP' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ --form 'Estado="Estoy usando Whatsapp Business con Mensatek"' \
[- {
- "Res": "1",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]Devuelve el listado de plantillas (message templates) de tu cuenta de WhatsApp Business, indexadas por idPlantilla. Para cada plantilla se devuelve su nombre, idioma, categoría, estado actual en Meta (APPROVED, PENDING, REJECTED, DISABLED, PAUSED, ...) y un indicador Verificada que vale 1 cuando el estado es APPROVED (es decir, la plantilla está aprobada por Meta y puede usarse para enviar mensajes a tus destinatarios).
Esta función es el primer paso del flujo para enviar un mensaje de tipo Plantilla por API: con el idPlantilla que aquí obtienes puedes consultar después las variables esperadas mediante la función GetVariablesPlantillaWhatsapp, y luego invocar EnviarWHATSAPP con TIPOMENSAJE=Plantilla pasando el nombre de la plantilla en DATOSMENSAJE.PLANTILLA y las variables en DESTINATARIOS.
| 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 <int32> Número total de plantillas devueltas en el parámetro Plantillas. |
| Plantillas | object Objeto cuyas claves son los idPlantilla de tu cuenta y cada valor un objeto con los siguientes campos:
|
| Error | string En caso de Res negativo, obtendrá un error descriptivo del problema en este parámetro. |
| Cred | double Créditos que hay en la cuenta |
curl --location --request POST 'https://api.mensatek.com/v7/GetPlantillasWHATSAPP' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \
[- {
- "Res": "1",
- "Total": "3",
- "Plantillas": "{\n\\\"572863982585983\\\": {\n\\\"Nombre\\\": \\\"bienvenida_cliente\\\",\n\\\"Idioma\\\": \\\"es\\\",\n\\\"Categoria\\\": \\\"MARKETING\\\",\n\\\"Estado\\\": \\\"APPROVED\\\",\n\\\"Verificada\\\": 1,\n\\\"FormatoParametros\\\": \\\"POSITIONAL\\\"\n},\n\\\"572863982585984\\\": {\n\\\"Nombre\\\": \\\"recordatorio_cita\\\",\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"
}
]Devuelve las variables que espera una plantilla concreta para poder personalizarse correctamente al enviarse. Recibe como entrada el idPlantilla (tal como lo devuelve GetPlantillasWhatsapp) y devuelve un objeto Variables indexado por número de variable, con el nombre de la variable, dónde aparece dentro de la plantilla (cabecera, cuerpo o botones) y el formato esperado del valor (texto, URL de imagen, URL de documento, etc.).
La variable 1 siempre es el Destinatario (Campo=Telefono, Formato=TELEFONO), correspondiente al teléfono del cliente al que vas a enviar el mensaje. El resto de variables son las que has definido al crear la plantilla en Meta (placeholders {{1}}, {{2}}, ... o {{Nombre}} si usas el formato NAMED) más las variables especiales que Meta exige para cabeceras tipo imagen/documento/vídeo o para botones URL.
Al llamar a EnviarWHATSAPP con TIPOMENSAJE=Plantilla, debes pasar dentro de DESTINATARIOS, para cada destinatario, un valor por cada variable usando el nombre indicado en el campo Campo (preferido) o en Nombre.
| Idplantilla | string Example: Idplantilla=572863982585983 Identificador numérico de la plantilla cuyas variables quieres consultar. Lo obtienes en las claves del objeto Plantillas que devuelve /GetPlantillasWhatsapp. |
| 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
|
| IdPlantilla | string Identificador de la plantilla consultada (el mismo IDPLANTILLA pasado como entrada). |
| Nombre | string Nombre de la plantilla. Es el valor que debes pasar en DATOSMENSAJE.PLANTILLA al llamar a EnviarWHATSAPP. |
| Idioma | string Código de idioma de la plantilla. |
| Categoria | string Categoría de la plantilla en Meta: MARKETING, UTILITY o AUTHENTICATION. |
| Estado | string Estado actual de la plantilla en Meta (APPROVED, PENDING, REJECTED, DISABLED, PAUSED). |
| Verificada | integer <int32> 1 si el estado es APPROVED (la plantilla puede usarse), 0 en cualquier otro caso. |
| FormatoParametros | string POSITIONAL si las variables van por orden ({{1}}, {{2}}, ...) o NAMED si la plantilla usa variables con nombre ({{Nombre}}, {{Producto}}, ...). |
| Total | integer <int32> Número total de variables devueltas en el parámetro Variables (incluyendo la variable 1 "Destinatario"). |
| Variables | object Objeto cuyas claves son el número de variable (1, 2, 3, ...) y cada valor un objeto con los siguientes campos:
|
| Error | string En caso de Res negativo, obtendrá un error descriptivo del problema en este parámetro. |
| Cred | double Créditos que hay en la cuenta |
curl --location --request POST 'https://api.mensatek.com/v7/GetVariablesPlantillaWHATSAPP' \ --header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \
[- {
- "Res": "1",
- "IdPlantilla": "572863982585983",
- "Nombre": "bienvenida_cliente",
- "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\\\": \\\"Valor de ejemplo\\\"\n},\n\\\"3\\\": {\n\\\"Nombre\\\": \\\"IMAGE de la cabecera\\\",\n\\\"Campo\\\": \\\"Variable_Cabecera_image\\\",\n\\\"Donde\\\": \\\"HEADER\\\",\n\\\"Formato\\\": \\\"URL_IMAGEN\\\",\n\\\"Ejemplo\\\": \\\"https://www.tudominio.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.tudominio.com/oferta/REF123\\\"\n}\n}\n",
- "Error": "Falta parámetro obligatorio",
- "Cred": "12000"
}
]ENVÍO EN TIEMPO REAL DE LOS CAMBIOS DE ESTADO DE MENSAJES ENVIADOS Y RECIBIDOS A 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 un mensaje enviado cambie de estado o cuando reciba un mensaje o respuesta a sus mensajes.
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 puede recibir
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Direccion required | string Tipo de report que está recibiendo (el objetivo es distinguir entre los reports de mensajes de entrada y de salirda).
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Estado required | integer Estado del mensaje enviado o recibido. Los estados posibles son:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Telefono required | string Teléfono del destinatario (o del remitente si es un mensaje recibido) al que se refiere el report. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| NombreDestinatario required | string Nombre del perfil de whatsapp al que se envía o del que se ha recibido un mensaje. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Fecha required | string Fecha del report | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| idMensaje required | integer Identificador único recibido como respuesta en la función de envío (idMensaje recibido en la función de envío) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Referencia required | string Referencia del usuario que se envió durante la petición de envío. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Tipo required | string Tipo del mensaje enviado o recibido. Son los tipos de mensaje indicados en la función 'Enviar' | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Mensaje | string Mensaje recibido, sólo disponible en caso de Direccion=INPUT |
{- "Servicio": "WHATSAPP",
- "Direccion": "INPUT",
- "Estado": "8",
- "Telefono": "34600000001",
- "NombreDestinatario": "Pedro Pérez",
- "Fecha": "2020-12-03 11:14:24",
- "idMensaje": "10573758",
- "Referencia": "Su referencia si la indicó",
- "Tipo": "text",
- "Mensaje": "{\"type\":\"text\",\"text\":\"Este es el mensaje que has recibido\"}"
}