Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
AuthorizationstringRequired
Path parameters
omniMessageIdstringRequired

Omni message id

Responses
200

Success

application/json
get/v1/message/{omniMessageId}
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
AuthorizationstringRequired
Body

One api send message request

Responses
202

Success

application/json
typestring · enumWrite-onlyOptionalPossible values:
post/v1/message
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"
    }
  ]
}
{
  "messages": [
    {
      "apiMessageId": "77fb29998253415fa5d66971d519d362",
      "accepted": true,
      "to": "2799900001",
      "error": null
    }
  ],
  "error": null
}

Send Business Read status notification

post
Authorizations
AuthorizationstringRequired
Body

Send Business Read Status notification request

Responses
202

Success

application/json
typestring · enumWrite-onlyOptionalPossible values:
post/v1/notification
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"
      }
    ]
  }
}
{
  "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
AuthorizationstringRequired
Path parameters
fileIdstringRequired

ID of the file that was returned in media upload request

Responses
200

Success

application/json
expirationTimeinteger · int64Optional
broadcastAllowedbooleanOptional
get/v1/media/{fileId}
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
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
get/v1/media
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
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
  • Field that marks this upload file for delivery to any destination users.
  • Value must be set to true
  • Broadcasts for media and interactive media templates are supported.
  • Note: The above is dependent on terms and conditions and best practices as prescribed by Meta.
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
fileIdstringOptional
acceptedbooleanOptional
post/v1/media
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"
{
  "fileId": "uuid.xxx",
  "accepted": true,
  "error": null
}

Return information about account balance

get
Authorizations
AuthorizationstringRequired
Responses
200

Success

application/json
balancenumberOptional
currencystringOptional
get/v1/balance
GET /v1/balance HTTP/1.1
Host: platform.clickatell.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "balance": 1267.92865,
  "currency": "ZAR"
}
PreviousClickatell API Reference
NextOne API Client Callbacks

Last updated