The Documentation Hub

Welcome to Kaleyra Documentation Hub. You can find comprehensive API docs, integration guides and docs to getting you started. In case you're stuck, refer to the docs here and you're good to go

Get Started    

WhatsApp Business API

What can you do with this API?

Seamlessly send messages through WhatsApp with our API. Compose the text that needs to be sent out through WhatsApp and our algorithm converts simple text message to WhatsApp message with images, audio & documents and delivers to the number.

How can I use this API?

To use this API follow the steps below:

  1. Create your message
  2. Trigger the API below with mandatory parameters
  3. Your message will be sent to the WhatsApp number(s)

Supported Formats

This section explains the supported formats of the message. The following formats are only supported:

  1. Text
  2. Audio
  3. Documents
  4. Images
  5. Templates
  6. Contacts
  7. Location
Type
Format

Text

Maximum text message length of 4096 characters

Image

JPG, JPEG, PNG

Document

PDF, DOC(X), PPT(X), XLS(X) ,TXT

Audio

AAC, M4A, AMR, MP3, OGG, OPUS

Template

Text message only

Contacts

List of contacts

Location

Current or Map location

Character Limitation

Maximum characters allowed are 4096 on a single trigger.

Maximum file size

The maximum file upload size is 64 MB

API for sending WhatsApp Messages

            curl -X POST \
  https://global.kaleyra.com/api/v4/ \
  -F method=wa \
  -F api_key=Ab0b126c927a8283fba2f5c50XXXXXX \
  -F 'body={
    "to": 9180508XXXXX,
    "type": "template",
    "template": {
        "namespace": "30e15086_b628_c216_cd8d_xxxxxxx",
        "template_name": "kaleyra_xxxx",
        "policy": "deterministic",
        "lang_code": "en",
        "params": ["#123456789"],
        "ttl": "86400"
    },
    "callback": "http://example.com/callback?"
}
' \
  -F from=91998645XXXX \
  -F format=json
            {
"status":"OK",
"data":[{"id":"3dd51fca-0a0f-4682-81ac-63a6a8b7bd15",
"mobile":"91805082XXXX"}],
"message":"Submitted Successfully."
}

https://global.kaleyra.com/api/v4/?method=wa&from=business number&api_key=A75bXXXXXXXXXXXXXX&body={}&format=json

Prerequisites

  1. Registered WhatsApp Business Number
  2. To Mobile Number
  3. Global API Key
  4. Message

Mandatory API Parameters

API Mandatory Parameters are listed below:

Name
Specification
Expected Value

method

Predefined method

wa

api_key

API key generated from your account

Alphanumeric Authentication key from your GMP account. This will be configured to validate account.

from

Valid registered WhatsApp number which is used for registration of the WhatsApp business account.

WhatsApp number

Name
Description
Response Value

caption

While sending image or Document, should be able to add a caption to the file

For images,
the caption will be added as description. The caption text appears in full length for images on both Android and iPhone.

For documents,
the caption replaces the filename. It is not meant to be displayed on the user's device as description text but instead to show the name of the file.

iPhones show the full text while Androids truncate the filename; this is technical limitation of the current implementation of WhatsApp on both devices

preview_url

Url information will be previewed in the message

Only for type : text

true/false

format

Output response format

xml/json
by default it should return json format
Can be changed to xml

ttl

If the message is not delivered to the customer before the expiration period the message will expire and will not be delivered

Only for template message
Min 86400 & Max 2592000

callback

Callback response with status and timestamp

http://example.com/callback?&status=READ&mobile=919xxxxxxxxx&timestamp=1542006912

Status types :
SENT
READ
DELIVERED

Timestamp: Unix time format
Mobile: Subscriber Mobile Number

Send Text Message(s)

Name
Specification
Expected Value

body

Text Message for Single Number

{
"to": "wa-number" ,
"type": "text",
"text": {
"message": "your-text-content"
},
"preview_url": true ,
"callback":"http://example.com/callback?"
}

Send Document(s)

Name
Specification
Expected Value

Body

Send document to a single number

{
"to": "wa-number",
"type": "document",
"document": {
"caption": "caption_name"
},
"callback":"http://example.com/callback?"
}

Send Images

Name
Specification
Expected Value

body

Send Image to a single number

{
"to": "wa-number",
"type": "image",
"image": {
"caption": "caption_name"
},
"callback":"http://example.com/callback?"
}

Send Audio(s)

Name
Specification
Expected Value

body

Audio for Single Number
sending a audio file to the WhatsApp number with the following formats

AAC, M4A, AMR, MP3, OGG, OPUS

{
"to": "wa-number" ,
"type": "audio",
"audio": {

      },

"callback":"http://example.com/callback?"
}

PHP Curl Snippet
Description

File Upload

File has to uploaded along with media messages (documents, images and audio)
e.g:
$cfile = new CURLFile(realpath('file path/What-is-an-API-1.0.pdf'));
$postdata = array(
'file' => $cfile,
'method' => 'wa',
'api_key' => 'Ab0b12xxxxxxxxxxxxxxxxxxxxx',
'body' => '{"to":"91xxxxxxxxx", "type": "document", "document" : {"caption" : "Ok boss"},"callback":""}',
'from' => '91xxxxxxxxxx',
'format' => 'json'
);

Send Template(s)

Name
Specification
Expected Value

body

Template for a single number

{
"to": "wa-number",
"type": "template",
"template": {
"namespace": "unique namespace id",
"template_name": "order_delivered",
"policy": "deterministic|fallback",
"lang_code": "en",
"params": ["{{value1}}", "{{value2}}"],
"ttl": "1"
},
"callback":"http://example.com/callback?"
}

Send Contact

Name
Specification
Expected Value

body

Contact

{
"to": "["wa-number1"]",
"type": "contacts",
"contacts": [
{
"addresses": [
{
"city": "MessageContactAddressCity",
"country": "MessageContactAddressCountry",
"country_code": "MessageContactAddressCountryCode",
"state": "MessageContactAddressState",
"street": "MessageContactAddressStreet",
"type": "MessageContactAddressType",
"zip": "MessageContactAddressZip"
}
],
"birthday": "MessageContactBirthday",
"emails": [
{
"email": "MessageContactEmail",
"type": "MessageContactEmailType"
}
],
"ims": [],
"name": {
"first_name": "MessageContactFirstName",
"formatted_name": "MessageContactFormattedName",
"last_name": "MessageContactLastName"
},
"org": {
"company": "MessageContactCompany"
},
"phones": [
{
"phone": "MessageContactPhone",
"type": "MessageContactPhoneType"
}
],
"urls": []
}
],
"callback":"http://example.com/callback?"
}

Post Body Parameters for Contact API

Parameter Name
Description
Expected Value

to

Whatsapp registered mobile number with country code

Mobile number with country codes, multiple numbers in an array separated by a comma
Number formats

  1. +919880390XXX
  2. 919880390XXX

type

Type of message

contact

street (optional)

Street number and name

ex: Menlo Park

city (optional)

city name

e.g: SanJose

state

State abbreviation

e.g: CA

zip

ZIP code

e.g:94025

country

Full country name

e.g:United States

country_code

Two-letter country abbreviation

e.g: US

birthday

Birthday
ex:YYYY-MM-DD formatted string

2012-08-18

email

Email address

test@domain.com

Standard Email Validation

type

Standard Values: HOME, WORKStandard Values: HOME, WORK

WORK

first_name

First name

John

last_name

Last name

ex:Smith

formatted_name

Full name as it normally appears

ex:John Smith

company

Name of the contact's company

ex:WhatsApp

department

Name of the contact's department

ex:Design

title

Contact's customer title

ex:Manager

phone

Automatically populated with the wa_id value as a formatted phone number.

EX:+1 (940) 555-1234

type

Standard Values: CELL, MAIN, IPHONE, HOME, WORK

HOME

wa_id

WhatsApp ID

16505551234

type

Standard Values: HOME, WORK

WORK

Response Parameters

Status
Description
Expected Value

status

It indicates the success or failure of your API request. “OK” is success & others are error codes.

1."OK"
2."A404"
3."A402"
4."E603"

More API codes below:
API Error Codes

message

message based on the status code response

1.Submitted successfully
2.Your api account got suspended
3.Api Key not found"
3.Missing message
4.Insufficient credits

More API codes below:
API Error Codes

id

Message sent id, after successful message sent for the given number

Auto generated Alphanumeric id for the successful request

mobile

Mobile number to which message has to be sent.

Subscriber Number to which message has to sent.

Send Location

Name
Specification
Expected Value

body

Location

{
"to": ["wa-number1"],
"type": "location",
"location": {
"longitude": "MessageLocationLongitude",
"latitude": "MessageLocationLatitude",
"name": "MessageLocationName",
"address": "MessageLocationAddress"
},
"callback":"http://example.com/callback?"
}

Post Body Location Parameters for Location API

Parameter Name
Description
Expected Value

to

Whatsapp registered mobile number with country code

Mobile number with country codes, multiple numbers in an array separated by a comma.
Number formats

  1. +919880XXXXXX
  2. +919880XXXXXX

type

Type of message

location

longitude

Location longitude

Valid Location longitude geographical values

ex:-9.669120

latitude

Location latitude

Location latitude geographical values
ex:26.906270

name (optional)

Location name

Location name to be shown to the user

address (optional)

Location address

Location address

Error codes for Location

Code
Description

E616

Latitude missing

E617

Longitude missing

Send message to Multiple Numbers

To send messages to multiple numbers, add two or more numbers in the array format below:

"to": ["wa-number1", "wa-number2"]

Body Mandatory Parameters

Name
Description
Response Value

to

WhatsApp registered mobile number with country code

Mobile number with country codes , multiple numbers in an array separated by comma
Number formats

  1. +919880390XXX
  2. 919880390XXX

type

Type of message

text,audio,document,image

message

Message content to deliver to the given WhatsApp number

Text message

file

File type is supported for the message types document, audio and image.

Upload file which need be sent to given whatsapp number

preview_url

Url information will be previewed in the message

Only for type : text

true/false

namespace

Unique id from the facebook business manager account

Only for template message Unique id
(e.g.,cdb2df51_9816_c754_c5a4_64cdabdcad3e)

template_name

Template name generated in Whatsapps Manager

Template name
(e.g.,order_status).

policy

The language policy the message should follow

Options:

fallback | deterministic

lang_code

The code of the language or locale to use — Accepts

(e.g., en, and en_US)

params

This field is an array of values to apply to variables in the template
Created in the Whatsapps Manager

(e.g., [“1”, “2”])

Example Error Response

{
    "status": "A404",
    "message": "Your api account got suspended"
}

Error Codes

View the API Error Codes

Error Code Exceptions

Error Code
Description

E 504

File size exceeds 64 MB

E 603

Missing Template name

WhatsApp Business API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.