Integre sin problemas nuestra API REST de mensajería a través de WhatsApp

Introducción

Este documento proporciona una referencia de todas las funciones disponibles en la API REST para envío de mensajes de texto a través de WhatsApp.

La API le permite integrar su aplicación (cliente) utilizando la arquitectura REST para enviar mensajes.

Para usar el servicio necesitará contar con una cuenta de user key y un account key. Llenando el siguiente formulario Mob Army los generará por usted.

La API REST se utiliza solo para el envío de mensajería unidireccional. Por lo tanto, debe proporcionar un MSISDN válido como número de destino.

Funcionalidades de la API

  • Envío de mensajes de texto sin límite de caracteres.
  • Envío de archivos multimedia.
  • Envío y verificación de códigos de seguridad tipo OTP.
  • Configuración de URL de confirmación (ACK) para confirmación de «entrega» y «lectura» de mensajes enviados.

Header

Todas las solicitudes deben contener los siguientes campos en el header:


 Authorization: Basic YWRtaW46YWRtaW4=
 Content-Type: application/json

Como enviar un mensaje de WhatsApp

API URL: http://my-server:port/v1/mwt/messageEvent

Parámetros

A continuación se muestra una lista de parámetros del request.

ParámetroDescripciónPresencia
receiversCadena de destinatarios (máximo 10) a los que se enviará el mensaje. Por ejemplo: 59172083143 (No use “+” antes del código de país)Obligatorio
templateMensaje a enviar.Obligatorio
user.keyCredencial de usuario asignado al cliente.Obligatorio
account.keyCredencial de la cuenta asignada al cliente.Obligatorio
scheduledEs un timestamp en el formato “2021-08-31T12:10:00.0-04:00″.
Si la fecha no es especifica o es menor a la fecha actual, el sistema asume que el envío es inmediato.		No obligatorio

Request


 {
    "userx": {
        "key": "user key"
    },
    "account": {
        "key": "account key"
    },
    "template": "Mensaje de prueba16 para {name}",
    "scheduled": "2021-08-31T12:10:00.0-04:00",
    "receivers": [
        {
            "name": "Bruce W.",
            "phoneNumber": 59170712345
        },
        {
            "name": "Daniel M.",
            "phoneNumber": 59170754321
        },
        {
            "name": "Sammy T.",
            "phoneNumber": 59170312345
        },
        {
            "name": "Danny B.",
            "phoneNumber": 59177900000
        }
    ]
 }

Response

Si el mensaje se ha enviado correctamente, el código de estado devolverá:

 {
    "uid": 23,
    "userx": {
        "key": "user key"
    },
    "account": {
        "key": "account key"
    },
    "type": "MSG",
    "template": "Mensaje de prueba16 para {name}",
    "filePath": null,
    "fileName": null,
    "scheduled": "2021-08-31T12:10:00.000+00:00",
    "receivers": [
        {
            "uid": 85,
            "phoneNumber": 59170712345,
            "name": "Bruce W."
        },
        {
            "uid": 86,
            "phoneNumber": 59170754321,
            "name": "Espartano M."
        },
        {
            "uid": 87,
            "phoneNumber": 59170312345,
            "name": "Sammy T"
        },
        {
            "uid": 88,
            "phoneNumber": 59177900000,
            "name": "Danny B."
        }
    ]
 }

Si el mensaje no se pudo entregar, devolverá un  mensaje de ERROR en el campo de respuesta.

Como enviar un archivo multimedia por WhatsApp

API URL: http://my-server:port/v1/mwt/fileEvent

Parámetros

A continuación se muestra una lista de parámetros del request.

ParámetroDescripciónPresencia
receiversCadena de destinatarios a los que se enviará el mensaje. Por ejemplo: 59172083143 (No use “+” antes del código de país)Obligatorio
filePathLink HTTP. Ejemplo:

https://mobarmy.dev/wp-content/uploads/2021/02/logotipo_cuadrado.jpg

O un archivo codificado en base64 con mime data, Por ejemplo:

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…

File in form-data input field		Obligatorio
fileNameNombre del archivo a ser enviado. Ejemplo: 1.jpg o archivo.pdfObligatorio
user.keyCredencial de usuario asignado al cliente.Obligatorio
account.keyCredencial de la cuenta asignada al cliente.Obligatorio
scheduledEs un timestamp en el formato “2021-08-31T12:10:00.0-04:00″.
Si la fecha no es especifica o es menor a la fecha actual, el sistema asume que el envío es inmediato.		No obligatorio

Request

 {
    "userx": {
        "key": "user key"
    },
    "account": {
        "key": "account key"
    },
    "template": "Hola estimad@ {name}, Este es un mensaje de prueba",
    "filePath": "https://mobarmy.dev/wp-content/uploads/2021/08/Invoice_Example_MWT.pdf",
    "fileName": "nombre_file.pdf",
    "scheduled": "2021-08-31T12:10:00.0+00:00",
    "receivers": [
        {
            "name": "Daniel M.",
            "phoneNumber": 59170712345
        },
        {
            "name": "Sammy T.",
            "phoneNumber": 59170354321
        },
        {
            "name": "Danny B.",
            "phoneNumber": 59177900000
        }
    ]
 }

Response

Si el mensaje se ha enviado correctamente, el código de estado devolverá:

 {
    "uid": 26,
    "userx": {
        "key": "user key"
    },
    "account": {
        "key": "account key"
    },
    "type": "FILE",
    "template": "Hola estimad@ {name}, Mensaje de prueba16",
    "filePath": "https://mobarmy.dev/wp-content/uploads/2021/08/Invoice_Example_MWT.pdf",
    "fileName": "nombre_file.pdf",
    "scheduled": "2021-08-31T12:10:00.000+00:00",
    "receivers": [
        {
            "uid": 96,
            "phoneNumber": 59170712345,
            "name": "Espartano M."
        },
        {
            "uid": 97,
            "phoneNumber": 59170354321,
            "name": "Sammy T"
        },
        {
            "uid": 98,
            "phoneNumber": 59177900000,
            "name": "Danny B."
        }
    ]
 }

Si el mensaje no se pudo entregar, devolverá un mensaje de ERROR en el campo de respuesta.

Enviar un código OTP

API URL: http://my-server:port/v1/mwt/otpEvent

Parámetros

A continuación se muestra una lista de parámetros del request.

ParámetroDescripciónPresencia
receiversCadena de destinatarios a los que se enviará el mensaje. Por ejemplo: 59172083143 (No use “+” antes del código de país)Obligatorio
templateMensaje de texto a enviar. 

Nota importante:

La plantilla de mensaje debe contener un marcador de posición (placeholder o comodín) para el código OTP, es decir, {*otp*}. El sistema generará un PIN aleatorio de 4 dígitos y lo sustituirá por el placeholder de la plantilla.

Ejemplo: Este es tu PIN: {*otp*}
Obligatorio
user.keyCredencial de usuario asignado al cliente.Obligatorio
account.keyCredencial de la cuenta asignada al cliente.Obligatorio
scheduledEs un timestamp en el formato “2021-08-31T12:10:00.0-04:00″.
Si la fecha no es especifica o es menor a la fecha actual, el sistema asume que el envío es inmediato.		No obligatorio
otpCharsCadena de caracteres alfanuméricos que conformarán del OTP. Si no se envía este parámetro, por defecto usará los valores: “0123456789”.

Si se especifica este parámetro, el valor no puede ser menor a 10 (diez) caracteres.

Ejemplo: “0123456789ABC”.		No obligatorio
otpPrefixEste campo agrega un prefijo al código OTP. Si no se envía este parámetro, por defecto usará el valor: “”.

Ejemplo: para otpPrefix=”Y-” el código OTP será “Y-184986”.		No obligatorio
otpSizeEste parámetro establece el número de caracteres que conformará en código OTP a generar. Si no se envía este parámetro, por defecto se usará el valor 6.No obligatorio

Request

 {
    "userx": {
        "key": "user key"
    },
    "account": {
        "key": "account key"
    },
    "template": "Hola estimad@ {name}, su codigo de seguridad es: {otp}. Mensaje de prueba17",
    "scheduled": "2021-08-31T16:33:00.0-04:00",
    "otpChars": "0123456789ABCD",
    "otpPrefix": "Y-",
    "otpSize": 6,
    "receivers": [
        {
            "name": "Bruce W.",
            "phoneNumber": 59170712345
        },
        {
            "name": "Daniel M.",
            "phoneNumber": 59170754321
        },
        {
            "name": "Sammy T.",
            "phoneNumber": 59170312345
        },
        {
            "name": "Danny B.",
            "phoneNumber": 59177900000
        }
    ]
 }

Response

Si el mensaje se ha enviado correctamente, el código de estado devolverá:

 {
    "uid": 25,
    "userx": {
        "key": "user key"
    },
    "account": {
        "key": "account key"
    },
    "type": "OTP",
    "template": "Hola estimad@ {name}, su codigo otp es: {otp}. Mensaje de prueba17",
    "filePath": null,
    "fileName": null,
    "scheduled": "2021-08-31T16:33:00.000+00:00",
    "receivers": [
        {
            "uid": 92,
            "phoneNumber": 59170712345,
            "name": "Bruce W."
        },
        {
            "uid": 93,
            "phoneNumber": 59170754321,
            "name": "Espartano M."
        },
        {
            "uid": 94,
            "phoneNumber": 59170312345,
            "name": "Sammy T"
        },
        {
            "uid": 95,
            "phoneNumber": 59177900000,
            "name": "Danny B."
        }
    ]
 }

Si el mensaje no se pudo entregar, devolverá un mensaje de ERROR en el campo de respuesta.

Verificar un código OTP

API URL: http://my-server:port/v1/mwt/verifyOTP

Parámetros

A continuación se muestra una lista de parámetros del request.

ParámetroDescripciónPresencia
phoneNumberLínea de WhatsApp a la que fue enviado el OTP.Obligatorio
otpCodeCódigo OTP a verificar. Este es el código ingresado por el usuario de la aplicación.Obligatorio
keyCredencial de usuario asignado al cliente.Obligatorio
expireTimeEs un valor numérico entre 1 y 15840, que representa cuantos minutos tendrá validez el código OTP que se está verificando.

El valor por defecto es 12 horas => 12 * 60 = 720		No obligatorio

Resquest

 {
    "key": "user key",
    "phoneNumber": 59170712345,
    "otpCode": "4214",
    "expireTime": 5
 }

Response

Si el mensaje se ha enviado correctamente, el código de estado devolverá:

 {
    "valid": true
 }

Si el código OTP ingresado no es igual a alguno registrado en las últimas 24hrs, devolverá el campo valid como «false».