Developer References
WhatsApp Business API is a communication solution that provides media-rich white-label messaging via one of the world’s most prominent OTT messaging channels. Our clients now have the opportunity to reach WhatsApp’s 2 billion monthly active users through a sophisticated, easy-to-use integration.
SMSGlobal’s WhatsApp Business API provides a robust gateway for our clients to utilize enterprise messaging on WhatsApp. With the opportunity to reach WhatsApp’s notable 2 billion monthly active users, this API allows trusted businesses to connect with customers directly.
Integrate SMSGlobal’s WhatsApp Business API to established backend systems and enable all the possibilities of rich, contextual, business-grade communication on WhatsApp.
The REST API allows programmatic access to SMSGlobal features in MXT. To use the REST API, you will need an MXT account and an API key and secret. You can generate these inside your MXT account. The REST API can be accessed at api.smsglobal.com. Use of SSL is supported and strongly encouraged. The REST API takes full advantage of all HTTP headers. Each part of a request and response is meaningful, including the request method (GET/POST, etc.), the individual headers (Location, Content-Type, Accept, etc.), and the response status code (200, 400, 404, etc.). Use of this API assumes a working knowledge of these HTTP components, and general use of RESTful web APIs.
The REST API uses an authentication scheme based on this OAuth 2 specification . All requests to resources (excluding the schema pages) must be accompanied by a correct Authorization header as per this specification. The header looks like this:
Authorization: MAC id="your API key", ts="1325376000", nonce="random-string", mac="base64-encoded-hash"The following response codes apply to all requests. Check each request type in the list below for more response codes specific to that request.
| Status Code | Meaning | Scenario |
|---|---|---|
| 200 | OK | 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 |
The types of messages that can be sent include the following:
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value template. | String | N/A | N/A | Yes |
| template_name | Name of the template. | String | N/A | 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. | No |
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value text | String | N/A | N/A | Yes |
| preview_url | Message object | Boolean | false | true or false | No |
| Text | The text message content | String | N/A | Valid URL | Yes |
Accepted content types can be found in the table below
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value image | String | N/A | 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 | No |
Accepted content types can be found in the table below
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value video | String | N/A | 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 | No |
Accepted content types can be found in the table below
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value document | String | N/A | 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 | No |
| caption | Optional caption that will be displayed as the document title. | String | None | N/A | No |
Accepted content types can be found in the table below
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value audio | String | N/A | 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 |
JSON object parameters:
| Name | Description | JSON Type | Default | Constraints | Required |
|---|---|---|---|---|---|
| type | Constant value location | String | N/A | 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 | N/A | No |
| address | The address for the location. Will be displayed in the message. | String | N/A | N/A | No |
| Message Type | Supported content types | Post-processing size limit |
|---|---|---|
| document | Any content type listed for other message types, | 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 |
Block messages from number(s)
| Parameter | Type | Required? | Format | Description |
|---|---|---|---|---|
| numbers[] | array of strings | true | List of numbers |
| Status Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Check capability of number(s) to receive messages
| Parameter | Type | Required? | Format | Description |
|---|---|---|---|---|
| numbers[] | array of strings | true | List of numbers |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Get list of incoming messages
| 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 |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Update incoming message(s) to read status
| Parameter | Type | Required? | Format | Description |
|---|---|---|---|---|
| ids[] | array of strings | true | List of ids |
| Status Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Get an incoming message
| Name | Requirement | Type | Description |
|---|---|---|---|
| id |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Get list of outgoing messages
| 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 |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Send a message
| Parameter | Type | Required? | Format | Description |
|---|---|---|---|---|
| to[] | array of strings | true | List of destination | |
| message | string | true |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Get an outgoing message
| Name | Requirement | Type | Description |
|---|---|---|---|
| id |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Show opted in numbers
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Opt in numbers
| Parameter | Type | Required? | Format | Description |
|---|---|---|---|---|
| opt-in[] | array of objects (WhatsappOptInExtendedType) | true | A collection of opt in | |
| opt-in[][name] | string | false | ||
| opt-in[][number] | string | true |
| 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 Code | Description |
|---|---|
| 200 |
|
| 403 |
|
| 405 |
|
Opt out numbers
| Parameter | Type | Required? | Format | Description |
|---|---|---|---|---|
| numbers[] | array of strings | true | List of numbers |
Live demonstations of our MXT platform are conducted over Google Meets by our friendly tech support team and generally take 15mins.