Customer Callbacks
Forward compatibility
While the basic callback structure remains constant:
{
"integrationID": "string",
"integrationName": "string",
"event": {}
}there are constant additions to channels, including new features and message types, and Clickatell will be adding these to the callbacks as they become available.
Customers are required to implement callback processing in such a way that new event types and additional parameters in an event type do not break callback processing in the customer system.
Any HTTP 200 range status code response from the client is considered an acknowledgment that the callback was successful. Anything else, excluding the redirect status code, will be retried.
Callback payloads and configurations are different (not backward compatible).
In the future, one HTTPS callback request may contain multiple events for efficiency, but currently, batch sizes are always one.
The events in callbacks may be out of sequence. Users should look at timestamp fields to determine the order.
Timestamps are millisecond unit timestamps.
If the customer application does not respond fast enough to HTTP/S callbacks, we will retry the callback. This means they may experience duplicate callbacks (due to the retries).
Customers can configure a callback URL for status event callbacks and another URL for MO messages. This helps to maintain low-latency conversations by splitting the events.
One API reply callback
Success
No content
POST /client-callback/one-api-reply HTTP/1.1
Host: platform.clickatell.com
Content-Type: application/json
Accept: */*
Content-Length: 3967
{
"integrationId": "fa8090815f05d5ed015f0b5b56080cd2",
"integrationName": "My integration",
"event": {
"moText": [
{
"channel": "whatsapp/sms ",
"messageId": "3a89680503414383af44dcd0e4e5f184",
"relatedMessageId": "d33eef0838a121f71069a4cc8d55c19e",
"relatedClientMessageId": "d33eef0838a121f71069a4cc8d55c19e",
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"content": "Text Content of the reply message",
"charset": "UTF-8",
"sms": {
"network": "Network ID"
},
"whatsapp": {
"profileName": "Profile Name"
}
}
],
"moMedia": [
{
"channel": "whatsapp ",
"messageId": "7ed16cedd7ca7c4d252c7ec854dec3cb",
"relatedMessageId": "8f287d93f5e5c5fd3ba228fef124c975",
"relatedClientMessageId": null,
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"contentType": "image/jpeg",
"content": "Base64 Binary Media Stream Content",
"caption": "caption text here",
"whatsapp": {
"profileName": "Profile Name"
}
},
{
"channel": "whatsapp ",
"messageId": "7ed16cedd7ca7c4d252c7ec854dec3cb",
"relatedMessageId": "8f287d93f5e5c5fd3ba228fef124c975",
"relatedClientMessageId": null,
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"files": [
{
"contentType": "image/jpeg",
"downloadUrl": "https://platform.clickatell.com/v1/media?fileId=UUID-1.xxx&sha256Hash=529fd5482f43db39992a894bbe4216f51a4d724131a97b93cc5589433b545820&source=client",
"sha256Hash": "529fd5482f43db39992a894bbe4216f51a4d724131a97b93cc5589433b545820",
"byteSize": 12345,
"fileName": "myImage.jpeg"
}
],
"caption": "caption text here",
"whatsapp": {
"profileName": "Profile Name"
}
}
],
"moLocation": [
{
"channel": "whatsapp ",
"messageId": "f4915e8edf965566246c995c8703120d",
"relatedMessageId": null,
"relatedClientMessageId": null,
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"charset": "Character set of the reply message",
"locationAddress": "900 Island Dr #202, Redwood City, Redwood City, CA, 94065",
"locationName": "Clickatell",
"latitute": "37.536033630371094",
"longitude": "-122.25885772705078",
"whatsapp": {
"profileName": "Profile Name"
}
}
],
"moContacts": [
{
"channel": "whatsapp",
"messageId": "f4915e8edf965566246c995c8703120d",
"relatedMessageId": null,
"relatedClientMessageId": null,
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"whatsapp": {
"profileName": "Profile Name"
},
"contacts": [
{
"addresses": [
{
"city": "Johannesburg",
"country": "SA",
"countryCode": "10",
"state": "state",
"street": "street",
"type": "personal",
"zip": "1010"
}
],
"birthday": "01.01.1980",
"emails": [
{
"email": "[email protected]",
"type": "personal"
}
],
"name": {
"firstName": "First Name",
"formattedName": "Formatted Name",
"lastName": "Last Name"
},
"org": {
"company": "Clickatell"
},
"phones": [
{
"phone": "2799900001",
"type": "personal"
},
{
"phone": "2799900002",
"type": "personal",
"waId": "waId"
}
],
"urls": [
{
"url": "https://clickatelllabs.com",
"type": "personal"
}
]
}
],
"charset": "Character set of the reply message"
}
],
"moSuggestedResponse": [
{
"channel": "whatsapp",
"messageId": "3a89680503414383af44dcd0e4e5f184",
"relatedMessageId": "d33eef0838a121f71069a4cc8d55c19e",
"relatedClientMessageId": "d33eef0838a121f71069a4cc8d55c19e",
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"content": "Text Content of the reply message",
"postbackData": "Custom Data As Defined In Outbound Message",
"charset": "UTF-8",
"whatsapp": {
"profileName": "Profile Name"
}
}
],
"moListPickerResponse": [
{
"channel": "whatsapp",
"messageId": "7ed16cedd7ca7c4d252c7ec854dec3cb",
"relatedMessageId": null,
"relatedClientMessageId": null,
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"postbackData": null,
"selectedItems": [
{
"postbackData": "food option 1"
}
],
"whatsapp": {
"profileName": "WA Client Profile Name"
}
}
],
"moButtonResponse": [
{
"channel": "whatsapp",
"messageId": "7ed16cedd7ca7c4d252c7ec854dec3cb",
"relatedMessageId": "27366213db12571cf7f433184ffa46ea",
"relatedClientMessageId": null,
"from": "2799900001",
"to": "2799900002",
"timestamp": 1506607698000,
"postbackData": null,
"selectedItem": {
"postbackData": "postback-id-2",
"content": "This field might be set to null on some channels"
},
"whatsapp": {
"profileName": "WA Client Profile Name"
}
}
]
}
}Success
No content
One API status callback
Success
No content
POST /client-callback/one-api-status HTTP/1.1
Host: platform.clickatell.com
Content-Type: application/json
Accept: */*
Content-Length: 312
{
"integrationId": "fa8090815f05d5ed015f0b5b56080cd2",
"integrationName": "My integration",
"event": {
"messageStatusUpdate": [
{
"channel": "whatsapp/sms ",
"timestamp": 1506607698860,
"statusCode": 5,
"status": "DEVICE_ACK",
"messageId": "3a89680503414383af44dcd0e4e5f184",
"clientMessageId": "2993b6b548000a80989a20549e7558a5"
}
]
}
}Success
No content
Last updated