SMSBOX - WhatsApp API Documentation (2.2.0)

Changelog

Version	Date	Changes
2.2.0	01/31/2025	📌 Add `reference` and `recipients` attributes in the response of the `message` resource and add URL versioning (`waba/1.1/json`)
2.1.0	10/03/2024	👩🏻‍💻 Add interactive list and interactive button group for Whatsapp API.
2.0.0	06/28/2024	📞 Start of the SMSBOX Documentation on github with our `Whatsapp API documentation`.

Message

Send text message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Text)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "text",
"text": {"body": "Message sent via my WhatsApp Business agent."
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send audio message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Audio)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "audio",
"audio": {"link": "https://www.example.com/fr/file.mp3",
"filename": "file.mp3"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send document message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Document)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "document",
"document": {"link": "https://www.example.com/fr/file.pdf",
"filename": "file.pdf"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send image message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Image)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "image",
"image": {"link": "https://www.example.com/fr/file.jpeg",
"filename": "file.jpeg"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send sticker message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Sticker)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "sticker",
"sticker": {"link": "https://www.example.com/fr/file.webp",
"filename": "file.webp"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send video message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Video)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "video",
"video": {"link": "https://www.example.com/fr/file.mp4",
"filename": "file.mp4"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send location message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (Location)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "location",
"location": {"longitude": 6.075501230687077,
"latitude": 43.08811078662267,
"name": "SMSBOX",
"address": "20 Av. Élie Gautier, 83320 Carqueiranne"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send reply text message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (ReplyText)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "text",
"context": {"message_id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
},
"text": {"body": "Reply to a previous message."
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send reaction message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (ReplyReaction)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "reaction",
"reaction": {"message_id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"emoji": "😀"
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Interactive

Send interactive button message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

type required	string Value: "interactive"
required	object

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"type": "interactive",
"interactive": {"type": "button",
"header": {"type": "text",
"text": {"body": "Message sent via my WhatsApp Business agent."
}
},
"body": {"text": "string"
},
"footer": {"text": "string"
},
"action": {"buttons": [{"type": "reply",
"reply": {"id": "string",
"title": "string"
}
}
]
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Send interactive list message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

type required	string Value: "interactive"
required	object

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"type": "interactive",
"interactive": {"type": "list",
"header": {"type": "text",
"text": "string"
},
"body": {"text": "string"
},
"footer": {"text": "string"
},
"action": {"button": "string",
"sections": [{"title": "string",
"rows": [{"id": "string",
"title": "string",
"description": "string"
}
]
}
]
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Template

Send OTP message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

recipients	Array of strings <= 5000 items
	object (OTPTemplateMessage)

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"recipients": ["+336XXXXXXXX"
],
"contentMessage": {"type": "template",
"template": {"name": "otp",
"language": {"code": "en"
},
"components": [{"type": "body",
"parameters": [{"type": "text",
"text": "123456"
}
]
},
{"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [{"type": "text",
"text": "123456"
}
]
}
]
}
}
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

Event

Send read message status

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

message_id	string Received message ID
status	string Value: "read"

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"message_id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "read"
}

Response samples

Content type

application/json

{"response": {"response_code": "202",
"response_desc": "Request successfully queued."
},
"details": "Request accepted for processing.",
"reference": "XXXXXXXXXXXXXX",
"recipients": [{"submitted": "+33xxxxxxxxx",
"rewrited": "33xxxxxxxxx",
"state": "ACCEPTED",
"reason_code": "PROCESSING"
}
]
}

File

Retrieve file received in a message

Authorizations:

ApiKey

path Parameters

wabaId required	string WhatsApp Business Agent ID
phoneID required	string WhatsApp Business Agent's Phone Number ID

Request Body schema: application/json
required

file_id

required

string

File ID received via webhook

Responses

Request samples

Payload
cURL
Python
JavaScript
PHP

Content type

application/json

{"file_id": "1234567890"
}

Response samples

Content type

application/json

{"response": {"response_code": "200",
"response_desc": "Request successfully processed."
},
"details": "Done.",
"data": {"mime_type": "application/pdf",
"sha256": "string",
"file_size": "string",
"caption": "string",
"raw": "data:application/pdf;base64,xxxxxxxxxxxxxxxxxx"
}
}

Webhooks

Important:

When a client or user submits an image, video, or other file that does not comply with the WhatsApp Business limitations, the WhatsApp agent is notified via a text type webhook with the details of the encountered error.

For example: Failed to download incoming media due to internal error. Because a client attempted to submit a document larger than 100 MB.

It is recommended to monitor this type of webhook.

Text Webhook

Request Body schema: application/json

	object
wabaId	string WhatsApp Business Agent ID
phoneId	string WhatsApp Business Agent's Phone Number ID
phoneNumber	string WhatsApp Business Agent's Phone Number
clientId	integer SMSBOX user account ID
requestProd	string Channel Value: "WABA"
requestDate	string <date-time> Datetime of the sent message
requestUUID	string <uuid>
requestType	string Value: "incoming_message"

Responses

Request samples

Payload

Content type

application/json

{"data": {"from": "33XXXXXXXXX",
"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "1719576000",
"text": {"body": "Hello 🙂"
},
"type": "text",
"is_error": "yes"
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "incoming_message"
}

Document Webhook

Request Body schema: application/json

	object
wabaId	string WhatsApp Business Agent ID
phoneId	string WhatsApp Business Agent's Phone Number ID
phoneNumber	string WhatsApp Business Agent's Phone Number
clientId	integer SMSBOX user account ID
requestProd	string Channel Value: "WABA"
requestDate	string <date-time> Datetime of the sent message
requestUUID	string <uuid>
requestType	string Value: "incoming_message"

Responses

Request samples

Payload

Content type

application/json

{"data": {"from": "33XXXXXXXXX",
"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "1719576000",
"type": "document",
"document": {"filename": "filename.pdf",
"mime_type": "application/pdf",
"sha256": "string",
"id": "1234567890",
"caption": "string"
}
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "incoming_message"
}

Image Webhook

Request Body schema: application/json

	object
wabaId	string WhatsApp Business Agent ID
phoneId	string WhatsApp Business Agent's Phone Number ID
phoneNumber	string WhatsApp Business Agent's Phone Number
clientId	integer SMSBOX user account ID
requestProd	string Channel Value: "WABA"
requestDate	string <date-time> Datetime of the sent message
requestUUID	string <uuid>
requestType	string Value: "incoming_message"

Responses

Request samples

Payload

Content type

application/json

{"data": {"from": "33XXXXXXXXX",
"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "1719576000",
"type": "image",
"image": {"mime_type": "image/jpeg",
"sha256": "string",
"id": "1234567890",
"caption": "string"
}
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "incoming_message"
}

Video Webhook

Request Body schema: application/json

	object
wabaId	string WhatsApp Business Agent ID
phoneId	string WhatsApp Business Agent's Phone Number ID
phoneNumber	string WhatsApp Business Agent's Phone Number
clientId	integer SMSBOX user account ID
requestProd	string Channel Value: "WABA"
requestDate	string <date-time> Datetime of the sent message
requestUUID	string <uuid>
requestType	string Value: "incoming_message"

Responses

Request samples

Payload

Content type

application/json

{"data": {"from": "33XXXXXXXXX",
"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "1719576000",
"type": "video",
"video": {"caption": "string",
"mime_type": "video/mp4",
"sha256": "string",
"id": "1234567890"
}
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "incoming_message"
}

Reaction Webhook

Request Body schema: application/json

	object
wabaId	string WhatsApp Business Agent ID
phoneId	string WhatsApp Business Agent's Phone Number ID
phoneNumber	string WhatsApp Business Agent's Phone Number
clientId	integer SMSBOX user account ID
requestProd	string Channel Value: "WABA"
requestDate	string <date-time> Datetime of the sent message
requestUUID	string <uuid>
requestType	string Value: "incoming_message"

Responses

Request samples

Payload

Content type

application/json

{"data": {"from": "33XXXXXXXXX",
"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "1719576000",
"type": "reaction",
"reaction": {"message_id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"emoji": "👍"
}
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "incoming_message"
}

Location Webhook

Request Body schema: application/json

	object
wabaId	string WhatsApp Business Agent ID
phoneId	string WhatsApp Business Agent's Phone Number ID
phoneNumber	string WhatsApp Business Agent's Phone Number
clientId	integer SMSBOX user account ID
requestProd	string Channel Value: "WABA"
requestDate	string <date-time> Datetime of the sent message
requestUUID	string <uuid>
requestType	string Value: "incoming_message"

Responses

Request samples

Payload

Content type

application/json

{"data": {"from": "33XXXXXXXXX",
"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "1719576000",
"type": "location",
"location": {"address": "20 Av. Élie Gautier, 83320 Carqueiranne",
"latitude": 43.0875153,
"longitude": 6.0754154,
"name": "SMSBOX",
"url": "https://foursquare.com/xxxxx"
}
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "incoming_message"
}

Message status Webhook

Message status

Request Body schema: application/json

required	object
wabaId required	string WhatsApp Business Agent ID
phoneId required	string WhatsApp Business Agent's Phone Number ID
phoneNumber required	string WhatsApp Business Agent's Phone Number
clientId required	integer SMSBOX user account ID
reference required	integer Internal ID of the sent message
requestProd required	string Channel
requestDate required	string <date-time> Datetime of the sent message
requestUUID required	string <uuid>
requestType required	string Value: "status_update"

Responses

Request samples

Payload

Content type

application/json

{"data": {"id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"status": "failed",
"timestamp": "1719576000",
"recipient_id": "33XXXXXXXXX",
"errors": [{"code": 131047,
"title": "Title of the error.",
"message": "Error message.",
"error_data": {"details": "Detaiils of the error.",
"href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
}
}
]
},
"wabaId": "xxxxxx",
"phoneId": "xxxxxx",
"phoneNumber": "xxxxxx",
"clientId": 123456,
"reference": 1234567890,
"requestProd": "WABA",
"requestDate": "2024-06-01T14:00:00+02:00",
"requestUUID": "xxxxxx",
"requestType": "status_update"
}

SMSBOX - WhatsApp API Documentation (2.2.0)

Changelog

Message

Send text message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send audio message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send document message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send image message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send sticker message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send video message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send location message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send reply text message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send reaction message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Interactive

Send interactive button message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Send interactive list message

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required