Some time ago I mentioned an error and a possible workaround when using PowerShell with the Clickatell SOAP interface. As Clickatell now provides a REST based interface I thought it is time to quickly show you how to use this API instead.

Description

When sending SMS you certainly first have to enable the REST API in your developer central account. There you will get an AuthToken and a link to the documentation. The API itself is a little bit sparse as it only allows to work with the following objects:

• coverage
• message
• account/balance

However for simple sending this should be enough.

Sending a message to the URI endpoint is basically to send a POST request to https://api.clickatell.com/rest/message and setting some header fields. So far I only found the following gotchas:

• the recipient MUST be passed as a string and an array (even if only sending a message to one recipient)
• the API version number MUST be passed as a string (this is more a PowerShell problem)
• you cannot set the Accept when using PowerShell v3.0 (which seems to have been fixed in PowerShell v4.0, see here for details).
• In case you edit your API to accept multiple message parts, the maxCredits and maxMessageParts header has no effect

When a message is successfully received from the API you will get an HTTP 202 and an apiMessageId that you can later query to see the actual status of the message. Otherwise you will get something like HTTP 400 or HTTP 500. The error code and description in the payload will give you further details what went wrong.

Usage

Usage is rather simple:

# send message to one recipient
Send-ShortMessage 419955555555 "hello, world!" -Credential "myAuthToken"
# send message to multiple recipients
"419955555555","419955555556" | Send-ShortMessage -Message "hello, world!" -Credential "myAuthToken"
Send-ShortMessage -To "419955555555","419955555556" -Message "hello, world!" -Credential "myAuthToken"

Examples

Here you see the HTTP payload of a successful message submit. Keep in mind that the message does not necessarily has already been delivered (or delivered at all). You see that even that only one number has been specified the number has to be supplied as an array:

=== HTTP REQUEST ===
POST https://api.clickatell.com/rest/message HTTP/1.1
Authorization: Bearer e2c479178dd741aabe4d05c25db9b9b3
X-Version: 1
User-Agent: Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0
Content-Type: application/json
Host: api.clickatell.com
Content-Length: 46

{"text":"'hello, world!","to":["41995551234"]}

=== HTTP RESPONSE ===
HTTP/1.1 202 Accepted
Date: Mon, 16 Feb 2015 07:35:05 GMT
Server: Apache
Content-Length: 109
Content-Type: application/json

In this case the message could not be delivered as the recipient number is invalid:

=== HTTP REQUEST ===
POST https://api.clickatell.com/rest/message HTTP/1.1
Authorization: Bearer e2c479178dd741aabe4d05c25db9b9b3
X-Version: 1
User-Agent: Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) WindowsPowerShell/3.0
Content-Type: application/json
Host: api.clickatell.com
Content-Length: 37
Connection: Keep-Alive

{"text":"hello, world!","to":["333"]}

=== HTTP RESPONSE ===
HTTP/1.1 400 Bad Request
Date: Mon, 16 Feb 2015 07:34:26 GMT
Server: Apache
Content-Length: 208
Connection: close
Content-Type: application/json

{"data":{"message":[{"accepted":false,"to":"333","apiMessageId":"","error":{"code":"105","description":"Invalid Destination Address","documentation":"http://www.clickatell.com/help/apidocs/error/105.htm"}}]}}

You find additional examples on the wiki page for this Cmdlet.

Download and Documentation

You will find the complete source code for download and documentation in the biz.dfch.PS.System.Utilities repository.