Introduction

About the Service

The Delevera WhatsApp Business API provides a rich, enterprise grade messaging solution for clients who wish to communicate with their customers via WhatsApp.

WhatsApp is the most popular communication and chatting app for the past few years. With its rich features, it can be a powerful platform for business owners to communicate with their clients. Therefore, WhatsApp for Business API has been introduced as a business version of WhatsApp.

Introducing WhatsApp for Business API as a communication channel between business owners and their customers.

  1. Communicate with 1.5B Global Users
  2. Instant communication to increase your customer’s satisfaction with less expenses
  3. Rich Media Content
  4. Ability to share live Locations and messages

We simply shape the future of Business Communications …

Authentication

To be able to authenticate Delevera WhatsApp Business API the access token needs to be passed.

BearerAuth

Authorization: Bearer 8d18d2f9045b7145ff81***********

Base URL

Currently all WhatsApp URLs referenced in the WhatsApp documentation has the base URL:

https://www.delevera.com/wa/v1/

Opt-In-and-Outs

All Business initiated conversations via the Delevera WhatsApp Business API must start with an “Opt-In” by the user. This can be collected through any third party. For example in an SMS message, In-Line with a Web Form, in an Email, or even via a deep-link in print media.

You can record a opt-in by the API call described below and once the “Opt-In” is recorded you’ll be able to message that customer via the Delevera WhatsApp Business API.

Businesses must provide a method by which customers may opt-out of receiving future messages from your organisation. The opt-out should be handled using the API call below.

Opt-In

Opt-in numbers to enable the receiving of business messages via WhatsApp.

post /provision/optin/

Authorizations

Authorizations is required via BearerAuth

Opt-In request Parameters

all data must be sent using Json format

Parameters Description required
numbers number or numbers for users who is going to receive messages from the enterprise. Yes

Opt-In Response Parameters

all results return with Json format

Parameters type Description
type string the opration type
statuses Array of object the opration results

the statuses object variables are show in below table

Parameters Description
status the status of the opration which can be success or failed
state the number status which can be enable or disable


curl -X POST \
  https://www.mobily.ws/wa/v1/provision/optin \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d '{
    "numbers": [
        "966666666666",
        "966666666666"
    ]
}'
{
    "type": "Opt-In",
    "statuses": [
        {
            "status": "success",
            "state": "enable"
        }
    ]
}
//Error on Empty number 
{
    "message": "Validation Failed",
    "reason": "Field [numbers]: must not be empty"
}

//Error on invalid number 
{
    "message": "Validation Failed",
    "reason":  "965577.523233 is not a valid msisdn"
}
{
    "message": "401",
    "reason": "No such bot/bearer combination"
}

Opt-Out

Opt-in numbers to enable the receiving of business messages via WhatsApp.

post /provision/optout/

Authorizations

Authorizations is required via BearerAuth

Opt-Out request Parameters

all data must be sent using Json format

Parameters Description required
numbers number or numbers for users who is receiving the messages from the enterprise. Yes

Opt-Out Response Parameters

all results return with Json format

Parameters type Description
type string the opration type
statuses Array of object the opration results

the statuses object variables are show in below table

Parameters Description
status the status of the opration which can be success or failed
state the number status which can be enable or disable


curl -X POST \
  https://www.mobily.ws/wa/v1/provision/optout \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d '{
    "numbers": [
        "966666666666",
        "966666666666"
    ]
}'
{
    "type": "Opt-Out",
    "statuses": [
        {
            "status": "success",
            "state": "disable"
        }
    ]
}
//Error on Empty number 
{
    "message": "Validation Failed",
    "reason": "Field [numbers]: must not be empty"
}

//Error on invalid number 
{
    "message": "Validation Failed",
    "reason":  "965577.523233 is not a valid msisdn"
}
{
    "message": "401",
    "reason": "No such bot/bearer combination"
}

Message

The message endpoint is used as the primary endpoint of the API and this is where all the messages are sent through.

post /messages/

Authorizations

Authorizations is required via BearerAuth

WhatsApp Message flow

WhatsApp message flow

  1. Customer opt-in is essential before sending any messages.
  2. Businesses can only start a conversation with a defined message template.
  3. Once you get a reply from your customer, a customer care session starts. You can then send “session” rich content messages for 24 hours.
  4. Every time a customer replies to one of your messages, a new 24-hour cycle starts.
  5. If a “session” expires, you’ll need to re-initiate a conversation, starting with a defined message template again.
  6. Customers can start a rich content conversation with a business at any time this opens up a new 24-hour session.

Supported Content-Types

Delevera WhatsApp API supports several media types. In the table below you can find what content-types are supported by the API.

Message type Supported Content-Types
Image image/jpeg, image/png
Video video/mp4
Document pdf, msword , vnd.ms-powerpoint , vnd.ms-excel ,text/plain
Audio AAC, M4A, AMR, MP3, OGG, OPUS.

Send a WhatsApp Message

Message API is use to send Messages to all numbers are pre opt-in only

when sending message , you should initiat the conversation with template type message , and you can spicify which template by using one of pre define templates.

other than this you are free to use the free form messages if the end user reply to your Template message or send you a message.

also you may want to specify the conversation time to live in queue waiting for receptors to receive the message using the parameter ttl (Time To Live) default time is 7 days, after that message will be deleted from the queue and fail error will be return.

Message request Parameters

Parameters Description required
to Array of phone numbers (msisdns) yes
message Message Type as Object yes

Messages Types


{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": "template",
    "template_name": "template_name",
    "params": ["77584"],
    "ttl": "P1D"
  }
{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": "text",
    "text": "Greetings from Mobily.ws"
  }
}
{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": "image",
    "url": "https://www.site.com/path/image.png",
    "caption": "Image Caption"
  }
}
{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": "video",
    "url": "https://www.site.com/path/video.mp4",
    "caption": "Video Caption"
  }
}
{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": "document",
    "url": "https://www.site.com/path/document.pdf",
    "caption": "Document Caption",
    "filename": "document.pdf"
  }
}
{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": " audio",
    "url": "https://www.site.com/path/audio.mp3"
  }
}
{
  "to": ["966666666666","966666666666"],
  "message": {
    "type": "location",
    "lat": "55.7047",
    "lng": "13.7047",
    "name": "names",
    "address": "address details"
      } 
}
{
  "to": ["966666666666"],
  "message": {
    "type": "contacts",
    "contacts": [
      {
        "addresses": [
          {
            "city": "Menlo Park",
            "country": "United States",
            "country_code": "us",
            "state": "CA",
            "street": "1 Hacker Way",
            "type": "HOME",
            "zip": "94025"
          }
        ],
        "birthday": "2012-08-18",
        "emails": [
          {
            "email": "test@fb.com",
            "type": "WORK"
          }
        ],
        "name": {
          "first_name": "John",
          "formatted_name": "John Smith",
          "last_name": "Smith"
        },
        "org": {
          "company": "WhatsApp",
          "department": "Design",
          "title": "Manager"
        },
        "phones": [
          {
            "phone": "+1 (654) 555-5555",
            "type": "WORK",
            "wa_id": "142055515444"
          }
        ],
        "urls": [
          {
            "url": "https://www.facebook.com",
            "type": "WORK"
          }
       ]
       }
    ]
}
}
{
  "type": "whatsapp",
  "statuses": [
      {
          "message_id": "a33538ff-e1c8-4916-a55b-7e9f7a8c0eb0",
          "recipient": "+966666666666",
          "status": "success",
          "state": "queued"
      }
  ]
}
//Empty Numbers or Text Message is empty or message type is incorrect
{
  "message": "Validation Failed",
  "reason":  "Field [numbers]: must not be empty"
}
//increct MSID format
{
  "message": "Validation Failed",
  "reason":  "965577.523233 is not a valid msisdn"
}

//exceed the max number of numbers [20 at most per request]
{
  "message": "400",
  "reason":  "the max Array of phone numbers is 20"
}

//message type is ncorrect
{
  "message": "Required request body is missing: public org.springframework.http.ResponseEntity<?> ws.mobily.whatsappapi.rest.services.NorthEndpoint.postMessage(ws.mobily.whatsappapi.domain.bot.Bot,ws.mobily.whatsappapi.domain.message.north.MobilyWhatsAppMessage)",
  "reason":  ""
}

//emprt message content
{
  "message": "Validation Failed",
  "reason":  "Field [message.text]: must not be empty"
}

// Link is empty
{
  "message": "Validation Failed",
  "reason":  "Field [message.url]: must not be empty"
}

//lat location is empty
{
  "message": "Validation Failed",
  "reason":  "Field [message.lat]: Parameter '{parameterPath}' must be provided."
}

//lng location is empty
{
  "message": "Validation Failed",
  "reason":  "Field [message.lng]: Parameter '{parameterPath}' must be provided."
}
{
  "message": "401",
  "reason":  "No such bot/bearer combination"
}

//balance is not enough
{
  "message": "402",
  "reason":  "Your balance is not enough"
}

//subscription expired
{
  "message": "402",
  "reason":  "subscription expired"
}

Call Back

{
  "type": "whatsapp",
  "statuses": [
      {
          "message_id": "message_id",
          "recipient": "recipient",
          "status": "status",
          "state": "status" 
          // dispatched, sent, delivered, read
      }
  ]
}

Message States

The message states below are status updates on sent messages.

message description
QUEUED Message has been queued by Delevera WhatsApp API
DISPATCHED Message has been dispatched by Delevera WhatsApp API to WhatsApp
SENT Message has been sent by WhatsApp to end-user
DELIVERED Message has been delivered to end-user by WhatsApp
READ The message has been read by the end-user in the WhatsApp application
DELETED The message has been deleted in the application, e.g. templates expiring or when the end-user manually deletes a message
NO_CAPABILITY Sent message has been rejected by the Delevera API as the recipient lacks WhatsApp capability
NO_OPT_IN Message rejected by Delevera API as recipient is not registered to have opted in to receive business messages on WhatsApp from the sending bot
FAILED Fail status, e.g. trying to send a non-template message outside of the 24 hour customer care window will return this error

Notification

Notification messages can be of one of the following Text, Location, Contacts or Media.


{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "text",
        "body": "hello"
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "image",
        "url": "https://site.com/image.png",
        "caption": "Image captain",
        "filename":"image.png",
        "mime_type": "image/jpeg"
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "video",
        "url": "https://site.com/video.mp4",
        "caption": "Video captain",
        "filename":"video.mp4",
        "mime_type": " video/mp4"
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "document",
        "url": "https://site.com/document.pdf",
        "caption": "Document captain",
        "filename":"document.pdf",
        "mime_type": "application/pdf"
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "audio",
        "url": "https://site.com/audio.mpeg",
        "caption": "Document captain",
        "filename":"audio.pdf",
        "mime_type": "audio/mpeg"
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "location",
"latitude": 31.919209,
        "longitude": 35.893356
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "notifications": [ {
      "from": "966666666666",
      "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
      "message": {
        "type": "contacts",
        "contacts": [
{
            "phoneNumbers": ["966666666666"],
            "name": "john smith"
          }
        ]
      },
      "to": "mobily"
    } ]
}
{
  "type": "whatsapp",
  "statuses": [
      {
          "message_id": "ABEGlid4WEQkAhDV7wnjg8YrPJH04-JlBJRb",
          "recipient": "+966666666666",
          "status": "success",
          "state": "queued"
      }
  ]
}
curl -X POST \
  https://www.mobily.ws/wa/v1/provision/optin \
  -H 'Authorization: Bearer 8d18d2f9045b7145ff81***********' \
  -H 'Content-Type: application/json' \
  -d '{
    "numbers": [
        "966666666666",
        "966666666666"
    ]
}'
{
    "type": "Opt-In",
    "statuses": [
        {
            "status": "success",
            "state": "enable"
        }
    ]
}
//Error on Empty number 
{
    "message": "Validation Failed",
    "reason": "Field [numbers]: must not be empty"
}

//Error on invalid number 
{
    "message": "Validation Failed",
    "reason":  "965577.523233 is not a valid msisdn"
}
{
    "message": "401",
    "reason": "No such bot/bearer combination"
}