API Envío de WHATSAPP (7.0)

INTRODUCCION

API de integración de envío de mensajes WHATSAPP BUSINESS desde aplicaciones mediante peticiones https.

AUTENTICACIÓN

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.

A TENER EN CUENTA

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

Enviar Whatsapp

/EnviarWHATSAPP

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.

query Parameters
Destinatarios
required
Array of arrays
Example: Destinatarios=[{"Telefono":"34600000001","Nombre":"Pedro Pérez","Email":"destinatario@eldominio.com"}]

Array JSON con los destinatario del whatsapp (parámetro Teléfono) y sus variables asociadas si desea personalizar. Puede añadir variables si desea personalizar Header, footer, botones, etc.. por destinatario. Sólo es obligatorio el teléfono y las variables de la plantilla en caso de enviar este tipo de mensaje, las demás variables se añaden para peersonalizar otros tipos de mensajes y deben incluirse en las secciones del mensaje como {{Variable}} (por ejemplo el el header, body o footer del mensaje) Por ejemplo:


   [
    {
      "Telefono": "34600000001",
      "Nombre": "Pedro Aicart",
      "Email": "pedro@dominio.com"
    },
    {
      "Telefono": "34600000002",
      "Nombre": "Ana Aguado",
      "Email": "ana@empresa.com"
    }
   ]
  

Tipomensaje
required
string
Enum: "PLANTILLA" "TEXTO" "IMAGEN" "DOCUMENTO" "UBICACION" "SOLICITARUBICACION" "LISTA" "BOTONESRESPUESTA" "REACCION" "BOTONESCTA"
Example: Tipomensaje=Plantilla

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.

Plantilla - Tipo de mensaje Plantilla, debes haber creado en Meta la plantilla correspondiente.
Texto - Mensaje de Texto, puedes incluir variables.
Imagen - Mensaje de Imagen
Documento - Envío de un Documento
Ubicacion - Envío de una ubicación.
SolicitarUbicacion - Solicita la ubicación al destinatario.
Lista - Envía una lista de opciones
BotonesRespuesta - Envío de una lista de botones con respuestas.
Reaccion - Enviar reacción a un mensaje recibido desde tu cliente
BotonesCTA - Envío de un botón CTA (Click to Action)

Datosmensaje
required
Array of arrays
Example: Datosmensaje={"Plantilla":"Mi Plantilla"}

Array JSON con los datos necesarios para cada tipo de mensaje del whatsapp
Plantilla Se deben incluir los siguientes parámetros en DatosMensaje
    Plantilla - Nombre de la plantilla que se desea enviar. Atención: debes incluir en el parámetro destinatarios el valor las variables incluidas en la plantilla para cada destinatario.
Texto - Se deben incluir los siguientes parámetros en DatosMensaje
    Texto - El mensaje de texto, puedes incluir variables del tipo {{Variable}} y recordar enviar en Destinatarios los valores de las variables incluidas en el mensaje.
Imagen - Mensaje de Imagen
    Imagen - URL de la imagen a enviar
    Descripcion - Mensaje de texto que acompaña a la imagen (puede contener variables por destinatario).
Documento - Envío de un Documento
    Documento - URL del documento a enviar
    Descripcion - Mensaje de texto que acompaña al documento (puede contener variables por destinatario).
Ubicacion - Envío de una ubicación.
    Latitud - Latitud de la ubicación
    Longitud - Longitud de la ubicación
    Nombre - Nomnre de la ubicación
    Direccion - Dirección de la ubicación
SolicitarUbicacion - Solicita la ubicación al destinatario.
    Texto - El mensaje de texto a enviar al destinatario para solicitar su ubicación. Ejemplo: Para poder enviarte sugerencias de restaurantes en tu zona necesitamos tu ubicación.
Lista - Envía una lista de opciones
    Header - Cabecera del mensaje
    Body - Cuerpo del mensaje
    Footer - Pie del mensaje
    - En el array Destinatarios se debe incluir un parámetro Lista que sea a su vez un array con "ID", "Titulo" y "Descripcion" por cada elemento de la lista. De esta forma es personalizable la lista por destinatario. ejemplo Lista:[{"ID":"1","Titulo":"Titulo dse la opción","Descripcion":"Descripcion de la opción"},{"ID":"2","Titulo":"Titulo de la opción 2","Descripcion":"Descripcion de la opción 2"}]
BotonesRespuesta - Envío de una lista de botones con respuestas.
    Header - Cabecera del mensaje
    Body - Cuerpo del mensaje
    Footer - Pie del mensaje
    - En el array Destinatarios se debe incluir un parámetro Botones que sea a su vez un array con "ID" y "Valor" por cada Botón. De esta forma es personalizable la lista del botones por destinatario. ejemplo Botones:[{"ID":"1","Valor":"Valor 1"},{"ID":"2","Valor":"Valor 2"}]
Reaccion - Enviar reacción a un mensaje recibido desde tu cliente
    Emoji - Valor del Emoji a enviar como reacción al mensaje recibido.
BotonesCTA - Envío de un botón CTA (Click to Action)
    Header - Cabecera del mensaje
    Body - Cuerpo del mensaje
    Footer - Pie del mensaje
    - En el array Destinatarios se deben incluir dos parámetros por destinatario: BOTON (texto del botón) y URL que es la url a la que se redirigirá al destinatario cuando pulse en el botón.

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 arrays
Idmensajerespondido
integer
Example: Idmensajerespondido=1234567

Si el mensaje es respuesta a uno recibido desde el destinatario, debes indicar aquí el Id que recibiste en ese mensaje

Fixutf8
integer
Resp
string
Enum: "TXT" "JSON" "XML"
Example: Resp=JSON

Tipo de respuesta a mostrar como resultado de la llamada.
ANT - (Obsoleto). Se mantiene por compatibilidad con versiones anteriores
JSON - La respuesta la obtendrá en JSON
XML - La respuesta la obtendrá en XML
TXT - La respuesta la obtendrá en formato Texto

Responses

Response Schema:
Array
Res
required
integer <int32>

Respuesta de la función solicitada
>0 Número de mensajes enviados.
-1 Error de autenticación.
-2 No hay créditos suficientes.
-3 Error en los datos de la llamada. Faltan Parámetros obligatorios. En este caso, obtendrá un parámetro adicional denominado Error con la descripción del error.
-4 No ha configurado Whatsapp Business en su cuenta de usuario.
-5 Error de meta/Facebook al enviar el mensaje.
-6 Error en la Plantilla de whatsapp

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.

Request samples


curl --location --request POST 'https://api.mensatek.com/v7/EnviarWHATSAPP' \ 
--header 'Authorization: Basic BASE64ENCODEdelStringUsuarioAPI:APIToken' \ 
--form 'Destinatarios="[{\"Telefono\":\"34600000001\",\"Nombre\":\"Pedro Pérez\",\"Email\":\"destinatario@eldominio.com\"}]"' \ 
--form 'Tipomensaje="Plantilla"' \ 
--form 'Datosmensaje="{\"Plantilla\":\"Mi Plantilla\"}"' \ 

Response samples

Content type
[
  • {
    }
]

Recepción de reports de entrega y cambios de estado de mensajes whatsapp enviados

https://{SuDominio}/path/de/su/script/de/recepción/de/reports

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

Request Body schema:

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 WHATSAPP Si el servicio se refiere a un report de WHATSAPP

Resultado
required
integer

Estado del mensaje enviado. Los estados posibles son:

ESTADO DESCRIPCION SIGNIFICADO
`8` Recibido El mensaje ha sido recibido.
`9` Mensaje leído Significado: Mensaje recibido y marcado como leído.
`10` Enviado Significado:El mensaje se ha enviado, esperando entrega.
`11` Mensaje Entregado Significado: El mensaje se ha entregado.
`12` El destinatario ha leído el mensaje Significado: El destinatario ha leído el mensaje.
`29` Mensaje Cancelado Significado: El mensaje ha sido cancelado por el usuario antes de su envío.
`50` Rechazado por Facebook Significado: Facebook ha rechazado el mensaje revise el motivo y reintente.
`51` Sin Whatsapp Significado: El destinatario no dispone de whatsapp, no se ha indicado ningún canal alternativo para entregar el mensaje.
`52` Reenviado por otro canal Significado: Se ha reenviado por otro canal porque el destinatario no dispone de whatsapp
`55` No se ha podido enviar. Hay un error en el envío del mensaje.
`56` Sin crédito en Meta. No tienes crédito en Meta. Debes acceder a tu cuenta de Meta y añadir una tarjeta bancaria.
`900` Enviado por SMS Significado: El destinatario no tiene whatsapp y se ha enviado por SMS .
`901` Enviado por RCS Significado: El destinatario no tiene whatsapp y se ha enviado por RCS .
`902` Enviado por VOZ Significado: El destinatario no tiene whatsapp y se ha enviado por VOZ .
`903` Enviado por EMAIL Significado: El destinatario no tiene whatsapp y se ha enviado por EMAIL .
`1000` Entregado a Facebook Significado: El mensaje ha sido aceptado para su entrega por Facebook/Meta.
`1001` Programado Significado: El mensaje Está programado para enviarse más tarde.
`1002` Enviando Significado: El mensaje está siendo enviado.
`1003` Reintentando Significado: Ha habido un problema en destino, el sistema está reintentando.
Destinatario
required
string

Teléfono del destinatario al que se refiere el report.

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.

Request samples

Content type
{
  • "Servicio": "WHATSAPP",
  • "Resultado": 11,
  • "Destinatario": 34600000001,
  • "Fecha": "2020-12-03 11:14:24",
  • "idMensaje": 10573758,
  • "Referencia": "Su referencia si la indicó"
}

Recepción de mensajes recibidos en su cuenta de Whatsapp conectada

https://{SuDominio}/path/de/su/script/para/recibir/reports

RECEPCIÓN EN TIEMPO REAL DE LOS MENSAJES RECIBIDOS POR WHATSAPP EN UN SCRIPT DE SU SERVIDOR. Recibirá una petición POST con el formato indicado cada vez que reciba un mensaje. Puede configurar recibir las peticiones con autenticación básica y en formato JSON o FORM-DATA

Request Body schema:

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/mensaje 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 RECEPCIONWHATSAPP Si el servicio se refiere a un mensaje recibido por WHATSAPP

idMensaje
required
integer

identificación del mensaje (puedes responder indicando este id en idMensajerespondido en la función enviar)

Fecha
required
string

Fecha del mensaje recibido

Telefono
required
string

Teléfono que envía el mensaje

Contacto
required
string

Nombre del perfil del remitente

Cuenta
required
string

Teléfono asociado a la cuenta que recibe el mensaje

TipoMensaje
required
string

Tipo de mensaje recibido

Contenido
required
string

Contenido del mensaje recibido

Request samples

Content type
{
  • "Servicio": "RECEPCIONWHATSAPP",
  • "idMensaje": 122121354432,
  • "Fecha": "2020-12-03 11:14:24",
  • "Telefono": 34600000001,
  • "Contacto": "Pedro",
  • "Cuenta": 34900000007,
  • "TipoMensaje": "text",
  • "Contenido": "Esto es un mensaje"
}