One API Client Callbacks

Forward Compatibility While the basic callback structure will remain 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 as well as additional parameters in an event type do not break callback processing in the customer system.

• Any HTTP 200 range status code response from client is considered an acknowledgement that the callback was successful. Anything else will be retried, excluding redirect status code.

• Callback payloads and configurations are different (not backwards compatible).

• In future, one HTTPS callback request may contain multiple events for efficiency, but for now batch sizes are always 1.

• The events in callbacks may be out of sequence. User should look at timestamp fields to determine 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).

• Customer 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.

Example of a customer's One Api reply callback

post

Body

application/json

integrationIdstringOptional

integrationNamestringOptional

Responses

200

Success

No content

post

/client-callback/one-api-reply

HTTPcURLJavaScriptPython

POST /client-callback/one-api-reply HTTP/1.1
Host: customer-server/
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"
        }
      }
    ]
  }
}

One Api repliesOne Api replies with referral info

200

Success

No content

Example of a customer's One Api status callback

post

Body

application/json

integrationIdstringOptional

integrationNamestringOptional

Responses

200

Success

No content

post

/client-callback/one-api-status

HTTPcURLJavaScriptPython

POST /client-callback/one-api-status HTTP/1.1
Host: customer-server/
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"
      }
    ]
  }
}

200

Success

No content