Build the future of communications.
Start building for free

Send Branded SMS Messages Using Twilio Alphanumeric Sender ID

phone

It’s been a few months since we hosted Signal (if you missed it, don’t forget that videos from all the sessions are available online) 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.

Authors
Sign up and start building
Not ready yet? Talk to an expert.