Back in the before time, I wrote a blog post entitled “Sending SMS Through PowerShell with Telstra’s New API”. Using some PowerShell scripts I provided back then, you could have a little play with using Telstra’s SMS gateways to amuse and annoy your pals (and I imagine apply some valid business use cases in there somewhere too). Fast forward to a few weeks ago, and I received an email from somebody who had read that blog post and reached out to me to say “Hey Dan, your scripts don’t work.” – that person is 100% correct, because much like time, API’s do not stand still and given enough change and too few updates, code you were using to send stuff might just break. This is the case with the code I published back in the day, which prompts me (for that one guy, and perhaps for you too) to write this follow-up blog post, which I have creatively titled “Sending SMS Through PowerShell with Telstra’s New New API”
At the time of writing, the current version of the Telstra SMS API available to the public is v2.2.9. Let’s quickly go over the changes in the API since the olden days when I wrote the other blog with the similar title.
|Randomly created number on each SMS send||Provision a dedicated number and send from that|
|Send SMS to only a single number at a time||Broadcast to up to 10 recipients|
|Send SMS to Australian mobiles only||Annoy your friends in many countries (link: https://raw.githubusercontent.com/telstra/MessagingAPI-v2/master/docs/Telstra_Messaging_API_Country_Codes.csv)|
|SMS Only||MMS joins the party|
|1000 free messages per month||Still 1000, but come on. That’s pretty good.|
Lots of new cool features. So, lets update that dusty old PowerShell and show you how you can make use of the new API.
The very first thing you’re going to need to do, is create an account over at https://developer.telstra.com if you don’t already have one and create an app. This is a very painless affair, all you have to do is hit the “develop” drop down box at the top, then “my apps and keys” and then hit the plus button to “create application”. Once you’ve done that, you will be issued a client key and client secret, which we will make use of in our code.
Then, you can start playing! For the purposes of this example, I’m just going to paste my client key and secret as variables within the script, if you’re doing this in an actual production environment however, you should not do that. Depending on how you end up deploying this thing will determine the best way to keep your secrets secret, but this Kloud blog by my former colleague Dave Lee might give you some clues on the best way to approach that.
Generate an Access Token
The first thing we need to do code-wise, is create an access token, we can do this easily with the following snippet:
Now, if you take a peek at the $Authorization variable (by of course just typing $Authorization) you should see something like the following:
Create a Subscription
Now that we’re authorised, we need to perform a step which is new for this updated version of the API, and that is to create a “subscription”. What’s that exactly? Well, it seems more or less that we are creating a phone number within Telstra which will become ours, but only for the next 30 days on the free tier. This is however an improvement on the olden days where we got a new number each and every time we sent a message. At this point, you can also specify a “notify URL” in your POST, what this would do is POST any responses that number receives back to the URL you specify, so if you had a fully-fledged app, you could start getting into some automated replies. We’re keeping it simple for this example. The following code snippet will help you create a subscription:
Once we execute that code, we get a subscription which consists of a destinationAddress (mobile number where you will send and receive SMS message) and an expiry date in UNIX time. This is all we need to start bouncing out messages and receiving replies, so let’s do that! Executing the following code is going to fire an SMS out in to the world
Send an SMS
The SMS is received quicker than the time it took me to lift my phone after hitting enter – not bad.
And now, of course I can reply to that message from my phone as I would any other information cat-based message, and retrieve said reply via the following PowerShell command:
Which results in the following:
Bonus Round: MMS
OK, this was just going to be an update on my original samples of sending SMS via Telstras API’s, but one of the new capabilities is MMS, so why the heck not – let’s have a play with that functionality too.
All of the authentication bits and pieces are identical, and we can send using the same subscription (mobile number) we created before, but the JSON we end up posting is structured quite differently and contains an embedded image in BASE 64. Here’s what it looks like:
This time, the message did take slightly longer to deliver to my phone. I imagine this is something I could complain to my local MP about to have rectified. Based on my experience alone, I would suggest if you’re building out any sort of application which requires a timely back and forth between your app and the user, use SMS rather than MMS, and where timeliness is irrelevant but you want to embed lovely images – well, use MMS.
To summarise, yes indeed astute reader, my old code no longer works with the Telstra SMS API, this is because we have a brand spanking new API! I hope the update hadn’t broken your automated cat fact spammer, and you enjoy updating your code to get the app back on it’s feet.
This post has provided a simple view of how you can make use of the Telstra API at no cost – PowerShell is my choice of language due to my background, but you can really write this type of thing in any old language you like. If you are interested in playing with this stuff yourself, I would encourage you to sign up over at https://dev.telstra.com/ and also check out the wealth of documentation they’ve got on this (and many other) API’s. Happy tinkering!