Status Code

Meaning

Scenario

200

The request was processed successfully

400

Bad Request

Your request contained invalid or missing data

401

Unauthorized

Authentication failed or the Authenticate header was not provided

404

Not Found

The URI does not match any of the recognised resources, or, if you are asking for a specific resource with an ID, that resource does not exist

405

Method Not Allowed

The HTTP request method you are trying to use is not allowed. Make an OPTIONS request to see the allowed methods

406

Not Acceptable

The Accept content type you are asking for is not supported by the REST API

415

Unsupported Media Type

The Content-Type header is not supported by the REST API

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value template.

String

N/A

Yes

template_name

Name of the template.

String

N/A

Yes

params

Parameters to inject into the template.

String array

N/A

This parameter can only be used for template messages with only a body of text.

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value text

String

N/A

Yes

preview_url

Message object

Boolean

false

true or false

Text

The text message content

String

N/A

Valid URL

Yes

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value image

String

N/A

Yes

url

Public url of the image file. Should be either HTTP or HTTPS link.

String

N/A

Accepted Content-Type header

Yes

caption

Optional caption that will be displayed underneath the image.

String

None

N/A

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value video

String

N/A

Yes

url

Public url of the video file (mp4). Should be either HTTP or HTTPS link.

String

N/A

Accepted Content-Type header

Yes

caption

Optional caption that will be displayed underneath the video.

String

None

N/A

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value document

String

N/A

Yes

url

Public url of the document file. Should be either HTTP or HTTPS link.

String

N/A

Accepted Content-Type header

Yes

filename

Optional parameter that describes the filename of the document.

String

None

N/A

caption

Optional caption that will be displayed as the document title.

String

None

N/A

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value audio

String

N/A

Yes

url

Public url of the audio file. Should be either HTTP or HTTPS link.

String

N/A

Accepted Content-Type header

Yes

Name

Description

JSON Type

Default

Constraints

Required

type

Constant value location

String

N/A

Yes

lat

The latitude position as a float number.

Number

N/A

[-90, 90]

Yes

lng

The longitude position as a float number.

Number

N/A

[-180, 180]

Yes

name

The name for the location. Will be displayed in the message.

String

N/A

address

The address for the location. Will be displayed in the message.

String

N/A

Message Type

Supported content types

Post-processing size limit

document

Any content type listed for other message types,

text/plain, text/csv, application/pdf, application/msword, application/x-tar, application/rtf.0, application/vnd.ms-powerpoint,


application/vnd.openxmlformats-officedocument.presentationml.presentation,

application/vnd.openxmlformats-officedocument.wordprocessingml.document,

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,

application/vnd.oasis.opendocument.presentation,

application/vnd.oasis.opendocument.spreadsheet,

application/vnd.ms-excel,

application/vnd.oasis.opendocument.text

100 MB

image

image/jpeg, image/png

5 MB

audio

audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg, audio/opus

16 MB

video

video/mp4, video/3gpp

16 MB

sticker

image/webp

100 KB

/v2/whatsapp/blacklist

POST /v2/whatsapp/blacklist beta since v2
Documentation
Block messages from number(s)
Parameters
Parameter Type Required? Format Description
numbers[] array of strings true List of numbers
Status Codes
Status Code Description
200
Returned when successful
403
Returned when the user is not authorized
405
Method not allowed

/v2/whatsapp/capabilities

POST /v2/whatsapp/capabilities beta since v2

Documentation

Check capability of number(s) to receive messages

Parameters

Parameter	Type	Required?	Format	Description
numbers[]	array of strings	true		List of numbers

Return

Parameter	Type	Versions	Description
capabilities[]	array of objects (WhatsappOptIn)	>=v2	A collection of opt-in objects
capabilities[][name]	string	>=v2	Name
capabilities[][number]	string	>=v2	Number
capabilities[][capable]	boolean	>=v2	Capability
capabilities[][blacklist]	boolean	>=v2	Notification blacklist

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the user is not authorized
405	Method not allowed

/v2/whatsapp/incoming

GET /v2/whatsapp/incoming beta since v2

Documentation

Get list of incoming messages

Filters

Name	Information
offset	Requirement \d+ Description Pagination offset (default 1, maximum offset + limit = 10,000) Default 1
limit	Requirement \d+ Description Number of items to return (default 20, maximum 1000) Default 20
startDate	Requirement Description Start date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
endDate	Requirement Description End date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
destination	Requirement \d+ Description The shared pool or dedicated number which the sms was sent to
origin	Requirement \d+ Description The number where the SMS appears to come from
search	Requirement Description Search string in source, destination and message

Return

Parameter	Type	Versions	Description
messages[]	array of objects (WhatsappIncoming)	>=v2	A collection of message objects
messages[][id]	integer	>=v2	Message id
messages[][from]	string	>=v2	From
messages[][to]	string	>=v2	To
messages[][message]	string	>=v2	Message
messages[][createdDate]	DateTime	>=v2	Create date

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the user is not authorized
405	Method not allowed

/v2/whatsapp/incoming/read

POST /v2/whatsapp/incoming/read beta since v2
Documentation
Update incoming message(s) to read status
Parameters
Parameter Type Required? Format Description
ids[] array of strings true List of ids
Status Codes
Status Code Description
200
Returned when successful
403
Returned when the user is not authorized
405
Method not allowed

/v2/whatsapp/incoming/{id}

GET /v2/whatsapp/incoming/{id} beta since v2
Documentation
Get an incoming message
Requirements
Name Requirement Type Description
id
Return
Parameter Type Versions Description
id integer >=v2 Message id
from string >=v2 From
to string >=v2 To
message string >=v2 Message
createdDate DateTime >=v2 Created date
Status Codes
Status Code Description
200
Returned when successful
403
Returned when the user is not authorized
405
Method not allowed

/v2/whatsapp/message

GET /v2/whatsapp/message beta since v2

Documentation

Get list of outgoing messages

Filters

Name	Information
offset	Requirement \d+ Description Pagination offset (default 1, maximum offset + limit = 10,000) Default 1
limit	Requirement \d+ Number of items to return (default 20, maximum 1000) Default 20
startDate	Requirement Description Start date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
endDate	Requirement Description End date of the date range filter. Date format <Y-m-d H:i:s> in account timezone
destination	Requirement \d+ Description The shared pool or dedicated number which the sms was sent to
origin	Requirement \d+ Description The number where the SMS appears to come from
search	Requirement Description Search string in source, destination and message

Return

Parameter	Type	Versions	Description
messages[]	array of objects (WhatsappMessage)	>=v2	A collection of message objects
messages[][id]	integer	>=v2	Message id
messages[][recipient]	string	>=v2	Recipient
messages[][status]	string	>=v2	Status
messages[][state]	string	>=v2	State
messages[][message]	string	>=v2	Message
messages[][createdDate]	DateTime	>=v2	Created date

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the user is not authorized
405	Method not allowed

POST /v2/whatsapp/message beta since v2
Documentation
Send a message
Parameters
Parameter Type Required? Format Description
to[] array of strings true List of destination
message string true
Return
Parameter Type Versions Description
id integer >=v2 Message id
recipient string >=v2 Recipient
status string >=v2 Status
state string >=v2 State
message string >=v2 Message
createdDate DateTime >=v2 Created date
Status Codes
Status Code Description
200
Returned when successful
403
Returned when the user is not authorized
405
Method not allowed

/v2/whatsapp/message/{id}

GET /v2/whatsapp/message/{id} beta since v2
Documentation
Get an outgoing message
Requirements
Name Requirement Type Description
id
Return
Parameter Type Versions Description
id integer >=v2 Message id
recipient string >=v2 Recipient
status string >=v2 Status
state string >=v2 State
message string >=v2 Message
createdDate DateTime >=v2 Created date
Status Codes
Status Code Description
200
Returned when successful
403
Returned when the user is not authorized
405
Method not allowed

/v2/whatsapp/opt-in

GET /v2/whatsapp/opt-in beta since v2

Documentation

Show opted in numbers

Return

Parameter	Type	Versions	Description
optIn[]	array of objects (WhatsappOptIn)	>=v2	A collection of opt-in objects
optIn[][name]	string	>=v2	Name
optIn[][number]	string	>=v2	Number
optIn[][capable]	boolean	>=v2	Capability
optIn[][blacklist]	boolean	>=v2	Notification blacklist

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the user is not authorized
405	Method not allowed

POST /v2/whatsapp/opt-in beta since v2

Documentation

Opt in numbers

Parameters

Parameter	Type	Required?	Description
opt-in[]	array of objects (WhatsappOptInExtendedType)	true	A collection of opt in
opt-in[][name]	string	false
opt-in[][number]	string	true

Return

Parameter	Type	Versions	Description
optIn[]	array of objects (WhatsappOptIn)	>=v2	A collection of opt-in objects
optIn[][name]	string	>=v2	Name
optIn[][number]	string	>=v2	Number
optIn[][capable]	boolean	>=v2	Capability
optIn[][blacklist]	boolean	>=v2	Notification blacklist

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the user is not authorized
405	Method not allowed

/v2/whatsapp/opt-out

POST /v2/whatsapp/opt-out beta since v2
Documentation
Opt out numbers
Parameters
Parameter Type Required? Format Description
numbers[] array of strings true List of numbers
Status Codes
Status Code Description
200
Returned when successful
403
Returned when the user is not authorized
405
Method not allowed

Parameter	Type	Required?	Format	Description
to[]	array of strings	true		List of destination
message	string	true

Introduction

REST API Scroll to Top ▲

Authentication Scroll to Top ▲

Response Codes Scroll to Top ▲

Message Object Types Scroll to Top ▲

Template message

Text message

Image message

Video message

Document message

Audio message

Location message

Accepted media types

API Endpoints Scroll to Top ▲

whatsapp

/v2/whatsapp/blacklist

POST /v2/whatsapp/blacklist beta since v2

/v2/whatsapp/capabilities

POST /v2/whatsapp/capabilities beta since v2

/v2/whatsapp/incoming

GET /v2/whatsapp/incoming beta since v2

/v2/whatsapp/incoming/read

POST /v2/whatsapp/incoming/read beta since v2

/v2/whatsapp/incoming/{id}

GET /v2/whatsapp/incoming/{id} beta since v2

/v2/whatsapp/message

GET /v2/whatsapp/message beta since v2

POST /v2/whatsapp/message beta since v2

/v2/whatsapp/message/{id}

GET /v2/whatsapp/message/{id} beta since v2

/v2/whatsapp/opt-in

GET /v2/whatsapp/opt-in beta since v2

POST /v2/whatsapp/opt-in beta since v2

/v2/whatsapp/opt-out

POST /v2/whatsapp/opt-out beta since v2

Early Access

WhatsApp Business API