Send Whatsapp SMS

{info} Ensure you read Whatsapp Overview HERE first.

Endpoint

For sending messages, the base url is:

@bulk_base/api/v1

{info} This endpoint is rate limited to 120 requests per second.

Method

Method URI
POST /whatsapp/send-message


Sending Template Message

Request Params

Param Type Description
sender string(required) The Phone Number to send the message with
recipient string(required) Phone Number to receive message. Should start with country code with 12 characters (e.g 254 for kenya) or 07 with 10 characters for Kenya or 7 with 9 characters for Kenya.
message OBJECT(required) Message structure, click HERE to see available message structures
correlator string(optional) A Unique identifier generated by YOUR system, for each message. We forward delivery receipts together with your correlator, to help you identify the message in your system associated with the delivery receipt,
endpoint string(optional) Your endpoint that we will call to send delivery receipt for a given message. Click HERE for delivery receipt structure

Message Object

Message body defines the type of message being sent via WhatsApp.

Message object contains type, template_name, language, header and params

Template

Used to send WhatsApp approved template messages with variables and optional media attachments.

Request Parameters

Parameter Type Required Description
type string Yes Must be "template"
template_name string Yes Name of Meta-approved template
language string Yes Template language code (e.g., en, en_US, en_UK)
header object Conditional Required if template has media header
params array Conditional Required if template has variables

Header Object Parameters (when present)

Parameter Type Required Description
type string Yes Media type: image, document or video
url string Yes HTTPS URL to media file
caption string No Media description

Requirements

  1. The params array must:
    • Contain values in exact order of template variables
    • Match the quantity of variables in template
  2. Media requirements:
    • Images: JPEG/PNG
    • Documents: PDF
    • Videos: MP4
  3. All URLs must be HTTPS


Sample Request (with media header)

Replace type with appropriate media type (image, document or video)

{
    "sender": "2547XXXXXXXX",
    "recipient": "2547XXXXXXXX",
    "message": {
        "type": "template",
        "template_name": "policy_placement",
        "language": "en",
        "header": {
            "type": "document",
            "url": "https://example.com/policy.pdf",
            "caption": "Policy Document"
        },
        "params": ["John", "MB93824", "2 days", "10000", "My Company Name"]
    }
}


Sample Request (without media header)

Useful if your template has no media header of type image, document or video

{
    "sender": "2547XXXXXXXX",
    "recipient": "2547XXXXXXXX",
    "message": {
        "type": "template",
        "template_name": "policy_placement",
        "language": "en",
        "params": ["John", "MB93824", "2 days", "10000", "My Company Name"]
    }
}


Sending Non-template Message

Request Params

Param Type Description
sender string(required) The Phone Number to send the message with
recipient string(required) Phone Number to receive message. Should start with country code with 12 characters (e.g 254 for kenya) or 07 with 10 characters for Kenya or 7 with 9 characters for Kenya.
message OBJECT(required) Message structure, click HERE to see available message structures
correlator string(optional) A Unique identifier generated by YOUR system, for each message. We forward delivery receipts together with your correlator, to help you identify the message in your system associated with the delivery receipt,
endpoint string(optional) Your endpoint that we will call to send delivery receipt for a given message. Click HERE for delivery receipt structure

Message Object

Message body defines the type of message being sent via whatsapp.

Currently available types are text, image, document and template

Text

used to send simple Textual messages.

Request Params

Param Type Description
type string(required) value should be text
text string(required) Message to be sent to specified Recipient

Sample Text Request Body

{
    "sender": "2547XXXXXXXX",
    "recipient": "2547XXXXXXXX",
    "message": {
        "type": "text",
        "text": "Test Whatsapp"
    }
}

Image

Used to send Image Object.

Valid Image types are jpeg, png.

The Imgae should be less than 2MB

Request Params

Param Type Description
type string(required) value should be image
image_url string(required) A Valid HTTP endpoint that points to the image file directly.

Sample Image Request Body

{
    "sender": "2547XXXXXXXX",
    "recipient": "2547XXXXXXXX",
    "message": {
        "type": "image",
        "image_url": "https://example.com/image_1.jpg"
    }
}

Sample Success Response

StatusCode 200

Content

{
    "status": true,
    "message": "Message Successfully Queued",
    "data": {
        "uniqueId": 5,
        "correlator": 999,
        "from": "254XXXXXXXXX"
    }
}

Read Receipts Structure

All Requested read receipts will be delivered via a POST method..

Available deliveryStatus are Read and Error

Sample Read receipt Body

{
    "phone": "2547XXXXXXXX",
    "correlator": "999",
    "uniqueId": 4,
    "deliveryStatus": "Read",
    "remarks": "Message Read",
    "dated": "2020-05-11 15:30:20"
}