Sending SMS Messages through Clickatell with the HTTP and JSON Components

Clickatell provides a REST API, the One API, for sending SMS messages. Messages are sent by posting a JSON request to https://platform.clickatell.com/v1/message, with the API key of a Clickatell integration in the Authorization header. The JSON component can be used to build the request and parse the response, and the HTTP component to send the request.

Building the Request

The request contains a messages array, with one object for each message (up to 100 messages in a single request). Each message includes the following fields:

JSON json = new JSON();
json.StartObject();
json.PutName("messages");
json.StartArray();
json.StartObject();
json.PutProperty("channel", "sms", 2); // 2 - String.
json.PutProperty("to", "15555550123", 2);
json.PutProperty("content", "Hi! This is a test message.", 2);
json.PutProperty("clientMessageId", Guid.NewGuid().ToString(), 2);
json.EndObject();
json.EndArray();
json.EndObject();
json.Flush();
string request = json.OutputData;

The request built by the code above looks like this:

{"messages":[{"channel":"sms","to":"15555550123","content":"Hi! This is a test message.","clientMessageId":"..."}]}

Sending the Request

To send the request, set the Authorization property of the HTTP component to the API key (the key is sent as is, without a scheme such as Bearer), and post the request using the Post method.

HTTP http = new HTTP();
http.Authorization = "API_KEY";
http.ContentType = "application/json";
http.Accept = "application/json";
http.PostData = request;
http.Post("https://platform.clickatell.com/v1/message");

If the request is rejected (e.g., with status code 401 when the API key is not valid, or 402 when the account has no remaining credit), the Post method throws an exception.

Reading the Response

When the request is accepted, Clickatell returns status code 202, and a response that contains an entry for each message in the request. Each entry includes the apiMessageId assigned by Clickatell (which can be used to check the status of the message), and an accepted field that indicates whether the message passed validation. When a message is not accepted, its error field contains a code and a description.

JSON response = new JSON();
response.Config("StringProcessingOptions=3"); // Unquote and unescape string values.
response.InputData = http.TransferredData;
response.Parse();

response.XPath = "/json/messages";
int count = response.XChildren.Count;
for (int i = 1; i <= count; i++)
{
  string message = "/json/messages/[" + i + "]/";
  response.XPath = message + "accepted";
  if (response.XText == "true")
  {
    response.XPath = message + "apiMessageId";
    Console.WriteLine("Message accepted with ID " + response.XText + ".");
  }
  else
  {
    response.XPath = message + "error/description";
    Console.WriteLine("Message rejected: " + response.XText);
  }
}

The status of a message can be checked later by sending a GET request to https://platform.clickatell.com/v1/message/{apiMessageId}, with the same Authorization header.

For more information, please see the Clickatell One API reference.