1. Introducción

WhatsApp Delivery API permite automatizar el envío de plantillas WhatsApp a través de Oct8ne. Las operaciones disponibles son las siguientes:

4. Enviar plantilla a WhatsApp
5. Consultar estado del envío
6. Consultar resumen de envíos
7. Consultar detalle de mensajes

2. Seguridad

Todas las llamadas a la API incluir un token de seguridad en el encabezado “x-oct8ne-token”. El token será facilitado por el equipo de soporte de Oct8ne en el momento de la puesta en marcha del servicio.

POST {HOST}/{BASEURL}/{PATH} HTTP/1.0 x-oct8ne-token: KSDX0C09DJDC90JD9WJDXS9DJIKJSJCF9JHFD ...

Si el token es incorrecto, las llamadas retornarán un error HTTP 401.

3. Límites de uso

Con objeto de no saturar el canal de mensajes salientes, por defecto la API de envíos limita su utilización a un máximo de X destinatario por segundo en función del plan. Cualquier intento de superar esta ratio provocará que los nuevos envíos sean descartados, retornando un error HTTP 429.

Por tanto, el envío de un número mayor de mensajes debería realizarse según el siguiente pseudocódigo:

Mientras queden mensajes por enviar: Enviar el siguiente mensaje Esperar X segundo (según plan contratado)

4. Pruebas durante el desarrollo 

Durante el desarrollo del cliente de la API, debe tener en cuenta que cada envío realizado a la infraestructura de WhatsApp conllevará un coste. 

Como se describirá algo más adelante, el endpoint de envío de plantillas permite especificar, mediante el parámetro testMode, que se trata de una llamada de prueba y, por lo tanto, evitar envíos reales al proveedor.

En cualquier caso, recomendamos realizar siempre pruebas con pocos mensajes, por si este parámetro fuera omitido por un descuido.

De la misma forma, antes de realizar envíos reales a gran número de destinatarios, recomendamos realizar previamente algún envío a menor escala a números conocidos con objeto de comprobar que el envío es correcto.

5. URL Base

El host al que hay que dirigir las llamadas depende del centro de datos de Oct8ne al que esté adscrito su empresa. 

Centro de datos	Host
Europa	https://messaging-eu-api.oct8ne.com
LATAM & USA	https://messaging-usa-api.oct8ne.com

Si tiene dudas sobre el centro de datos que le corresponde, consulte al equipo de soporte de Oct8ne.

La base URL para realizar las peticiones es, en la versión actual de la API, la dirección del host correspondiente seguida de los segmentos “/api/v1.0/”. Por ejemplo, el destino de todas las peticiones dirigidas al centro de datos de Europa sería de la forma:

https://messaging-eu-api.oct8ne.com/api/v1.0/{PATH}

Siendo {PATH} es la ruta específica de la acción que desee realizar, 

6. Endpoints

6.1. Envío de plantillas

Este endpoint permite enviar mensajes de plantilla (Templates) vía WhatsApp a uno o varios destinatarios. 

Uso:

POST {BASEURL}/whatsapp/templates/{accountId}/{provider}/{sender} HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN} content-type: application/json {BODY}

Los parámetros incluidos en la ruta son:

6. {accountId}: Identificador de la cuenta de su empresa en Oct8ne. Se le suministrará en el momento de la puesta en marcha del servicio.
7. {provider}: Identificador del proveedor con el que contrató su acceso a WhatsApp Business API. Puede ser uno de los siguientes valores:

3. 2: Vonage
4. 4: 360Dialog
5. 6: Whatsapp Business Cloud API

7. {sender}: Número de teléfono que realizará el envío de los mensajes, que debe estar configurado como instancia del servicio de Messaging dentro de su cuenta de Oct8ne. Debe incluir su prefijo internacional y usar únicamente dígitos numéricos.

Adicionalmente, puede enviar los siguientes parámetros a través de la query string:

9. testMode: Establezca este parámetro a 1 si desea realizar una verificación de los datos suministrados previa al envío o durante el desarrollo del cliente de la API para que evitar que los mensajes lleguen al proveedor de WhatsApp.
10. campaign: Nombre de la campaña a la que pertenece el envío. Es una cadena arbitraria con un máximo de 15 caracteres que identifica el grupo de envíos.

El siguiente ejemplo muestra la petición que realizaría la empresa con código 1008, ubicada en Europa, desde el número de teléfono 34614234216, vinculado al proveedor 360Dialog (4), en la campaña "CHRISTMAS_2020" y activando el modo de pruebas:

POST https://messaging-eu-api.oct8ne.com/api/v1.0/whatsapp/templates/1008/4/34614234216?testMode=1&campaign=CHRISTMAS_2020 HTTP /1.0 ... {BODY}

Como respuesta, el endpoint retornará un objeto como el siguiente, en el que la propiedad deliveryId, una cadena de texto de 32 caracteres como máximo, identifica de forma única el envío realizado:

{  "deliveryId": "393848553.202112" }

Cuerpo de la petición

El cuerpo de la petición debe ser un objeto, serializado como JSON, con el detalle del envío a realizar. Su estructura es la siguiente:

{   "template": <TEMPLATE-INFO>,   "targets": [      <TARGET>   ]    }

El objeto <TEMPLATE-INFO> utilizado en la propiedad template contiene información sobre la plantilla a enviar, según la estructura mostrada a continuación:

<TEMPLATE-INFO> {   "name": "your-template-name",   "language": "your-template-language",   "namespace": "your-account-namespace", }

12. name: Nombre o identificador de la plantilla, tal y como fue registrada en WhatsApp.
13. language: Idioma en el que definió la plantilla.
14. namespace: Espacio de nombres de la cuenta. Si utiliza 360Dialog, puede consultarlo en su panel de administración, o bien, en todos los casos, en la página WhatsApp Manager de la cuenta de Facebook asociada al número que realiza el envío.

Los destinatarios se definen en la propiedad targets en forma de array de objetos <TARGET>, que presentan la siguiente estructura:

<TARGET> {   "number": "",   "components": [      <COMPONENT-1>,      <COMPONENT-2>,      …      <COMPONENT-N>,   ] }

14. number: Es el número de teléfono del destinatario, incluyendo el prefijo internacional y únicamente dígitos numéricos.
15. components: Array que, cuando usamos una plantilla parametrizada, contiene las distintas partes del mensaje (encabezado, cuerpo…) y los parámetros a insertar en cada uno de ellas.

Importante: la versión actual soporta únicamente un destinatario en cada envío, es decir, un único objeto <TARGET> en el array  en cada llamada a la API.

Los componentes siguen la documentación de Whatsapp relativa a objetos components, por lo que puede obtener más información en el sitio oficial. Básicamente siguen esta estructura:

<COMPONENT> {   "type": "body",   "parameters": [      { "type": "text", "text": "First value" },      { "type": "text", "text": "Second value" },   ] }

16. type: Un componente puede ser de tipo "body", "header" o "button". 
17. parameters: Array de parámetros definidos por la plantilla en el componente especificado.

Ejemplo 01: Envío de plantilla sin parámetros a un número

Plantilla: thanks_purchase (en)
Texto (cuerpo): Thanks for your purchase. We hope to see you here again soon.

{   "template": {      "name": "thanks_purchase",      "namespace": "e9fa0eea_3bef_987a_1132_9f29387a5822",      "language": "en"   },   "targets": [      { "number": "34666666666" }   ] }

Ejemplo 02: Envío de plantilla con parámetros en el cuerpo del mensaje

Plantilla: your_order_is_ready (en)
Texto (cuerpo): Dear {{1}}, your order {{2}} is ready.

{   "template": {      "name": "your_order_is_ready",      "namespace": "f7af3d4a_c3be_405d_8824_0e30787b4711",      "language": "en"   },   "targets": [      {         "number": "34666666666",         "components": [            {               "type": "body",               "parameters": [                  {                     "text": "John Smith",                     "type": "text"                  },                  {                     "text": "#2293384",                     "type": "text"                  }               ]            }         ]      }   ] }

Ejemplo 03: Envío de plantilla con parámetros en el encabezado y cuerpo del mensaje

Plantilla: your_order_is_ready_with_header (en)    
Texto (encabezado): Order {{1}}.
Texto (cuerpo): {{1}}, your order {{2}} is ready.

{   "template": {      "name": "your_order_is_ready_with_header",      "namespace": "e8af3d4a_c3be_318e_9283_0e30787c51121",      "language": "en"   },   "targets": [      {         "number": "34666666666",         "components": [            {               "type": "header",               "parameters": [                  {                     "text": "#12345",                     "type": "text"                  }               ]            },            {               "type": "body",               "parameters": [                  {                     "text": "John Smith",                     "type": "text"                  },                  {                     "text": "#12345",                     "type": "text"                  }               ]            }         ]      }   ] }

Ejemplo 04: Envío de plantilla con imagen en el encabezado

Plantilla: promotion (en)
Imagen (encabezado): https:// mysite.com/img/image.jpeg

{   "template": {      "name": "promotion",      "namespace": "d87d4810_fe02_42de_ac0d_778b85afbefd",      "language": "es"    },    "targets": [    {       "number": "5474345225980",       "components": [       {          "type": "header",          "parameters": [          {             "type": "image",             "image": {                "link": "https:// mysite.com/img/image.jpeg"             }          }]       }]     }] }

Opciones adicionales

1. Plantilla con cola de destino

Mediante el parámetro targetQueueId puede especificar el identificador numérico de la cola a la que desea mover la conversación al enviar el mensaje. Puede obtener dicho identificador desde su panel de Oct8ne.

{   "template": <TEMPLATE-INFO>,   "targets": [      <TARGET>   ],   "targetQueueId": <QUEUE-ID> }

Importante: las conversaciones que actualmente tengan una sesión activa no serán movidas de cola aunque se especifique este parámetro.

Ejemplo 05: Envío de plantilla con cola de destino

{   "template": {      "name": "campaign",      "namespace": "d87d4810_fe02_42de_ac0d_778b85afbefd",      "language": "es"    },    "targets": [        {            "number": "XXXXXXXXXXXX",            "components": []        }    ],    "targetQueueId": 165 }

2. Cambiar el estado personalizado de la conversación

Mediante el parámetro customStatusId puede especificar el identificador numérico del estado personalizado al que quiere asignar esta conversación al enviar el mensaje. Puede obtener dicho identificador desde su panel de Oct8ne.

{   "template": <TEMPLATE-INFO>,   "targets": [      <TARGET>   ],   "customStatusId": <CUSTOM-STATUS-ID> }

Ejemplo 06: Envío de plantilla con cambio de estado

{   "template": {      "name": "campaign",      "namespace": "d87d4810_fe02_42de_ac0d_778b85afbefd",      "language": "es"    },    "targets": [        {            "number": "XXXXXXXXXXXX",            "components": []        }    ],    "customStatusId": 12 }

3. No enviar plantilla en caso de tener una sesión abierta

Mediante el parámetro ignoreIfSessionIsActive puede especificar si desea que la plantilla se envíe aún teniendo una sesión en curso. Si un agente en Messaging está con una conversación/sesión en curso puede evitar que en medio de esa conversación se le envíe al cliente un template.

Importante: Las sesiones si no se finalizan por el agente quedan “abiertas” durante 1 día, transcurrido ese plazo el sistema cerrará la sesión. Tenga en cuenta esta casuística a la hora de configurar tanto el envío de plantillas como quien debe finalizar la sesión.

{   "template": <TEMPLATE-INFO>,   "targets": [      <TARGET>   ],   "ignoreIfSessionIsActive":<IGNORE-IF-SESSION-IS-ACTIVE> }

Ejemplo 06: Enviar plantilla en conversaciones con sesiones abiertas

{   "template": {      "name": "campaign",      "namespace": "d87d4810_fe02_42de_ac0d_778b85afbefd",      "language": "es"    },    "targets": [        {            "number": "XXXXXXXXXXXX",            "components": []        }    ],    "ignoreIfSessionIsActive": true }

6.2. Consulta de estado del envío

Este endpoint permite consultar el estado de un envío realizado con anterioridad.

Uso:

GET {BASEURL}/whatsapp/templates/{accountId}/deliveries/{deliveryId} HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

Los parámetros incluidos en la ruta son:

18. {accountId}: Identificador de la cuenta de su empresa en Oct8ne. Se le suministrará en el momento de la puesta en marcha del servicio.
19. {deliveryId}: Identificador del envío realizado anteriormente mediante la API de envío de plantillas.

La estructura del objeto retornado como respuesta es similar a la mostrada a continuación:

{   "provider": 4,   "sender": "34666666666",   "template": "order_ready",   "campaign": null,   "createdAtUtc": "2021-11-01T09:48:00.000",   "mode": "normal",   "totalTargets": 2,   "errorCount": 1,   "successCount": 1,   "details": [      {        "number" : "111111",        "error" : "Undeliverable",        "status": 100      },      {        "number" : "54273481945",        "success" : true,        "deliveredDateUtc": "2021-11-01T09:50:00.000"        "readDate": "2021-11-01T09:50:00.010",        "status": 3      }        ] }

El campo status indica el estado del mensaje en el momento de la llamada, y puede contener uno de los siguientes valores:

Estado	Nombre	Significado
0	Pending	El mensaje ha sido recibido por Oct8ne, pero está pendiente de ser enviado al proveedor de WhatsApp.
1	Submitted	El mensaje ha sido enviado al proveedor de WhatsApp con éxito.
2	Delivered	El proveedor de WhatsApp ha enviado el mensaje correctamente al destinatario. También puede indicar que el envío en modo Test ha sido satisfactorio.
3	Read	El destinatario ha leído el mensaje.
100	Undeliverable	El proveedor de WhatsApp no fue capaz de entregar el mensaje. Puede deberse a que el número no existe, o no dispone de WhatsApp, o está bloqueando al remitente, entre otros motivos.
101	Ignored	El mensaje no fue enviado al proveedor de WhatsApp siguiendo las instrucciones de la llamada. Esto puede ocurrir, por ejemplo, si se ha usado el parámetro ignoreIfSessionIsActive y el destinatario tiene una sesión de conversación abierta.
102	Api Error	Se ha producido un error en la llamada a la API. Habitualmente indica que los parámetros de la invocación no son correctos (por ejemplo, se ha indicado un nombre de plantilla inexistente, el namespace es incorrecto, etc.)

Nota: para los códigos de estado de error (1XX), en el campo error puede consultar información más detallada sobre el motivo por el que el mensaje no fue entregado.

6.3. Consultar resumen de envíos

Esta API permite obtener un resumen agregado de los envíos realizados entre dos fechas determinadas, en formato JSON o CSV.

Uso:

GET {BASEURL}/whatsapp/templates    /{accountId}/deliveries HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

El parámetro {accountId} incluido en la ruta es el identificador de la cuenta de su empresa en Oct8ne. Se le suministrará en el momento de la puesta en marcha del servicio.

Adicionalmente, puede usar la query string para añadir parámetros adicionales de la consulta:

23. from (obligatorio): fecha inicial del periodo a consultar (inclusive). Debe especificarla usando el formato YYYY/MM/DD. No puede ser anterior a un año desde la fecha actual.
24. to (obligatorio): fecha final del periodo (inclusive). Debe especificarla usando el formato YYYY/MM/DD. Como máximo podrá ser 31 días posterior al valor establecido en el parámetro from.
25. sender: si se especifica, sólo se obtendrán los datos relativos al número de teléfono emisor indicado. En caso contrario, serán mostrados todos los números utilizados.
26. offsetMinutes indica el desplazamiento horario en minutos respecto a la zona horaria UTC+0, y es utilizado para obtener los datos atendiendo a dicho factor. Por ejemplo, en horario de verano de España, debería establecerse al valor -120.
27. format indica el formato en el que desean obtenerse los datos, a elegir entre "json" y "csv". Si no se especifica, por defecto se usará JSON.

Un ejemplo completo de llamada podría ser:

GET {BASEURL}/api/v1.0/whatsapp/templates    /4928/deliveries?from=2021/11/01&to=2021/11/02    &offsetMinutes=-120 HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

La estructura del objeto JSON retornado como respuesta es similar a la mostrada a continuación:

[  {    "sender": "34662323212",    "campaign": "BlackFriday21-1",    "isTest": false,    "lastSent": "2021-11-01T03:04:57.18",    "successes": 0,    "errors": 21  },  {    "sender": "34666841698",    "campaign": "BlackFriday21-2",    "isTest": false,    "lastSent": "2021-11-02T20:14:20.593",    "successes": 120,    "errors": 1  } ]

Si opta por CSV, los datos serán retornados en filas (la primera de ellas para el encabezado), separando cada columna por el carácter tabulador:

Sender         Campaign           IsTest LastSent         Successes Errors 34662323212 BlackFriday21-1 0      2021-11-01 03:04:57 64          0 34666841698 BlackFriday21-2 0      2021-11-02 20:14:20 120          1

6.4. Consultar detalle de mensajes

Mediante esta API es posible obtener el detalle de los mensajes enviados entre dos fechas determinadas, en formato JSON o CSV.

Uso:

GET {BASEURL}/whatsapp/templates    /{accountId}/messages HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

El parámetro {accountId} incluido en la ruta es el identificador de la cuenta de su empresa en Oct8ne. Se le suministrará en el momento de la puesta en marcha del servicio.

Adicionalmente, puede usar la query string para añadir parámetros adicionales de la consulta:

31. from (obligatorio): fecha inicial del periodo a consultar (inclusive). Debe especificarla usando el formato YYYY/MM/DD. No puede ser anterior a un año desde la fecha actual.
32. to (obligatorio): fecha final del periodo (inclusive). Debe especificarla usando el formato YYYY/MM/DD. Como máximo podrá ser 1 día posterior al valor establecido en el parámetro from.
33. sender: si se especifica, sólo se obtendrán los datos relativos al número de teléfono emisor indicado. En caso contrario, serán mostrados todos los números utilizados.
34. campaign: cuando es especificado, retorna únicamente los mensajes pertenecientes a la campaña indicada.
35. success permite restringir la búsqueda únicamente a mensajes enviados con éxito (valor true) o con error (valor false).
36. test limita la búsqueda a mensajes enviados en modo de pruebas (valor true) o envíos reales (valor false).
37. offsetMinutes indica el desplazamiento horario en minutos respecto a la zona horaria UTC+0, y es utilizado para obtener los datos atendiendo a dicho factor. Por ejemplo, en horario de verano de España, debería establecerse al valor -120.
38. format indica el formato en el que desean obtenerse los datos, a elegir entre "json" y "csv". Si no se especifica, por defecto se usará JSON.

Un ejemplo completo de llamada podría ser:

GET {BASEURL}/api/v1.0/whatsapp/templates    /4928/messages?from=2021/11/01&to=2021/11/02    &offsetMinutes=-120 HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

La estructura del objeto JSON retornado como respuesta es similar a la mostrada a continuación:

[  {    "sender": "34865723645",    "target": "34626791639",    "campaign": "BlackFriday21-1",    "template": "offer_bf",    "success": true,    "creationDate": "2021-11-01T09:48:06.737",    "extraInfo":"Ignored because there is an active session",    "deliveredDateUtc": "2021-11-01T09:50:00.000"    "readDate": "2021-11-01T09:50:00.010",    "status": 3  },  {    "sender": "34865723645",    "target": "34667349771",    "campaign": "BlackFriday21-2",    "template": "offer_bf",    "success": true,    "creationDate": "2021-11-01T15:23:10.221",    "deliveredDateUtc": "2021-11-01T15:23:11.000"    "readDate": null,    "status": 2  },  ...   ]

Si opta por el formato CSV, los datos serán retornados en filas (la primera de ellas para el encabezado), separando cada columna por el carácter tabulador.

6.5. Consultar uso

Mediante esta API es posible obtener el detalle de consumo de los últimos meses.

Uso:

GET {BASEURL}/usage/{accountId} HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

El parámetro {accountId} incluido en la ruta es el identificador de la cuenta de su empresa en Oct8ne. Se le suministrará en el momento de la puesta en marcha del servicio.

Adicionalmente, puede usar la query string para añadir parámetros adicionales de la consulta:

34. year: si se especifica, se obtendrán los datos relativos al año indicado. En caso contrario, serán mostrados los datos de uso del año en curso.
35. month: si se especifica, sólo se obtendrán los datos relativos al mes indicado. En caso contrario, serán mostrados los datos de uso del año en curso.
36. format indica el formato en el que desean obtenerse los datos, a elegir entre "json" y "csv". Si no se especifica, por defecto se usará JSON.

Un ejemplo completo de llamada podría ser:

GET {BASEURL}/api/v1.0/usage/4928?year=2023&month=8 HTTP /1.0 x-oct8ne-token: {YOUR-TOKEN}

Cuando se solicita información de un mes concreto, la estructura del objeto JSON retornado como respuesta es similar a la mostrada a continuación:

{   "month": 8,   "usage": 1534 }

En cambio, si no se especifica el mes, se obtendrán un array con los consumos de los distintos meses:

[   { "month": 1, "usage": 1534 },   { "month": 2, "usage": 879 },   { "month": 3, "usage": 1850 } ]

Si opta por CSV, los datos serán retornados en filas (la primera de ellas para el encabezado), separando cada columna por el carácter tabulador.