1. Introduction

WhatsApp Delivery API allows you to automate the delivery of WhatsApp templates via Oct8ne. The following operations are available:

4. Send template to WhatsApp
5. Get delivery status
6. Get deliveries
7. Get message details

2. Security

All API calls must include a security token in the "x-oct8ne-token" header. The token will be provided by the Oct8ne support team at the time-of-service launch.

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

If the token is incorrect, calls will return an HTTP 401 error.

3. Limits on use

In order not to saturate the outgoing message channel, by default the sending API limits its usage to a maximum of 1 recipient per second. Any attempt to exceed this rate will cause new sends to be discarded, returning an HTTP 429 error.

Therefore, sending a larger number of messages should be done according to the following pseudo-code:

As long as there are still messages to be sent: Send the following message Wait 1 second

4. Testing during development 

During the development of the API client, you should be aware that each submission to the WhatsApp infrastructure will incur a cost. 

As will be described a little later, the template submission endpoint allows to specify, via the testMode parameter, that this is a test call and therefore to avoid actual submissions to the provider.

In any case, we recommend always testing with few messages, in case this parameter is omitted due to an oversight.

In the same way, before sending actual messages to a large number of recipients, we recommend making some smaller-scale mailings to known numbers beforehand in order to check that everything works fine.

5. URL Base

The host to which calls should be targeted depends on the Oct8ne data center to which your company is attached. 

Data center	Host
Europe	https://messaging-eu-api.oct8ne.com
LATAM & USA	https://messaging-usa-api.oct8ne.com

If you are in doubt about which data center is right for you, please consult the Oct8ne support team.

The URL basis for making requests is, in the current version of the API, the address of the corresponding host followed by the segments "/api/v1.0/". For example, the destination of all requests directed to the Europe data center would be of the form:

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

where {PATH} is the specific path of the action you want to perform. 

6. Endpoints

6.1. Sending templates

This endpoint allows template messages (Templates) to be sent via WhatsApp to one or more recipients. 

Use:

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

The parameters included in the path are:

6. {accountId}: Identifier of your company's Oct8ne account. It will be provided to you when the service is set up.
7. {provider}: Identifier of the provider with whom you contracted your WhatsApp Business API access. This can be one of the following values:

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

7. {sender}: The telephone number that will send the messages, which must be configured as an instance of the Messaging service within your Oct8ne account. You must include your international prefix and use only numeric digits.

Additionally, you can send the following parameters via the query string:

9. testMode: Set this parameter to 1 if you want to perform a verification of the data provided prior to sending or during the development of the API client to prevent messages from reaching the WhatsApp provider.
10. campaign: Name of the campaign to which the mailing belongs. It is an arbitrary string with a maximum of 15 characters that identifies the group of mailings.

The following example shows the request that would be made by the company with code 1008, located in Europe, from the phone number 34614234216, linked to the provider 360Dialog (4), in the campaign "CHRISTMAS_2020" and activating the test mode:

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

In response, the endpoint will return an object like the following, where the deliveryId property, a text string of up to 32 characters, uniquely identifies the delivery:

{  "deliveryId": "393848553.202112" }

Request body

The body of the request must be an object, serialised as JSON, with the details of the sending to be done. Its structure is as follows:

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

The <TEMPLATE-INFO> object used in the template property contains information about the template to be sent, according to the structure shown below:

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

12. name: Name or identifier of the template, as registered in WhatsApp.
13. language: Language in which you defined the template.
14. namespace: Account namespace. If you use 360Dialog, you can check this in your admin panel or, in all cases, on the WhatsApp Manager page of the Facebook account associated with the sending number.

The targets are defined in the targets property as an array of <TARGET> objects, which have the following structure:

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

14. number: This is the telephone number of the addressee, including the international prefix and numeric digits only.
15. components: Array that, when using a parameterised template, contains the different parts of the message (header, body...) and the parameters to insert in each of them.

Important: the current version supports only one recipient in each dispatch, i.e. only one <TARGET> object in the array in each API call.

The components follow the Whatsapp documentation for component objects, so you can find more information on the official site. They basically follow this structure:

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

16. type: A component can be of type "body", "header" or "button". 
17. parameters: Array of parameters defined by the template in the specified component.

Example 01: Sending a template without parameters to a number

Template: thanks_purchase (en)
Text (body): 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" }   ] }

Example 02: Sending template with parameters in message body

Template: your_order_is_ready (en)
Text (body): 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"                  }               ]            }         ]      }   ] }

Example 03: Sending template with parameters in the header and body of the message

Template: your_order_is_ready_with_header (en)
Text (header): Order {{1}}.
Text (body): {{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"                  }               ]            }         ]      }   ] }

Example 04: Sending template with header image

Template: promotion (en)
Image (header): 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"             }          }]       }]     }] }

Additional Options

1. Template with target queue

Using the targetQueueId parameter, you can specify the numeric identifier of the queue to which you want to move the conversation when the message is sent. You can get such an identifier from your Oct8ne dashboard.

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

Important: Conversations that currently have an active session will not be moved to the specified queue.

Example 05: Sending Template with Destination Queue

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

2. Template with custom status 

Using the customStatusId parameter, you can specify the numeric identifier of the custom status to which you want to assign this conversation when sending the message. You can get such an identifier from your Oct8ne dashboard.

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

Example 06: Sending Template with Custom Status change

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

3. Do not send template if a session is open 

Using the ignoreIfSessionIsActive parameter, you can specify whether you want the template to be sent even if a session is in progress. If an agent in Messaging is in the middle of a conversation/session, this parameter can prevent the template from being sent to the customer during that conversation.

Important: If sessions are not ended by the agent, they remain "open" for 1 day. After this period, the system will close the session. Keep this in mind when configuring both the template sending and who should end the session.

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

Example 06: Send template in conversations with open sessions

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

6.2. Get delivery status

This endpoint allows you to get the status of a delivery previously made.

Use:

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

The parameters included in the path are:

18. {accountId}: Identifier of your company's Oct8ne account. It will be provided to you when the service is set up.
19. {deliveryId}: Identifier of the delivery previously made through the template delivery API.

The structure of the object returned as a response is similar to the one shown below:

{   "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      }        ] }

The status field indicates the status of the message at the time of the call, and can contain one of the following values:

State	Name	Meaning
0	Pending	The message has been received by Oct8ne, but it is pending to be sent to the WhatsApp provider.
1	Submitted	The message has been sent to the WhatsApp provider successfully.
2	Delivered	The WhatsApp provider has successfully sent the message to the recipient. It can also indicate that the submission in Test mode was successful.
3	Read	The recipient has read the message.
100	Undeliverable	The WhatsApp provider was not able to deliver the message. It may be because the number does not exist, or does not have WhatsApp, or is blocking the sender, among other reasons.
101	Ignored	The message was not sent to the WhatsApp provider following the instructions on the call. This can happen, for example, if the ignoreIfSessionIsActive parameter has been used  and the recipient has an open conversation session.
102	Api Error	The API call failed. Usually indicates that the invocation parameters are incorrect (e.g., a non-existent template name has been specified, the namespace is incorrect, etc.)

Note: For error status codes (1XX), you can see more detailed information about why the message was not delivered in the error field.

6.3. Get deliveries

This API allows you to obtain an aggregated summary of deliveries made between two given dates, in JSON or CSV format.

Usage:

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

The {accountId} parameter included in the path is the identifier of your company's Oct8ne account. It will be provided to you at the time of the start-up of the service.

Additionally, you can use the query string to add additional query parameters:

23. from (mandatory): initial date of the period to be consulted (inclusive). It must be specified using the format YYYYY/MM/DD. It cannot be earlier than one year from the current date.
24. to (mandatory): end date of the period (inclusive). You must specify it using the format YYYYY/MM/DD. It can be a maximum of 31 days after the value set in the from parameter and they must be from the same year.
25. sender: if specified, only the data relating to the specified sender telephone number will be obtained. Otherwise, all numbers used will be displayed.
26. offsetMinutes indicates the time offset in minutes with respect to the UTC+0 time zone, and is used to obtain the data according to this factor. For example, in Spanish summer time, it should be set to the value -120.
27. format indicates the format in which the data is to be obtained, choosing between "json" and "csv". If not specified, JSON will be used by default.

A complete example of a call could be:

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}

The structure of the JSON object returned as a response is similar to the one shown below:

[  {    "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  } ]

If you opt for CSV, the data will be returned in rows (the first row for the header), separating each column by the tab character:

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. Get message details

Through this API it is possible to obtain the detail of the messages sent between two specific dates, in JSON or CSV format.

Usage:

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

The {accountId} parameter  included in the path is the identifier of your company account on Oct8ne. It will be supplied to you at the time of commissioning of the service. Additionally, you can use the query string to add extra query parameters:

31. from (mandatory): initial date of the period to be consulted (inclusive). It must be specified using the format YYYYY/MM/DD. It cannot be earlier than one year from the current date.
32. to (mandatory): end date of the period (inclusive). You must specify it using the format YYYYY/MM/DD. It can be a maximum of 1 days after the value set in the from parameter and they must be from the same year.
33. sender: if specified, only the data relating to the specified sender telephone number will be obtained. Otherwise, all numbers used will be displayed.
34. campaign: When specified, returns only messages belonging to the indicated campaign.
35. success allows you to restrict the search only to messages sent successfully (value true) or with error (value false).
    
    
36. test limits the search to messages sent in test mode (value true) or actual submissions (value false).
37. offsetMinutes indicates the time offset in minutes with respect to the UTC+0 time zone, and is used to obtain the data according to this factor. For example, in Spanish summer time, it should be set to the value -120.
38. format indicates the format in which the data is to be obtained, choosing between "json" and "csv". If not specified, JSON will be used by default.

A complete example of a call to this API could be the following:

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}

The structure of the JSON object returned as a response is similar to the one shown below:

[  {    "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  },  ...   ]

If you opt for CSV, the data will be returned in rows (the first row for the header), separating each column by the tab character.

6.5. Check usage

Through this API, it is possible to obtain the usage details of the past months.

A complete example of a call to this API could be the following:

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

The {accountId} parameter  included in the path is the identifier of your company account on Oct8ne. It will be supplied to you at the time of commissioning of the service. 

Additionally, you can use the query string to add extra query parameters:

34. year: If specified, data for the indicated year will be obtained. Otherwise, usage data for the current year will be displayed.
35. month: If specified, only data for the specified month will be obtained. Otherwise, usage data for the current year will be displayed.
36. format indicates the format in which the data is to be obtained, to choose between "json" and "csv". If not specified, JSON will be used by default.

A complete example of a call to this API could be the following:

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

When requesting information for a specific month, the structure of the JSON object returned in response is similar to the following:

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

On the other hand, if the month is not specified, an array will be obtained with the consumption of the different months:

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

If you opt for CSV, the data will be returned in rows (the first row for the header), separating each column by the tab character.