SMSBOX - WhatsApp API Documentation (2.2.0)

Changelog

Version Date Changes
2.3.0 05/16/2025 ๐Ÿ†• New Templates List resource and Error Incoming webhook added. You can now view IPs sending webhooks in the webhook section.
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

Content type
application/json
{
  • "recipients": [
    ],
  • "contentMessage": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "recipients": [
    ],
  • "contentMessage": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "recipients": [
    ],
  • "contentMessage": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "recipients": [
    ],
  • "contentMessage": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "type": "interactive",
  • "interactive": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "type": "interactive",
  • "interactive": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

Template

Get all templates

Authorizations:
ApiKey
path Parameters
wabaId
required
string

WhatsApp Business Agent ID

phoneId
required
string

WhatsApp Business Agent's Phone Number ID

Responses

Request samples

curl --request GET \
	--url https://api.wababox.net/waba/1.1/json/<WABAID>/template/<PHONEID> \
	--header 'Authorization: App <APIKEY>' \
	--header 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "List of the agent's templates",
  • "data": [
    ]
}

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

Content type
application/json
{
  • "recipients": [
    ],
  • "contentMessage": {
    }
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "message_id": "wamid.xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "status": "read"
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Request accepted for processing.",
  • "reference": "XXXXXXXXXXXXXX",
  • "recipients": [
    ]
}

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

Content type
application/json
{
  • "file_id": "1234567890"
}

Response samples

Content type
application/json
{
  • "response": {
    },
  • "details": "Done.",
  • "data": {
    }
}

Webhooks

Important:

You should pay close attention to the requestType properties in your webhook payload.
If you are using a firewall, make sure to allow this IPv4 address (this is the address that emits the webhooks):

  • 37.59.198.135
  • 178.33.185.51
  • 54.36.93.79
  • 54.36.93.80
  • 62.4.31.47
  • 62.4.31.48

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

Content type
application/json
{
  • "data": {
    },
  • "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

Content type
application/json
{
  • "data": {
    },
  • "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

Content type
application/json
{
  • "data": {
    },
  • "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

Content type
application/json
{
  • "data": {
    },
  • "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

Content type
application/json
{
  • "data": {
    },
  • "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

Content type
application/json
{
  • "data": {
    },
  • "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

Content type
application/json
{
  • "data": {},
  • "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"
}

Incoming error Webhook

This webhook will be present if an error occurs when a user submits a document, image, or other file. In this case, a Error incoming type webhook will be triggered, and the errors property will contain a JSON object with the error details.

Request Body schema: application/json
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_error"
object

Responses

Request samples

Content type
application/json
{
  • "wabaId": "xxxxxx",
  • "phoneId": "xxxxxx",
  • "phoneNumber": "xxxxxx",
  • "clientId": 123456,
  • "requestProd": "WABA",
  • "requestDate": "2024-06-01T14:00:00+02:00",
  • "requestUUID": "xxxxxx",
  • "requestType": "incoming_error",
  • "data": {
    }
}