One API

Query status of a message

get

• Response will contain status information for any channel relevant to the message.

• The timestamp field indicates the time of the last status change.

• If the message is in an unknown state (message not found), the format is different (since there is no channel) and the timestamp should be set to the current time as it is presently unknown at the time of the request.

Authorizations

api-key

AuthorizationstringRequired

Path parameters

omniMessageIdstringRequired

Omni message id

Responses

200

Success

application/json

404

Account not found

get

/v1/message/{omniMessageId}

HTTPcURLJavaScriptPython

GET /v1/message/{omniMessageId} HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "sms": {
    "status": "QUEUED",
    "timestamp": 1506607698000
  }
}

Send one or more messages

post

Note that on message send responses, there are two possible locations for error information: one for global level (where entire payload is rejected) and one where a message level reject is applicable. Errors Table Message Status Table Supported content types and limitations

Authorizations

api-key

AuthorizationstringRequired

Body

application/json

One api send message request

Responses

202

Success

application/json

207

Returned on a message when more than one message was submitted, but they have a different status (example: one message was accepted, and one was rejected

application/json

400

Bad Request. Note that the global error object is not used because this is a message-level error

application/json

401

Unauthorized

application/json

402

Payment Required. User is out of funds/credits/currency/balance

404

Request was sent to a resource that does not exist

503

Service Unavailable

post

/v1/message

HTTPcURLJavaScriptPython

POST /v1/message HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "messages": [
    {
      "channel": "sms",
      "to": "2799900001",
      "content": "Here is my message"
    }
  ]
}

SMS: One MessageSMS: Two-way MessageSMS: Message with aes-256-gcm encryptionSMS: Two unique message texts sent to two handsetsWhatsApp Text MessageWhatsApp Media Inline MessageWhatsApp Media By Reference Message (With Caption)WhatsApp Media By Reference Message (Without Caption)WhatsApp Contacts MessageWhatsApp Location MessageWhatsApp Text TemplateWhatsApp Interactive Text Template with Dynamic URLWhatsApp Interactive Media Template with Suggested Response ButtonsWhatsApp Media TemplateWhatsApp Interactive Text Template with Mixed ButtonsWhatsApp Interactive ListPicker MessageWhatsApp Interactive Button MessageWhatsApp Interactive Button Message: MediaWhatsApp Location Template (cloud-hosted only)WhatsApp Interactive Location RequestWhatsApp and SMS message in one requestWhatsApp Interactive URL Button MessageWhatsApp OTP via Authentication template

{
  "messages": [
    {
      "apiMessageId": "77fb29998253415fa5d66971d519d362",
      "accepted": true,
      "to": "2799900001",
      "error": null
    }
  ],
  "error": null
}

Send Business Read status notification

post

Authorizations

api-key

AuthorizationstringRequired

Body

application/json

Send Business Read Status notification request

Responses

202

Success

application/json

207

Returned on a request when more than one notification was submitted, but they have a different status (example: one notification was accepted, and one was rejected

application/json

400

Bad request

application/json

401

Unauthorized

application/json

404

Request was sent to a resource that does not exist

503

Service Unavailable

post

/v1/notification

HTTPcURLJavaScriptPython

POST /v1/notification HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "event": {
    "messageStatusUpdate": [
      {
        "channel": "whatsapp",
        "statusCode": 1001,
        "messageId": "3a89680503414383af44dcd0e4e5f184",
        "clientEventId": "2993b6b548000a80989a20549e7558a5"
      }
    ]
  }
}

WhatsApp: One business read notificationWhatsApp: Two Business read notifications

{
  "event": {
    "messageStatusUpdate": [
      {
        "apiEventId": "77fb29998253415fa5d66971d519d362",
        "accepted": true,
        "messageId": "3a89680503414383af44dcd0e4e5f184",
        "clientEventId": "2993b6b548000a80989a20549e7558a5",
        "error": null
      }
    ]
  },
  "error": null
}

Get media file metadata

get

Response returns metadata of uploaded media

Authorizations

api-key

AuthorizationstringRequired

Path parameters

fileIdstringRequired

ID of the file that was returned in media upload request

Responses

200

Success

application/json

expirationTimeinteger · int64Optional

broadcastAllowedbooleanOptional

400

Bad request

application/json

404

Account/file not found

get

/v1/media/{fileId}

HTTPcURLJavaScriptPython

GET /v1/media/{fileId} HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "expirationTime": 1583845974,
  "broadcastAllowed": true
}

Media Download

get

• Media file will be available for download for 30 days

• The response body will contain:

  • the binary media data if it is not client side encrypted

  • the encrypted binary media data if client side encrypted

• The download URL is specified in the moMedia event in the downloadUrl parameter of the files object array

Authorizations

api-key

AuthorizationstringRequired

Query parameters

fileIdstringRequired

ID of the file that is presented in MO Callbacks

sourcestring · enumOptional

If encryption is client, value should be 'client'

Possible values:

sha256HashstringRequired

Hash of file that is presented in MO Callbacks

Responses

200

Success

*/*

string · binaryOptional

400

Bad request

*/*

404

Account/file not found

get

/v1/media

HTTPcURLJavaScriptPython

GET /v1/media?fileId=text&sha256Hash=text HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Accept: */*

TUYASDBJHWETTASDGJ

Upload media file for One Api

post

• Uploaded media file will be available for message sending for 30 days after uploading

• The body must contain the binary media data

• Media size limit is 30MB

Supported content types and limitations

Authorizations

api-key

AuthorizationstringRequired

Query parameters

tostringOptional

Field that marks this upload file for delivery to a single destination user. Limits message sending to only this number

broadcastAllowedbooleanOptional

fileNamestringRequired

File name of the file being uploaded

encryptionKeystringOptional

kmsArnstringOptional

encryptionCipherstringOptional

sha256FileHashstringOptional

Header parameters

Content-TypestringRequired

Content type of file

Example: image/jpg

Body

*/*

objectOptional

Responses

201

Success

application/json

400

Bad request

application/json

404

Account not found

post

/v1/media

HTTPcURLJavaScriptPython

POST /v1/media?fileName=text HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Content-Type: */*
Accept: */*
Content-Length: 188

"curl -X POST -H \"Authorization: YOUR-API-KEY\" -H 'Content-Type: image/jpg' --data-binary @myFilename.jpg https://platform.clickatell.com/v1/media?fileName=myFilename.jpg&to=27999123456"

Media upload CURL example: single destination userMedia upload CURL example: any destination userMedia upload CURL example: Client side encryption: single destination userMedia upload CURL example: Client side encryption: any destination user

{
  "fileId": "uuid.xxx",
  "accepted": true,
  "error": null
}

Return information about account balance

get

Authorizations

api-key

AuthorizationstringRequired

Responses

200

Success

application/json

balancenumberOptional

currencystringOptional

404

Account not found

get

/v1/balance

HTTPcURLJavaScriptPython

GET /v1/balance HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "balance": 1267.92865,
  "currency": "ZAR"
}