Amazon Pinpoint for AWS Text Messages

SMS, or text messaging, is the simplest way to reach your users outside of normal customer-facing web or mobile applications. Compared to other communication channels such as email and push notifications, text messaging results in higher engagement.

SMS messaging is extremely convenient — users don’t have to authenticate, download your app, or go to your website. They simply receive your message on their device. When it comes to customer acquisition and retention, it doesn’t get any easier than this.

In this article, I’ll explain what two-way SMS is and how you can quickly and easily start sending personalized, timely, and relevant text messages to your customers with Amazon Pinpoint. We’ll then implement a practical solution for setting up an SMS long code so you can start sending and receiving text messages.

SMS messages (better known as “text messages”) are typically sent person-to-person, but they are also sent business-to-person. Businesses typically send text messages programmatically, as they would otherwise need a lot of physical phones and dedicated employees manually sending text messages to each customer — which is simply not realistic or scalable.

When a business sends a text message to a customer, it tends to be a one-way SMS. In a one-way communication, the business will send a message in the form of an announcement or one-off notification that typically doesn’t require any further interaction. For example, a restaurant may text a patron when their reserved table is ready. Or, a doctor’s office might send a text to a patient reminding them of their upcoming appointment.

Businesses can also send twoway messages to customers when they want to receive a response that provides them with actionable next steps. For example, going back to the doctor appointment use case, the outbound message to the patient could include an option to respond “1 to ‘confirm’ or 2 to ‘cancel appointment’”. The patient’s text response would come back to the doctor’s office management app, and they can then take action based on the response. With two-way SMS, the possibilities are endless.

To engage in programmatic two-way SMS conversations with your customers, you’ll first need to obtain a long code or short code from a messaging provider like Twilio, Nexmo, or Amazon Pinpoint.

Each provider will offer an API for sending and receiving text messages from your customers to your long or short code. These numbers are not associated with a mobile device and are intended as virtual addresses for your applications.

A long code is a essentially 10-digit phone numbers used to send and receive SMS and are limited to 1 message per second. A short code is a five-digit or six-digit number that’s meant for high-volume SMS messaging.

Short codes are often used for application-to-person (A2P) messaging, two-factor authentication (2FA), and marketing messages — and you must request a separate short code for each country you support.

Bottom line, you need to be serious about SMS to own a short code as they are more expensive than long codes. You can lease them for around $1,000 USD per month in the USA. Short code also involves a rigorous registration process with wireless carriers.

If your business revolves around SMS as a main form of communication, like bank alerts/transactions, emergency notifications, etc., then a short code is the way to go as it offers high-volume messaging and can reach many different users at once. You can learn more about requesting a dedicated short code for SMS Messaging with Amazon Pinpoint here.

Amazon Pinpoint enables AWS customers to send both one-way and two-way transactional or promotional text messages via either long or short code. With two-way SMS messaging, Amazon Pinpoint opens up the possibilities for event-driven use cases where customer interaction from human-to-human or human-to-business is now front and center.

Below, I’ll walk through provisioning a long code with Amazon Pinpoint, registering a keyword and canned message, and creating an SNS topic. Don’t worry, I’ll explain how it all works once we set it up.

Setup should take about 5–7 minutes. Please note, this service is not free. For pricing information, check the current rates.

1. Log into the Amazon Pinpoint Console
2. Create a project by giving it a name and select Create a project.

3. Select SMS and voice under project features

4. In General settings, select (a) Enable the SMS channel for this project and(b) select Transactional.

5. Expand the Advanced configurations — optional and Select Request Long Codes

6. Select your Target country or region, quantity of 1. Select Request long codes orange button. If you don’t see a long code for a particular county, you can always request one.

7. Select the newly provisioned phone number

8. Scroll down and ignore the Required keywords and select Enable two-way SMS

When enabling two-way SMS, you are prompted to create or choose an existing SNS topic. Select “Create a new SNS topic” and provide a name for the topic like SMSTwoWayHandler.

9. Select Add another keyword

For keyword, add “Amplify”. Under Response message, add a message that is an automated response to the user when they send “Amplify” to your long code. Select Save.

Done! You now have a dedicated long code for sending & receiving SMS messages. No longer do your customers have to download an app or submit a form online to interact with your business; you can simply set up a phone number (long code) and ask customers to send in votes, register for an event, confirm appointments, or anything else that requires instant feedback and interaction.

You just provisioned a long code, created an SNS topic, added a keyword, and provided a default canned response message for the given keyword. Now, let’s talk about how it all works.

Keywords and Canned Messages
For incoming text messages to your new long code, Amazon Pinpoint parses the message and looks for a specific keyword and, if found, immediately responds to the customer via SMS text message with the canned message you provided for that corresponding keyword. This whole cycle is fully automated and managed by Pinpoint.

Handling incoming messages with an SNS topic
In addition to handling the keyword and canned response, the original message is always forwarded to your Amazon Simple Notification Service (SNS) topic for further handling. The SNS topic will receive a JSON message from Pinpoint regardless if the customer provides a keyword or not.

Earlier, we created an SNS topic but didn’t add subscriptions. We need to add a listener (subscription) to the SNS topic in order to capture all inbound messages, otherwise, this two-way SMS thing would be kind of useless.

Amazon Pinpoint sends a JSON message to your SNS topic for all inbound messages sent to your long code. As a developer, you can subscribe one or more protocols (endpoints) to the SNS topic for handling the inbound JSON message.

For subscriptions, you can subscribe any HTTP/s service endpoint, an email address, an Amazon Simple Queue Service (SQS) queue, an AWS Lambda function, a push notification endpoint, or even an SMS phone number. You can subscribe one or many of these endpoints to the same topic.

When your long code number receives an SMS message, Amazon Pinpoint sends a JSON payload to the Amazon SNS topic that you designated. The JSON payload contains the body of the message and related data, as in the following example:

The value for originationNumber is the number that the message was sent from (that is, your customer’s mobile number). The value for destinationNumber is the number that the message was sent to (your long code). The messageBody is the exact text message that your customer typed into their phone.

As an example, I’ll walk you through subscribing an SMS phone number to the SNS topic. In this case, the flow looks like this: Customer +12064555xxxx sends “Hello, world!” to your long code at +1321517xxxx.

1. Launch the SNS management console
2. Select your topic (we named it SMSTwoWayHandler)
3. Select Create subscription
4. Select SMS for protocol and enter your phone number. Make sure it’s in the right format as shown.

5. Select Create subscription

Done! Now test the subscription by sending a text message to your Amazon Pinpoint long code from any mobile device and you should see the JSON message arrive on your SMS phone number that you just subscribed to the topic. The SMS subscription is just a quick test. A common practice is to subscribe an AWS Lambda function that handles the incoming message, parses it, and performs other business logic and even respond to the customer.

There are limitations to consider when using two-way SMS with Amazon Pinpoint. First, there’s a default spending limit of only $1 per account, which you could reach after sending several dozen text messages. It’s a good idea to increase this limit immediately so that your SMS messaging doesn’t stop without notice.

Secondly, for long codes, SMS transactions have sending rate restrictions as stated in the Amazon Pinpoint docs. Also note, different countries and jurisdictions have different limitations on the permitted uses of SMS — make sure you are complying with your local regulations or you can face fines and have your sending suspended.

I created an application about five years ago that monitors the AWS Status Dashboard for issues. When a new posting is made to the RSS feed, I parse the data in an AWS Lambda function and notify about 15 subscribing mobile phone numbers via SMS.

During a large event, the application could send up to 12 messages per hour to those 15 subscribers. That’s about 180 SMS messages delivered per hour and I haven’t observed any issues and have trusted Amazon Pinpoint to deliver those messages successfully and in a timely manner since switching nearly two years ago from Amazon Simple Notification Service (SNS).

SMS messaging is a powerful tool for customer engagement. Using a two-way SMS channel for your business can drive adoption and help retain those users in more ways than email or push notifications. Text messaging takes your application out of the picture and provides immediate interaction and customer feedback. Give Amazon Pinpoint a try and start sending/receiving text messages!

I’m considering some more advanced topics for SMS messaging like phone verification, building a robust Lambda function handler for handling all two-way scenarios, and/or diving deep into the delivery and failure CloudWatch Logs. Please let me know your preference in the comments.

A Cloud Guru makes it easy (and awesome) to get certified and master modern tech skills — whether you’re new to cloud or a seasoned pro. Check out ACG’s current free courses or get started now with a free trial.