This is the second post in a two part series on integrating SMS functionality into an application. In the first post, “A high-level look into Clickatell’s new SMS Small Business API”, I focused on the analysis I did into Clickatell’s Small Business API. This post focuses on the options available and technical details for integrating the API into your application.
There are many options available for integrating Clickatell’s Small Business API into your application and Clickatell’s APIs & Scripts page has all the info you need to get started. All of the specifications for all the protocols are available on their “Developer’s Central” page.
The protocols available are: HTTP/S, XML, SOAP and COM object. There are other protocols listed on that page, like FTP and SMTP, but they don’t apply to the Small Business API. They have sample scripts available for PhP, VBScript, C#, VB.NET, Cold Fusion and Oracle and there are third party libraries available for Java, Perl, Ruby and Applescript.
WHAT PROTOCOLS ARE AVAILABLE?
HTTP:
The HTTP option is pretty straightforward. Just pass your api_id, user, password, to and text to the /http/sendmsg endpoint and it will return a status and guid for the message.
http://api.clickatell.com/http/sendmsg?api_id=xxxx&user=xxxx&password=xxxx&to=xxxx&text=xxxx
XML:
This is very similar to the HTTP endpoint, but instead of passing the data as individual querystring parameters you pass one “data” parameter with xml.
The only reason I’d want to use XML instead of HTTP is if I have some client serialization code that already spits out XML. Otherwise, HTTP is more intuitive and requires less bandwidth.
http://api.clickatell.com/xml/xml?data=<clickAPI><sendMsg><api_id>1</api_id><user>demo</user><password>demo</password><to>448311234567</to><text>Meet me outside</text><from>me</from></sendMsg></clickAPI>
SOAP:
It looks complex, but this message is dynamically generated from the WSDL proxy.
<?xml version="1.0" encoding="ISO-8859-1"?> <SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:tns="soap.clickatell.com"> <SOAP-ENV:Body>
<tns:sendmsg xmlns:tns="soap.clickatell.com"> <session_id xsi:nil="true" xsi:type="xsd:string"/> <api_id xsi:type="xsd:int">1234</api_id> <user xsi:type="xsd:string">demo</user> <password xsi:type="xsd:string">demo</password>
<to xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="xsd:string[2]"> <item xsi:type="xsd:string">2799912345</item> <item xsi:type="xsd:string">27999123134</item> </to>
<from xsi:type="xsd:string">me</from> <text xsi:type="xsd:string">Initial test message</text> <concat xsi:nil="true" xsi:type="xsd:int"/> <deliv_ack xsi:nil="true" xsi:type="xsd:int"/> <callback xsi:nil="true" xsi:type="xsd:int"/> <deliv_time xsi:nil="true" xsi:type="xsd:int"/> <max_credits xsi:nil="true" xsi:type="xsd:float"/> <req_feat xsi:nil="true" xsi:type="xsd:int"/> <queue xsi:nil="true" xsi:type="xsd:int"/> <escalate xsi:nil="true" xsi:type="xsd:int"/> <mo xsi:nil="true" xsi:type="xsd:int"/> <cliMsgId xsi:nil="true" xsi:type="xsd:string"/> <unicode xsi:nil="true" xsi:type="xsd:int"/> <msg_type xsi:nil="true" xsi:type="xsd:string"/> <udh xsi:nil="true" xsi:type="xsd:string"/> <data xsi:nil="true" xsi:type="xsd:string"/> <validity xsi:nil="true" xsi:type="xsd:int"/> </tns:sendmsg>
</SOAP-ENV:Body> </SOAP-ENV:Envelope>
COM:
The COM option will be a good one to choose if you have legacy software that runs in a COM world. You could obviously get it to work with modern technologies, but you still have DLL HELL to consider. You have to register the DLL, create an INTEROP and go from there. I haven’t looked at COM in so long, but I still have nightmares about it.
oSMS.SendSimpleSMS API_ID, "username", "password", "278…", "My first SMS"
WHICH PROTOCOL SHOULD I CHOOSE?
If you are using Java, Perl, Ruby or Applescript then the clear winner is to use one of the 3rd party libraries that you can find on the Scripts page.
Nothing for .NET. Yes, they do have examples on how one would call their API using C#, but that is just code to issue a WebRequest.
My recommendation for Clickatell is to create a .NET library and get it up on NuGet.
So, as it stands right now, if you are using .NET then you are left with these options:
- HTTP or XML
- Write your own .NET 3rd Party Library
- COM
- SOAP
HTTP or XML
If you use HTTP or XML then you have to write your own code to process the response. Yes, Clickatell did a nice job telling you what all the responses would be in their HTTP and XML documentation, but you are probably like me and don’t have the time to write the code to process all the responses. Here’s what a typical response looks like:
If you just need a very simple “fire and forget” SMS notification implementation and don’t care if it fails or succeeds then this is the best way to go. This is also a great option if you want to create an SMS from script. My recommendation for Clickatell on this one is to at least return the response as JSON so they are easily consumable from script.
WRITE YOUR OWN .NET 3RD PARTY LIBRARY
Just like the HTTP or XML option you are left to write a ton of code to wrap one of the protocols. This would be a big undertaking…more than I would expect any of my readers to implement. If you do decide to go this route, then start copying from the Java 3rd party library.
COM
Like most of you out there I got bit by COM in the late 90s so I try to avoid it like the plague. But, if that is your preference then go for it. Just be warned that you’ll need to be concerned with DLL registration and trust levels. The DLL might require full trust, something that isn’t supported in most shared hosting environments.
They provide an MSI that installs the DLLs for you, but again installing an MSI in a shared hosting environment probably isn’t supported.
SOAP
It’s heavy, big and complex, but given all the other options currently available I think SOAP is probably the best option for .NET developers, because…
1. You can create a proxy that behaves like your own 3rd party library
2. You don’t have to write an HTTP endpoint wrapper WebRequest code
3. You don’t have to deal with COM and DLL hell.
You still have to process all the response codes, but you’ll have to do that with any of the options.
How to USE THE SOAP ENDPOINT IN A .NET APPLICATION
1. Open your app and add a service reference
2. Enter the Clickatell SOAP URL
http://api.clickatell.com/soap/webservice.php?WSDL
3. Click “Go”. Enter a Namespace and click OK.
That will generate your C# proxy and give you a class called PushServerWSPortTypeClient. You’ll use this class for all your SMS needs.
4. Add a using statement: (This will be different for your app)
using ClickatellSample.Console.ClickatellProxy;
5. Instaniate a new PushServerWSPortTypeClient class:
var client = new PushServerWSPortTypeClient();
6. Call the auth method to get a session Id;
var authResponse = client.auth([app_id], "[username]", "[password]");
if (!string.IsNullOrWhiteSpace(authResponse)
&& authResponse.StartsWith("OK"))
{
//authResponse = "OK: [sessionId]"
//authResponse is prefixed with an OK status code and then the sessionId so you need to parse it out
var colonIndex = authResponse.IndexOf(":", StringComparison.Ordinal);
if (colonIndex != -1)
{
var sessionId = authResponse.Substring(colonIndex + 2); // Add two to trim the colon and the space after it ": "
7. Call the sendmsg method to send the SMS.
var responses = client.sendmsg(
sessionId, [app_id],"[username]","[password]", new string[] { "[to]" },"[from]","Test SMS",
0,0,0,0,0,0,0,0,0,string.Empty,0,string.Empty,string.Empty,string.Empty,0);
foreach (var response in responses)
{
//response = "ID: [unique id of sms]"
System.Console.WriteLine(response);
}
Here’s the complete code sample:
var client = new PushServerWSPortTypeClient();
var authResponse = client.auth(123456, "[username]", "[password]);
if (!string.IsNullOrWhiteSpace(authResponse) && authResponse.StartsWith("OK"))
{
//authResponse = "OK: [sessionId]"
//authResponse is prefixed with an OK status code and then the sessionId so you need to parse it out
var colonIndex = authResponse.IndexOf(":", StringComparison.Ordinal);
if (colonIndex != -1)
{
var sessionId = authResponse.Substring(colonIndex + 2); // Add two to trim the colon and the space after it ": "
System.Console.WriteLine(sessionId);
var responses = client.sendmsg(
sessionId, 123456, "[username]", "[password]", new string[] { "[to]" },"[from]","Test SMS",
0,0,0,0,0,0,0,0,0,string.Empty,0,string.Empty,string.Empty,string.Empty,0);
foreach (var response in responses)
{
//response = "ID: [unique id of sms]"
System.Console.WriteLine(response);
}
}
}
FINAL THOUGHTS
Clickatell’s Small Business API is great if you want to integrate simple SMS functionality into your application. A simple HTTP request is all you need to send an SMS.
They are behind the times when it comes to integrating SMS into a .NET application, but you can get HTTP/XML to work with WebRequest or you can create proxies to the COM or SOAP endpoints. I found out through using the endpoints that all of them require you to parse the response, i.e. “OK: [sessionId]”. This is obviously the result of the service being around for a very long time because modern day HTTP endpoints would return a JSON response that looks something like this “{status:‘ok’, sessionId:’[sessionId]}” and the SOAP endpoint would return a strongly typed object. This leaves a lot of work for developers because we have to account for every possible response and parse it appropriately. I was hoping the SOAP endpoint would deal with that for me, but it doesn’t.
Here’s what I recommend they do to make their service more appealing to .NET developers.
- Create a .NET library
- Put that library up on NuGet so it is easy to install and update
- Parse all the response messages into strongly typed objects and enums.
- Simplify the API. As you can see in my sample above the “sendmsg” method takes 22 parameters, all but 3 are optional.
I hope this SMS series gave you the information you need to get started with integrating SMS into your application and saved you some time.
Jon