Plain text
Notes
- No major changes in the JSON structure for sending plain text messages via the One API.
- A new ‘channel‘ parameter is used for specifying the channel over which the message must be sent if you have multiple channels linked to an One API integration.
- Required encoding for WhatsApp remains UTF-8.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
POST /wa/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-Wa-API-key]
JSON request body:
{
"messages": [
{
"to": "27999000001",
"content": "Here is an example message",
"clientMessageId": "Customer-Message-Id"
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-Wa-API-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "27999000001",
"content": "Here is an example message",
"clientMessageId": "Customer-Message-Id"
}
]
}
|
Content-Type: application/json
Authorization: [Customer-Direct-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "27999000001",
"content": "4wIHuMqqKIb7poTZfn3FzVA58KT8X8pwmBHw2YiufwuMwn53enhNA8ppfrW/V1LcVnY+ZJ8aHZ0CONWSASaYSg/PGhXRQJAM3g/aq5O3HEmzl6kPUZXNjVsbuiHnXeLW",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwFtLrfBKLlvhXd57szd4Bz1AAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMugYYXnQAUKo9zIy3AgEQgDunOyaASkPc8vpgZ0kA6W/OnrbqodTiNWOZfy6Uj6aY1jk3gPUrTWqhyedSgAp5K4Hi4/0XsAWN6LxpJA=="
}
]
}
|
 |
| |
Success response |
Success response |
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "a4b828469b0a40f29efb1524892b23d9",
"accepted": true,
"to": "27999000001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "25a46c36ebd246369f735da77583844e",
"accepted": true,
"to": "27999000001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
Plain text – with preview first URL
Notes
- No major changes in the JSON structure for sending plain text messages via the One API.
- A new ‘channel‘ parameter is used for specifying the channel over which the message must be sent if you have multiple channels linked to an One API integration.
- Required encoding for WhatsApp remains UTF-8.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
POST /wa/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-Wa-API-key]
JSON request body:
{
"messages": [
{
"to": "27999000001",
"content": "Here is an example message with a URL https://www.facebook.com",
"previewFirstUrl": true,
"clientMessageId": "Customer-Message-Id"
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "27999000001",
"content": "Here is an example message with a URL https://www.facebook.com",
"previewFirstUrl": true,
"clientMessageId": "Customer-Message-Id"
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-Wa-API-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "27999000001",
"content": "JMj1C5XlC1+tTGZrIHp9JAis+A/ar2rvzQrVoWME038LfdIVzx9+TWntOX5J/h76L+bE+Qf0vERm7L5v+5syP1lezI2uaQIiIrWgoPZB5MI=",
"previewFirstUrl": true,
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwFxyLWSUAOfn2FSdi7tHX3zAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMVvCglm6CoRWaZFmUAgEQgDswBsX7D2cRThRWoypriPx2dmuwssxizdD+MhM1oqQRLuvC3lVLt1nAp1bYNe7NRnFzJ/waPmZa/E/GIg=="
}
]
}
|
 |
|
|
Success response
|
Success response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "12d960e2b249454d8f2916062d3ee2c7",
"accepted": true,
"to": "27999000001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "707d3ea51ff84afda82d82f512581d9e",
"accepted": true,
"to": "27999000001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
Inline media
Notes
- The ‘contentType’ and ‘caption’ parameters have been moved into a ‘media’.
- The ‘content’ parameter that contains the base64 encoded binary file data remains in the ‘messages‘ object.
Restrictions
- A single media file in an inline media message request has a limit of 20MB
- The total request payload size is limited at 30MB
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
POST /wa/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-Wa-API-key]
JSON request body:
{
"messages": [
{
"to": "27999000001",
"contentType": "image/png",
"content": "Base64 Encoded Binary File Data",
"caption": "File Caption",
"clientMessageId": "Customer-Message-Id"
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"content": "Base64 Encoded Binary File Data",
"media": {
"contentType": "image/png",
"fileName": "myfilename.png",
"caption": "File Caption"
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"content": "Base64 Encoded - Encrypted Binary File Data",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwH4kNy6xp2F8zxQbWccpxKEAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMKCiX0wtLihg3xuopAgEQgDtETtj8f3S+rAnwyIxe91ctZOCADFWDxHmFHWmQGMO2egqARTubydLW7YZxaw6LHE2S5ob0qpL5iMHE1Q==",
"media": {
"contentType": "image/png",
"fileName": "myfilename.png",
"caption": "WoBbuFeAUoqxmUxoJv90OmHjPFLZZVPbbFEOTzD8jeI=",
"sha256Hash": "529fd5482f43db39992a894bbe4216f51a4d724131a97b93cc5589433b545820"
}
}
]
}
|
 |
|
|
Success response
|
Success response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "695a996295d24cc3944360ba7168d333",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "5defc030df5c425ca2bb216567c2d091",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
Media file upload
Notes
-
This is used to upload media files to the Clickatell server. In response to the upload, you will receive a ‘fileId‘ that will be required in the media file sending request to reference the media file instead of including the base64 encoded binary data inline with the JSON request.
-
The media file data that is sent to the Clickatell server must be raw binary data as read from the file stream, and not base64 encoded.
-
The HTTP parameter
-
The HTTP parameter ‘broadcastAllowed=true’ is specified in the request if the file does not contain any personal information and the business need to send the same file to multiple end-users. Note that a file uploaded for broadcasting is available for 30 days on the Clickatell servers from the day of upload.
-
The ‘Content-Type’ HTTP header is required to specify the content type of the raw binary data stream if that is being uploaded.
-
The ‘Authorization’ HTTP header containing the API key for the integration is required, as it is only allowed to send an uploaded media file via the WhatsApp business number for which it was uploaded.
-
All file types will be accepted by the media upload endpoint. File type limitations will be enforced on the actual message-sending API call.
Restrictions
-
It is not allowed to send a media file uploaded with the broadcasting flag with any template message containing media.
-
The media file size limitation on One API is 30MB per file upload. Note that in conjunction with this restriction, WhatsApp also enforces size restrictions per media type.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
Request detail
|
Request detail
|
Not applicable. No actual messages are sent to the handset when media files are uploaded to Clickatell’s server.
|
|
POST /v1/media
HTTP Headers:
Content-Type: [Actual-File-Content-Type]
Authorization: [Customer-OneAPI-key]
Request parameters (always ensure that parameter values are URL encoded):
1) Media file upload for sending to defined user:
fileName=[filename.extension]
to=2799900001
2) Media file uploaded for broadcasting to multiple users:
fileName=[filename.extension]
broadcastAllowed=true
Request body:
Raw binary file data
|
POST /v1/media
HTTP Headers:
Content-Type: [Actual-File-Content-Type]
Authorization: [Customer-OneAPI-key]
Request parameters (always ensure that parameter values are URL encoded):
1) Media file upload for sending to defined user:
fileName=[filename.extension]
to=2799900001
encryptionKey=[BASE64-ENCODED-ENCRYPTION-KEY]
kmsArn=[AWS-KMS-MT-ARN]
sha256FileHash=[SHA256-FILE-HASH]
2) Media file uploaded for broadcasting to multiple users:
fileName=[filename.extension]
broadcastAllowed=true
encryptionKey=[BASE64-ENCODED-ENCRYPTION-KEY]
kmsArn=[AWS-KMS-MT-ARN]
sha256FileHash=[SHA256-FILE-HASH]
Request body:
Raw encrypted binary file data
|
|
Request Examples
|
Request Examples
|
|
1) Example curl call to upload an image for sending to one defined user:
curl -X POST \
-H "Authorization: [Customer-OneAPI-key]" \
-H 'Content-Type: image/jpg' \
--data-binary @myFilename.jpg \
"https://platform.clickatell.com/v1/media?fileName=myFilename.jpg&to=2799900001"
2) Example curl call to upload an image for broadcasting to multiple users:
curl -X POST \
-H "Authorization: [Customer-OneAPI-key]" \
-H 'Content-Type: image/jpg' \
--data-binary @myFilename.jpg \
"https://platform.clickatell.com/v1/media?fileName=myFilename.jpg&broadcastAllowed=true"
|
1) Example curl call to upload an image for sending to one defined user:
curl -X POST \
-H "Authorization: [Customer-OneAPI-key]" \
-H 'Content-Type: image/jpg' \
--data-binary @myEncryptedFilename.jpg \
"https://platform.clickatell.com/v1/media?https://platform.clickatell.com/v1/media?fileName=myEncryptedFilename.jpg&to=2799900001&encryptionKey=AQIDAHigcx4kN%2BSNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwG%2BGsUGTTvg84B0DGcrKziKAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQML5a3jpKpnd6J5753AgEQgDtdefpq9YRdlqqNX7lixas5XQZuXtnPb8UficO43DwuWRaPvc1D%2BEGKLtlwTVtpbo%2B3GzWYMnW837%2BSMA%3D%3D&kmsArn=arn%3Aaws%3Akms%3Aeu-west-1%3A748156735851%3Akey%2Faa09fa21-6166-4fe2-bb1f-9874a7f7561e&sha256FileHash=529fd5482f43db39992a894bbe4216f51a4d724131a97b93cc5589433b545820"
2) Example curl call to upload an image for broadcasting to multiple users:
curl -X POST \
-H "Authorization: [Customer-OneAPI-key]" \
-H 'Content-Type: image/jpg' \
--data-binary @myEncryptedFilename.jpg \
"https://platform.clickatell.com/v1/media?fileName=myEncryptedFilename.jpg&broadcastAllowed=true&encryptionKey=AQIDAHigcx4kN%2BSNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwFWoKBkAcY%2BIFRiGHmyz0ngAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMGYsxwlvkvFsc%2B53SAgEQgDsXWAl9vLsasn89P5ATPvZfgWO8sQPZLhSq1pP9fLZNdzvxOeNN0IiR0qtxTdhYf5c00FKFs5I4vImrMw%3D%3D&kmsArn=arn%3Aaws%3Akms%3Aeu-west-1%3A748156735851%3Akey%2Faa09fa21-6166-4fe2-bb1f-9874a7f7561e&sha256FileHash=529fd5482f43db39992a894bbe4216f51a4d724131a97b93cc5589433b545820"
|
|
Success Response
|
Success Response
|
|
HTTP 201
{
"fileId" : "uuid.xxx",
"accepted" : true,
"error" : null
}
|
HTTP 201
{
"fileId" : "uuid.xxx",
"accepted" : true,
"error" : null
}
|
Sending media by reference
Notes
-
Note that the ‘contentType‘ parameter no longer forms part of the ‘media’ object in the One API request, as the content type was specified when the media file was uploaded to the Clickatell server.
-
The ‘fileId’ parameter as received from the media upload API call will serve as the input to the ‘fileId’ in the media object in this send media message request.
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"media": {
"fileId": "UUID.xxx",
"caption": "File Caption"
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwFtLrfBKLlvhXd57szd4Bz1AAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMugYYXnQAUKo9zIy3AgEQgDunOyaASkPc8vpgZ0kA6W/OnrbqodTiNWOZfy6Uj6aY1jk3gPUrTWqhyedSgAp5K4Hi4/0XsAWN6LxpJA==",
"media": {
"fileId": "UUID.xxx",
"caption": "4wIHuMqqKIb7poTZfn3FzVA58KT8X8pwmBHw2YiufwuMwn53enhNA8ppfrW/V1LcVnY+ZJ8aHZ0CONWSASaYSg/PGhXRQJAM3g/aq5O3HEmzl6kPUZXNjVsbuiHnXeLW"
}
}
]
}
|
|
|
Success Response
|
Success Response
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "135a9e6daf114381b3e0ce962a7a11a5",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "521aa7d226e04fdb8fe565bfd00b8267",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
Location
Notes
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"location": {
"longitude": "18.635891216806",
"latitude": "-33.881037287485",
"name": "Clickatell",
"address": "100 Edward Street, Bellville, Bellville, Western Cape 7530"
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwGgAG8uyZ4hYcwvCo2yA472AAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMFl7evO6frS5b2HuHAgEQgDvY/f8HN1PYPHDU2+F3StJtuddVfYz2vkoEfLFgJFFsXBcey0AxiY7L+BWqj3fAxJkAu3GjaJVeZVbK8g==",
"location": {
"longitude": "KJIgTSKD/CiAr80WVt+hHHKqPdKS3CjQahyUr7LsuU0=",
"latitude": "gMhEbJPyB7bQ8mwznV/2PaUmSkOtAPT1C4UDn+SKg4f0QTexyi4BaBTT24l56ur4",
"name": "8z6Y2LHZvb78yz0ZxkTsBAOQi1PcNorB5ad59qQ8TeE=",
"address": "vsxlSyHKBKoNNWEBI56x+iU7nSnNoOVRt4lUCB8hJAuyCugpVnxSoJpDhJARESPDFQH8IM0Mj/YcxMvMz2ajz1vmjspYeDalGAeoi+1JLAY="
}
}
]
}
|
 |
|
Success Response
|
Success Response
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "76b4b308bd134866af6cff20c79d1f16",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "8c966e77024244d2957274d57853f639",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
Contacts
Notes
-
A new contacts message (from the business to the handset user) is available on One API.
-
This message type is not available on the legacy WhatsApp API.
-
A business can send a single person/business or multiple persons/businesses contact information to a handset user in a single.
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
Minimal Contacts Info Example
|
Minimal Contacts Info Example
|
 |
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"contacts": [
{
"name": {
"firstName": "John",
"formattedName": "John Smith",
"lastName": "Smith"
},
"phones": [
{
"phone": "+1 (940) 555-1234",
"type": "HOME"
}
]
}
]
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"contacts": [
{
"name": {
"firstName": "D/ebgTU1x3vakOCj4RXdwvqjWBy6sKVL6269j0umeXc=",
"formattedName": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w=",
"lastName": "3qgOiMjuCpOwvXQoEjh/jNF3sK9deSI0ZuhsAKmlkFk="
},
"phones": [
{
"phone": "8D6H6gc5pzLjRKotRuHZiAqYyibhMpz/Nl+rmWJLfbkint+L8kLvdKQn6gqGksJU",
"type": "1iO02Td7gqDldkfUWhxoUn2EmYoT+4iTcn/Ayq5RrK4="
}
]
}
]
}
]
}
|
|
|
Full Info Contact Example
|
Full Info Contact Example
|
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"contacts": [
{
"addresses": [
{
"city": "Menlo Park",
"country": "United States",
"countryCode": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "HOME",
"zip": "94025"
},
{
"city": "Menlo Park",
"country": "United States",
"countryCode": "us",
"state": "CA",
"street": "200 Jefferson Dr",
"type": "WORK",
"zip": "94025"
}
],
"birthday": "2021-12-31",
"emails": [
{
"email": "test@fb.com",
"type": "WORK"
},
{
"email": "test@whatsapp.com",
"type": "WORK"
}
],
"name": {
"firstName": "John",
"formattedName": "John Smith",
"lastName": "Smith"
},
"org": {
"company": "WhatsApp",
"department": "Design",
"title": "Manager"
},
"phones": [
{
"phone": "+1 (940) 555-1234",
"type": "HOME"
},
{
"phone": "+1 (650) 555-1234",
"type": "WORK",
"wa_id": "16505551234"
}
],
"urls": [
{
"url": "https://www.facebook.com",
"type": "WORK"
}
]
}
]
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"contacts": [
{
"addresses": [
{
"city": "v99L33eLDQN/zAGU4kZQZZ5QxmDOz4/WnXnNK4Fk1x8=",
"country": "6tlfaFRPlPi+C2VTbafJ+AaTsVLmAJWQFb9v6mMdA8A=",
"countryCode": "EgLhANweQI3a5OGO2KlvkxWW4dsXavJgpSZLQ8SGH/I=",
"state": "DdyoraMPHgPxcoJTtpzUl525NLw00wSk2LKBzOKwpjc=",
"street": "YyPtMuFEuT4EzkWck4REZ/dOJBShfm30hbJHBcssc3Y=",
"type": "MaDV/PnCXPU94wlhB/sAJbgMUpKeSeiDvuXqk5HulxI=",
"zip": "7nvMRQwZBF/ArEe2AbBmRv7qJ2VrPdp2BRR7fCW0PgQ="
},
{
"city": "3zoNmELlPcfDtSPeCsFOqSyqhM1TQeYSMGRlmPjsnN4=",
"country": "TcpkonJPos1YGxLRCJImJtUfDvxQ/PomY1evrWFZLQQ=",
"countryCode": "YLuaC4pevJXvtmOBMLWjB9Rpj0c5IjqfvfanbNIv9gU=",
"state": "qXTEi5ZC3tUdPjGKr+ChJpXtpyaWuubZblHxNEEpGC8=",
"street": "84N8w7BE5acFPhmP8GJ8sE6oddHF8ZEl8OPl90YhkWqYvfiAMrEoDPbgR5Gr5MBr",
"type": "t1zX35vhZROmnY6tK/CzISZqKPEQ0KpQbA0VLo5iu4Q=",
"zip": "9PExw5nK1zCcp5o7ayUD2Oje/d1nqxfIHayoS6Og7g4="
}
],
"birthday": "fULKQkRQACWBSkUzfhQqvqyZcJYvtntSuKS0q8eG8GI=",
"emails": [
{
"email": "lAPkB/gcN5U67L4rtuX253iYQvkUCtnvzLR05d66hOg=",
"type": "/L5i3KbXhdj6OzFb3lOUonrrHHo3kNXREQ8u8QvNMIc="
},
{
"email": "oaeKFpxk2a/Z+PlT6/TaekUTNsNDXcRwp+4yNM3vaAi5xkNuh++cVn1SJfStTwSp",
"type": "ulZADNGT1e2z4cXGPOFzVUANfnK77TYw4E9JEfzXyME="
}
],
"name": {
"firstName": "D/ebgTU1x3vakOCj4RXdwvqjWBy6sKVL6269j0umeXc=",
"formattedName": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w=",
"lastName": "3qgOiMjuCpOwvXQoEjh/jNF3sK9deSI0ZuhsAKmlkFk="
},
"org": {
"company": "y88D0eOZzDvLrBk+Oa+FWxCBPD5bij15RellW1fTpDQ=",
"department": "iZg14767oYiaj+uNUU/3aG1Yxe8pStzRfhSLa6uTrUU=",
"title": "tcH0r/UWkIzFTk8jm1A8LkT2Y15vH57AYyMhsoKqNAk="
},
"phones": [
{
"phone": "8D6H6gc5pzLjRKotRuHZiAqYyibhMpz/Nl+rmWJLfbkint+L8kLvdKQn6gqGksJU",
"type": "1iO02Td7gqDldkfUWhxoUn2EmYoT+4iTcn/Ayq5RrK4="
},
{
"phone": "7WRYkjZY1UD+9dhU9ZFKZx1TeT0YbjnR4/3fPaSzl14WK4H40LuIwKZrxYe3iR2G",
"type": "Clwuyb2NbN6NEX9kATa1Kc1ALYjUeC6vrnPgR4HFgDA=",
"wa_id": "jUVisANnDTJKOSoHGbR5qyLEX9MHwdzp/5sj1zXGKBA="
}
],
"urls": [
{
"url": "J+4AuGCrFJHWG709u6SAKlvQfjFkbpk5uYVnd50GQyOAxHo5+9Cyrv9+xXlj1dq+",
"type": "YSx/d+90pye12MRJc0LEPhQL3NDwzmLuaYiaO48wE5I="
}
]
}
]
}
]
}
|
|
Success Response
|
Success Response
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "739434f210d74f92a81b586c4ac9a478",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "0d1164789c084c328dc1a38309924b55",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HSM (legacy support)
Notes
HSM could be deprecated in the future.
This message request type is seen as a legacy message type and should be replaced by the plain text template request type. See the ‘Templates – Plain text (NO header parameter)‘ message type section below.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
POST /wa/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-Direct-Wa-API-key]
JSON request body:
{
"messages": [
{
"to": "27999000001",
"clientMessageId": "Customer-Message-Id",
"hsm": {
"template": "welcome_notification_demo",
"parameters": {
"1": "Clickatell"
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"hsm": {
"template": "welcome_notification_demo",
"parameters": {
"1": "Clickatell"
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"hsm": {
"template": "welcome_notification_demo",
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w="
}
}
}
]
}
|
 |
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "65074f0ecc53430a9e3288469e0aadb0",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "557a922421ec467989b8c8bcd415db96",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
Templates
Notes
-
All template message types can be sent to the handset user outside of the 24 hour re-engagement window.
-
Template messages have additional costs associated with the message as determined by Facebook.
-
The handset user must opt-in to receive template messages as specified in the WhatsApp requirements.
-
Template parameters are now allowed to contain any:
-
\n, \t characters.
-
More than 4 consecutive spaces.
-
Character formatting.
-
The template message structure can contain formatting characters during template creation.
|
|
Templates – Plain text (NO header parameter)
Notes
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "welcome_notification_demo",
"body": {
"parameters": {
"1": "Clickatell"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "welcome_notification_demo",
"body": {
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w="
}
}
}
}
]
}
|
|
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "1bb69b30bca74171a759e3c5ede33a3a",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "93681a067f244b9fb32ca5ef4ec56c34",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Templates – Plain text (WITH header parameter)
Notes
-
You are only allowed to create text template headers with one (1) parameter. This means that the text.parameters cannot contain more than one (1) value.
-
The structure allows for more than key-value pair for future expansion if WhatsApp changes this restriction.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_header_with_text",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "February 2021"
}
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_header_with_text",
"2": "R13.00"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_header_with_text",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "lAPkB/gcN5U67L4rtuX253iYQvkUCtnvzLR05d66hOg="
}
}
},
"body": {
"parameters": {
"1": "D/ebgTU1x3vakOCj4RXdwvqjWBy6sKVL6269j0umeXc=",
"2": "3qgOiMjuCpOwvXQoEjh/jNF3sK9deSI0ZuhsAKmlkFk="
}
}
}
}
]
}
|
 |
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "11b5b4a66b6a4119afab2055f22958b1",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "1d0962d2924c4f539880f55dfca7a07d",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Template – media
Notes
-
WhatsApp currently supports sending media templates for video, image and document file types (see https://docs.clickatell.com/channels/one-api/supported-content-types/ for supported content types)
-
Media templates require that each media file reference in a template media message must be uploaded via the Clickatell media upload API call with the ‘to’ HTTP parameter on the media upload call matching the ‘to’ JSON parameter in the send media template message request.
-
The header.media.fileId parameter is the ‘fileId’ parameter as received in response to the media upload API call.
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_media_header_with_image",
"header": {
"type": "media",
"media": {
"fileId": "c45ada9b-8a51-4413-a134-928c2b085d31.jpg"
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_media_header_with_image",
"2": "R21.00"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_media_header_with_image",
"header": {
"type": "media",
"media": {
"fileId": "c568f4d91d7b45909a6461d2ee1715de.pdf"
}
},
"body": {
"parameters": {
"1": "D/ebgTU1x3vakOCj4RXdwvqjWBy6sKVL6269j0umeXc=",
"2": "fULKQkRQACWBSkUzfhQqvqyZcJYvtntSuKS0q8eG8GI="
}
}
}
}
]
}
|
 |
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
“messages”: [
{
“apiMessageId”: “8799d91cc4e640d490854fdc803445b1”,
“accepted”: true,
“to”: “2799900001”,
“clientMessageId”: “Customer-Message-Id”
}
],
“error”: null
}
|
HTTP 202
{
“messages”: [
{
“apiMessageId”: “5f7eb8d606124aedb7e23c0bba935dfd”,
“accepted”: true,
“to”: “2799900001”,
“clientMessageId”: “Customer-Message-Id”
}
],
“error”: null
}
|
|
Template – Interactive text suggested response (NO postbackData parameters)
Notes
-
A suggested response message template will present the handset user with a message where there are predefined buttons at the bottom of the message.
-
The buttons and button text are defined at the time of creating the template.
-
If no postbackData is defined in the send message request, the button text of the button pressed by the handset user will be used in the response message which will be received as a plain text message by the business.
-
The handset user can select one (1) or multiple/all of the buttons that is visible on the message. Each button is returned to the business as a separate message but will contain the same source message reference.
-
As soon as a button is selected, the button will be disabled and greyed out.
-
A text header is not a requirement for a suggested response template.
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_header_with_text_quick_reply",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "February 2021"
}
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_header_with_text_quick_reply",
"2": "R16.00"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_header_with_text_quick_reply",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "7nvMRQwZBF/ArEe2AbBmRv7qJ2VrPdp2BRR7fCW0PgQ="
}
}
},
"body": {
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w=",
"2": "9PExw5nK1zCcp5o7ayUD2Oje/d1nqxfIHayoS6Og7g4="
}
}
}
}
]
}
|
 |
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "8577a02bc3794d1298e7036d5e4387f9",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "53b3a1c2c85c49228ae93f8e34b4d478",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Template – Interactive text suggested response (WITH postbackData parameters)
Notes
- When postbackData is defined in the message request, the postbackData for the button pressed by the handset user will be passed back to the business in a suggested response inbound message.
- A handset user can select one (1) or multiple/all of the buttons that is visible on the message.
- Each button is returned to the business as a separate message but will contain the same source message reference.
- As soon as a button is selected, the button will be disabled and greyed out.
- A text header is not a requirement for a suggested response template.
Restrictions
- An interactive suggested response template can contain a maximum of three (3) buttons. This is a WhatsApp restriction.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_header_with_text_quick_reply",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "February 2021"
}
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_header_with_text_quick_reply",
"2": "R16.00"
}
},
"buttons": {
"suggestedResponse": {
"postbackData": {
"1": "{\"buttonPressed\":\"welcome_button1\"}",
"2": "{\"buttonPressed\":\"welcome_button2\"}",
"3": "{\"buttonPressed\":\"welcome_button3\"}"
}
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_header_with_text_quick_reply",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "7nvMRQwZBF/ArEe2AbBmRv7qJ2VrPdp2BRR7fCW0PgQ="
}
}
},
"body": {
"parameters": {
"1": "D/ebgTU1x3vakOCj4RXdwvqjWBy6sKVL6269j0umeXc=",
"2": "9PExw5nK1zCcp5o7ayUD2Oje/d1nqxfIHayoS6Og7g4="
}
},
"buttons": {
"suggestedResponse": {
"postbackData": {
"1": "3zoNmELlPcfDtSPeCsFOqSyqhM1TQeYSMGRlmPjsnN4=",
"2": "TcpkonJPos1YGxLRCJImJtUfDvxQ/PomY1evrWFZLQQ=",
"3": "qXTEi5ZC3tUdPjGKr+ChJpXtpyaWuubZblHxNEEpGC8="
}
}
}
}
}
]
}
|
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "1ccd1b083ce84f0d80c74dd481b68050",
"accepted": true,
"to": "27845362714",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "47618c32350c4f22972ade63d26d4d65",
"accepted": true,
"to": "27845362714",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Template – Interactive text action
Notes
-
An interactive action template can be created with a maximum of two (2) buttons. This template message allows a maximum of one (1) dial button and one (1) website URL button per template.
-
The dial button cannot be changed dynamically during message sending as this is not currently allowed by WhatsApp. When the user presses the dial button on the handset, the handset will open the dial pad on the user’s handset with the number populated.
-
The website URL button contains a base URL that is specified at the time of creating the template. With a dynamic URL message request, one (1) parameter can be specified and will be appended to the base URL on the user’s handset.
-
Currently, only one (1) parameter is allowed for the website URL button on an interactive action template message. This is a WhatsApp restriction.
-
When the handset user presses the website URL button, the user will be prompted if he wants to open the specified URL in his web browser.
-
The ‘listPosition’parameter is used to indicate if the websiteUrl button is located in the 1st or 2nd position of the template message as at the time of creating the action template.
-
This parameter is carried in the request to enable future expansion when WhatsApp might allow more than one dynamic website URL button on an action template message.
-
A text header is not a requirement for an interactive action template.
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
Dynamic URL
|
Dynamic URL
|
 |
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_header_with_text_dynamic_action",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "February 2021"
}
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_header_with_text_dynamic_action",
"2": "R14.00"
}
},
"buttons": {
"websiteUrl": [
{
"listPosition": 2,
"parameters": {
"1": "contact/contact-sales/"
}
}
]
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_header_with_text_dynamic_action",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "fULKQkRQACWBSkUzfhQqvqyZcJYvtntSuKS0q8eG8GI="
}
}
},
"body": {
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w=",
"2": "9PExw5nK1zCcp5o7ayUD2Oje/d1nqxfIHayoS6Og7g4="
}
},
"buttons": {
"websiteUrl": [
{
"listPosition": 1,
"parameters": {
"1": "YSx/d+90pye12MRJc0LEPhQL3NDwzmLuaYiaO48wE5I="
}
}
]
}
}
}
]
}
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "81542c76b9a146eca02f1e851b491f43",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "40231a9d4e344446a8baf624b0587550",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Static URL
|
Static URL
|
|
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id-2",
"template": {
"templateName": "test_header_with_text_dynamic_action",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "February 2021"
}
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_header_with_text_dynamic_action",
"2": "R14.00"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id-2",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_header_with_text_dynamic_action",
"header": {
"type": "text",
"text": {
"parameters": {
"1": "fULKQkRQACWBSkUzfhQqvqyZcJYvtntSuKS0q8eG8GI="
}
}
},
"body": {
"parameters": {
"1": "oaeKFpxk2a/Z+PlT6/TaekUTNsNDXcRwp+4yNM3vaAi5xkNuh++cVn1SJfStTwSp",
"2": "9PExw5nK1zCcp5o7ayUD2Oje/d1nqxfIHayoS6Og7g4="
}
}
}
}
]
}
|
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "cde6db6ee78045ba9fcc0db1af660c34",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id-2"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "497112220a1747c3aa0ee0d73980d4ed",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id-2"
}
],
"error": null
}
|
|
Template – Interactive media suggested response (NO postbackData parameters)
Notes
- WhatsApp currently supports sending media templates for video, image and document file types.
- Media templates require that each media file reference in a template media message must be uploaded via the media upload API call with the ‘to’HTTP parameter on the media upload call matching the ‘to’ JSON parameter in the send media template message request.
- The header.media.fileId parameter is the ‘fileId’parameter as received in response to the media upload API call.
- Button responses when pressed by the handset user will react the same as described for the ‘Template – Interactive text suggested response (NO postbackData parameters)‘message type.
Restrictions
- WhatsApp only allows the sending of PDF files for the ‘document’ media type.
- Audio file types are not
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_media_quick_reply_header_with_pdf",
"header": {
"type": "media",
"media": {
"fileId": "c45ada9b-8a51-4413-a134-928c2b085d31.pdf"
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_media_quick_reply_header_with_pdf",
"2": "R17.00"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_media_quick_reply_header_with_pdf",
"header": {
"type": "media",
"media": {
"fileId": "ddc2c4519d1a443ba2d99cc45b05cf6c.pdf"
}
},
"body": {
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w=",
"2": "fULKQkRQACWBSkUzfhQqvqyZcJYvtntSuKS0q8eG8GI="
}
}
}
}
]
}
|
 |
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "59e0e380ce25407da1feb50dc67030cc",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "fb3a88b985f44f7588c2890b45adfd5e",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Template – Interactive media suggested response (WITH postbackData parameters)
Notes
-
WhatsApp currently supports sending media templates for video, image and document file types.
-
Media templates require that each media file reference in a template media message must be uploaded via the media upload API call with the ‘to’ HTTP parameter on the media upload call matching the ‘to’ JSON parameter in the send media template message request.
-
The header.media.fileId parameter is the ‘fileId’ parameter as received in response to the media upload API call.
-
Button responses when pressed by the user will react the same as described for the ‘Template – Interactive text suggested response (WITH postbackData parameters)’ message type.
Restrictions
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "test_media_quick_reply_header_with_pdf",
"header": {
"type": "media",
"media": {
"fileId": "c45ada9b-8a51-4413-a134-928c2b085d31.pdf"
}
},
"body": {
"parameters": {
"1": "Msg 1 Template werner_test_media_quick_reply_header_with_pdf",
"2": "R17.00"
}
},
"buttons": {
"suggestedResponse": {
"postbackData": {
"1": "{\"buttonPressed\":\"welcome_button1\"}",
"2": "{\"buttonPressed\":\"welcome_button2\"}",
"3": "{\"buttonPressed\":\"welcome_button3\"}"
}
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "test_media_quick_reply_header_with_pdf",
"header": {
"type": "media",
"media": {
"fileId": "ddc2c4519d1a443ba2d99cc45b05cf6c.pdf"
}
},
"body": {
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w=",
"2": "fULKQkRQACWBSkUzfhQqvqyZcJYvtntSuKS0q8eG8GI="
}
},
"buttons": {
"suggestedResponse": {
"postbackData": {
"1": "ulZADNGT1e2z4cXGPOFzVUANfnK77TYw4E9JEfzXyME=",
"2": "tcH0r/UWkIzFTk8jm1A8LkT2Y15vH57AYyMhsoKqNAk=",
"3": "jUVisANnDTJKOSoHGbR5qyLEX9MHwdzp/5sj1zXGKBA="
}
}
}
}
}
]
}
|
|
|
Success Response
|
Success Response
|
|
|
HTTP 202
{
"messages": [
{
"apiMessageId": "fa155c76d83b4a77b88b72c13bea75c7",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 202
{
"messages": [
{
"apiMessageId": "228eda67522341edacb5e6d8d2520148",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
|
Templates – Plain text (WITH header parameter and no variable)
Notes
-
You are only allowed to create text template headers with one (1) parameter. This means that the text.parameters cannot contain more than one (1) value.
-
This example illustrates a request for a text template that has a static header defined with no variables. Note that the ‘text‘ parameter is defined as an empty object ‘{ }‘.
-
Changes to One API is currently in development to allow you to submit the request as per the example below or omit the ‘header‘ parameter from the request completely.
-
The structure allows for more than key value pair for future expansion if WhatsApp changes this restriction.
Online One API developer documentation
|
| Legacy WhatsApp API |
One API request (unencrypted) |
One API request (client-side encrypted) |
Visual example as seen on the end-users’ handset |
|
Not supported
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"template": {
"templateName": "template_header_0var_one_param",
"header": {
"type": "text",
"text": {}
},
"body": {
"parameters": {
"1": "8am-5pm"
}
}
}
}
]
}
|
POST /v1/messages
HTTP Headers:
Content-Type: application/json
Authorization: [Customer-OneAPI-key]
JSON request body:
{
"messages": [
{
"channel": "whatsapp",
"to": "2799900001",
"clientMessageId": "Customer-Message-Id",
"encryptionKey": "AQIDAHigcx4kN+SNTVLxxd6cYLmM7DE08asxE6NFNkM64hE3lwHJhdFgu6/pYA70ouO1qr6jAAAAfjB8BgkqhkiG9w0BBwagbzBtAgEAMGgGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMzc58TZHjteRTi2fiAgEQgDujc/hjzY8GJjg0LUOw6x+5FUwMoF516JBq8hfTGSxYAX45NLRDfN8Obn0nj8qPYQ0yv9FVhrpuDvE8xg==",
"template": {
"templateName": "template_header_0var_one_param",
"header": {
"type": "text",
"text": {}
},
"body": {
"parameters": {
"1": "chpdfMe6jWtx7P0fqGovJ5pHY3YaKK9DU5RUPwaI43w="
}
}
}
}
]
}
|
 |
|
Success Response
|
Success Response
|
|
|
HTTP 200
{
"messages": [
{
"apiMessageId": "24592e86e98f423e8aa60a10aabbc94d",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
HTTP 200
{
"messages": [
{
"apiMessageId": "129b1cdb63a54cfda560ae3985ae5eed",
"accepted": true,
"to": "2799900001",
"clientMessageId": "Customer-Message-Id"
}
],
"error": null
}
|
