Send Branded SMS Messages Using Twilio Alphanumeric Sender ID

Time to read: 3 minutes

August 06, 2015
Written by
Phil Nash
Twilion

phone

It’s been a few months since we hosted Signal and in this post I wanted to spend some time exploring one of the announcements that I found pretty exciting: alphanumeric sender ID’s. Being based in the UK and traveling often in Europe I regularly receive SMS messages with a business name as the sender ID instead of a phone number. This is great as I instantly recognize the name of the business sending me the message instead of seeing an incoming message from an unknown number.

In my SMS inbox right now there are no less than 3 messages using a business name as the sender ID instead of a phone number
Now I can use Twilio to enhance the experience I provide users receiving my SMS messages by sending text messages with an alphanumeric sender ID to any of 145 countries around the world. In this post I’m going to show you how.

A word of warning

Before we dive into the code, there are a few things you should know about alphanumeric sender IDs. This style is great for alert or broadcast type messages, but no use for interactive applications as users cannot respond to an alphanumeric sender. As such, if you choose to use an alphanumeric sender ID you will need to provide alternative ways for users to opt out. You should also think carefully about the sender ID that you choose. Your business name or brand is fine, but if you try to get too creative things can really backfire.

Ready to start sending branded SMS messages? Let’s get on with it then.

Today’s toolbox

I’m going to demonstrate sending an SMS message from an alphanumeric ID using Ruby, so if you want to follow along, you’ll need the following:

and that’s it, so let’s get on with sending some SMS messages!

Sending SMS messages

You may have seen how to send an SMS message from a phone number before, but here’s a quick recap:

 

require 'twilio-ruby'

# Get these from your account dashboard
account_sid = YOUR_ACCOUNT_SID
auth_token = YOUR_AUTH_TOKEN
# You'll need to buy a Twilio number for this
twilio_phone_number = YOUR_TWILIO_PHONE_NUMBER
# This can be your phone number for testing purposes
recipient_phone_number = RECIPIENT_PHONE_NUMBER

# Instantiate a Twilio::REST::Client with our Account SID and Auth Token
client = Twilio::REST::Client.new(account_sid, auth_token)

# Use the client to create a message using the arguments from above
client.messages.create(
  from: twilio_phone_number,
  to:   recipient_phone_number,
  body: "Hello, this is a message from Phil"
)

 

You can save that to a file and run it or just type it straight into irb, either way it will just work. Pretty straightforward, right? How about sending an SMS message from an alphanumeric sender ID then?

 

require 'twilio-ruby'

account_sid = YOUR_ACCOUNT_SID
auth_token = YOUR_AUTH_TOKEN
twilio_phone_number = "Phil"
recipient_phone_number = RECIPIENT_PHONE_NUMBER

# Instantiate a Twilio::REST::Client with our Account SID and Auth Token
client = Twilio::REST::Client.new(account_sid, auth_token)

# Use the client to create a message using the arguments from above
client.messages.create(
  from: twilio_phone_number,
  to:   recipient_phone_number,
  body: "Hello, this is a message from Phil"
)

 

If you run the code, you should receive a message from the name you use instead of the number.
As you can see, there’s only one change. We replaced the phone number with a string of text and that was all there was to it.

145 countries is not all all the countries

Well, ok, it’s that simple only if you are sending SMS messages to one of the 145 countries that support this feature. If you are sending to multiple countries and one of them, like the US, doesn’t support alphanumeric sender IDs then there is a bit more work to do.

Send a message using an alphanumeric sender ID to a number in a country that doesn’t support it and the Twilio API will respond with an HTTP 400 response. The body of the response will contain the Twilio specific error details, including a Twilio error code and error message. The error code that represents our problem, sending an SMS message from an alphanumeric sender ID to a country that doesn’t support it, is Twilio error code 21612.

The HTTP response will manifest itself in the Ruby library as a  Twilio::REST::RequestError. We can rescue the exception and query the error for the code to check it is the error we expect by making sure it has code 21612. If it is we can retry sending the message using a Twilio number as the sender. Here’s how that would work:

 

require 'twilio-ruby'

account_sid = YOUR_ACCOUNT_SID
auth_token = YOUR_AUTH_TOKEN
alphanumeric_id = "Phil"
twilio_phone_number = YOUR_TWILIO_NUMBER
recipient_phone_number = RECIPIENT_PHONE_NUMBER

client = Twilio::REST::Client.new(account_sid, auth_token)
begin
  client.messages.create(
    from: alphanumeric_id,
    to:   recipient_phone_number,
    body: "Hello, this is a message from Phil"
  )
rescue Twilio::REST::RequestError => error
  if error.code == 21612
    client.messages.create(
      from: twilio_phone_number,
      to:   recipient_phone_number,
      body: "Hello, this is a message from Phil"
    )
  else
    # handle this some other way
    raise error
  end
end

 

You can now try this script against a number from a country that doesn’t support these messages, like the US, Japan or Belgium. Once the API responds with the error the script will fallback to using the supplied phone number as the sender.

If other errors are raised they will cause this script to crash and you should handle those errors in an appropriate manner for your application.

Brand those SMS messages

There we go, you can now:

  • Improve the user experience for SMS alerts and broadcasts by branding your SMS message sender
  • Fallback successfully in cases where the receiver is in a country that won’t accept an alphanumeric sender ID

Remember that using an alphanumeric sender ID is not appropriate in all possible uses of SMS as recipients cannot respond and in cases where you can use this feature it is important to provide alternative ways for users to opt out of these messages.

As always, if you have any further questions about this drop a comment below, give me a shout on Twitter or shoot me an email.

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.