HOW-TO: SMS via Amazon Web Services

(To be followed in order, as indicated below...)

AWS Simple Notification Service (SNS)

This is the part you've been waiting for, right? All this talk about sending SMS messages from the cloud and so far all you've done is play with an EC2 instance...not fun, I know.

Well, now you get to play with SMS messaging without using your phone, at least for the sending part. That may not qualify as fun, but at a minimum it's at least a little bit cool. It's not hard, either, as long as you understand the process. And in order to understand the process, you must first understand a few things about the AWS Simple Notification Service.

SNS is not an SMS service

You read that right: it's not made specifically for SMS messaging. Instead, it's a notification service (says so in the name), one that can send notifications via any of a number of different protocols, one of which is SMS. In fact, the primary selling point of SNS is push notifications, not SMS messages.

The following is the full list of SNS-supported protocols:

  • http (JSON-encoded notification sent via HTTP POST)
  • https (JSON-encoded notification sent via HTTPS POST)
  • email (notification sent via SMTP)
  • email-json (JSON-encoded notification sent via SMTP)
  • sms (you know what this is)
  • sqs (JSON-encoded notification sent via Message Queueng Service)
  • application (JSON-encoded notification sent to a mobile app/device)

Topics and subscriptions are the meat and potatoes of SNS

Each notification that is set up in SNS consists of a "topic" and a number of "subscriptions" to that topic.

As you can probably guess by their name, topics are subjects for notifications. You can set up a topic for anything at all: events, security advisories, etc...whatever floats your boat. After a topic is created, devices and applications can subscribe to the topic to receive messages that are posted to the topic. One protocol from the list above is chosen for each subscription. Whichever protocol is chosen, that protocol will be used to send/receive any messages posted to the topic.

In other words, if there is a topic called "ServerDown" and it has three subscriptions, two of which subscribed to notifications via the SMS protocol and a third subscribed to notifications via email, whenever a message is posted to "ServerDown," that message will be sent to the first two people's phones via the SMS protocol and to the third person via email. It's a very democratic system, allowing subscribers to choose the channel through which they prefer to be notified.

Okay, got it. Now, send a notification using SNS already...

You now have a very general idea of how SNS works. Let's go to AWS and see first-hand how to set up a notification.

Note Perhaps you recall from the EC2 setup page that some AWS services are only partially offered in some regions. SNS currently only offers SMS notifications in the USA, and then only for topics that are created in the "US East (N. Virginia)" region. So, before digging in, after logging into AWS pull down the region menu at the top of the page and select "US East (N. Virginia)". And just a reminder, it's okay if your EC2 instance is in a different region.

Head over to the AWS listing page and click on "SNS" to get to the SNS system.

The first thing you'll need to do is set up a topic. Click on "Topics" in the left menu to get the topic listing:

There's not much to see yet, so click on the "Create new topic" button and fill out the form to create a new topic. Call it "Testing," and give it a display name of "Test Msg." These can both be something different, but this HOW-TO assumes you used those values.

Note Setting the display name on a topic is a requirement for SMS notification messaging.

When you save the new topic, you'll return to the topic listing which will show you not only the new topic name but also its "Amazon Resource Name," or ARN.

ARNs will be used extensively in the REST API that we'll set up later, so keep them in the back of your mind as we play with SNS. For now, click on the ARN for the new topic to pull up the "Topic Details" page:

There's a lot of information on this page that is not important yet. However, see that "Create Subscription" button? Click it so we can set up a new subscription. Select "SMS" from the protocol menu, then enter the number for an SMS-capable phone as the endpoint.

When you're done, click the "Create Subscription" button to finalize the subscription. You should end up back at the Topic Details page.

Within a few seconds, the phone associated with the phone number will receive a message asking to confirm the subscription. Follow instructions to confirm the subscription.

As you can see, the display name that you specified when setting up the topic is used to represent the topic in notifications, similar to a subject in an email. And after you respond with your subscription confirmation, you'll receive a follow-up message with instructions on how to get help with the topic and how to quit receiving notifications.

Unless you get errors, the phone should now be subscribed to the topic. Now, the coast is clear to send a test notification via the topic. Click on the blue "Publish to topic" button at the top of the Topic Details page to get the notification form:

The ARN for the topic will be pre-filled. Leave the subject line blank and leave the message format at its current "raw" setting, then enter a notification message in the message box:

When you're done, click the blue "Publish message" button at the bottom of the page. In a few seconds, unless something really bad happened, you should get a new SMS message on the phone.

Did you get the message? If so, congratulations! If not...I'm afraid AWS support will be required (debugging someone else's cloud service is near impossible). For the sake of progress, I'll assume you were successful. Hopefully that wasn't too daunting.

Even if it wasn't daunting at all, that's a lot of interaction with webpages just to set up and send a text message, isn't it? AWS isn't impossible to navigate, but it's not simple either. Wouldn't it be better to put this all in a REST API so you can perform all the steps from your own mobile app, intranet, curl at a command prompt...you know, anything other than logging into AWS? I think so. That's exactly what we're going to set up next.