Twilio SMS: Get Started

Updated

Let’s get you started using Twilio to send SMS to your customers as part of your triggered campaigns!

How it works

We send SMS (text) and MMS (PNG, JPEG, and GIF image) messages through Twilio. Before you can send messages to your mobile audience, you’ll need to set up a Twilio account.

 Customer.io doesn’t set up or manage your Twilio account

While we partner with Twilio to send SMS messages, you’ll have to set up and manage your own Twilio account—including things like adding senders and setting up keywords.

To make sure that your messages go to the right people, you’ll need to store people’s phone numbers as attributesA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines.. When you send an SMS or MMS message, you’ll point to this attribute using liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}. so we know where to send the message.

  1. Set up your Twilio account.

  2. Store your audience’s phone number(s) as attributes.

  3. Set up a message.

Send an SMS or MMS message
Send an SMS or MMS message

MMS messages

When you enable Twilio SMS, you can also send images. When you send a Twilio SMS message with an image, it becomes a multi-media message (MMS). MMS messages can help you make your point when 160 characters just aren’t enough. However, before you send an MMS message, you should take into account:

  • Images must be PNGs, JPEGs, or GIFs

    The URL you host must end in the image format for us to attach it to your message.

  • Maximum image size is determined by recipient carrier, so you should limit image size to 600kb where possible.

    While our asset library accepts files up to 3MB, and Twilio sometimes allows attachments up to 5MB, the maximum image size for MMS is typically much smaller. Recipient carriers enforce their own size limits, many down to just 600kb. We recommend that you use the smallest possible images to ensure that your audience sees your image, regardless of their carrier and connection quality. If you use a short code or a toll-free carrier, your image may be limited to 600kb. Your message can also include up to 1600 characters.

  • MMS messages are slightly more expensive than SMS messages

    This is because MMS messages are typically larger than SMS messages; this pricing model is not unique to Twilio. But you may want to reserve MMS messages for your most meaningful mobile interactions.

  • MMS messages are limited to the United States and Canada.

    MMS messages sent to someone in another country will fail.

Set up Twilio SMS

To send Twilio SMS and MMS messages in Customer.io, you’ll need to have a Twilio account and the Sender phone number. This might be a regular phone number, short code, or an alphanumeric ID.

Twilio can lease these numbers to you. Or, if you have a paid Twilio account with Alphanumeric Sending enabled, you can send messages from an Alphanumeric ID instead of a Twilio phone number.

  1. Set up a Twilio account if you don’t already have one. We recommend using a trial account to get started.

  2. Set up a Twilio-specific Sender if you don’t already have one. You can’t use your own phone number to send SMS; you need to purchase a number from Twilio. If you already set up your sender number, you’ll select it when you compose messages.

  3. In your Customer.io workspace, Go to Data & Integrations > Integrations > Twilio SMS and add your Account SID and Auth Token. You’ll find these values in your Twilio dashboard. We only support credentials associated with the US Twilio region.

    Find your credentials in the Twilio dashboard
    Find your credentials in the Twilio dashboard

 Don’t use your test credentials

You might see a set of test credentials on your Twilio account page. Don’t use these credentials! To send SMS with Customer.io, you need to use your live credentials.

Now the Twilio SMS option is available in your workflows, letting you set up SMS and MMS messages in your campaigns and broadcast workflows.

Add phone numbers to people in Customer.io

To send people SMS messages, you need to store their phone numbers as an attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines.—for example, an attribute called phone. If you store multiple phone numbers, you might label them primary_phone, cell_phone, etc. You’ll select the phone number you want to use when you send your message. If you have multiple phone number values, you can use liquid to pick the right one.

{% if customer.primary_phone %}
    {{customer.primary_phone}}
{% else %}
    {{customer.cell_phone}}
{% endif %}

You should store phone numbers in E.164 format. If your numbers aren’t stored in this format, Twilio may not be able to detect your phone number format and messages may not make it to your audience. E.164 is the internationally-standardized format for all phone numbers, containing up to fifteen digits and usually written as shown below. See Twilio’s documentation for more information about E.164 phone numbers.

[+][country code][subscriber number including area code]

Here are a few examples:

CountryLocalE.164
USA415 555 2671+14155552671
UK020 7183 8750+442071838750
China021 6309 5246+862163095246
Australia(08) 9287 8230+61892878230

 Twilio can send SMS messages almost anywhere

We send SMS messages through Twilio, so we support all the countries Twilio supports. That accounts for most countries worldwide. But before you send SMS messages, you should check if there are any restrictions based on your recipients’ phone numbers.

Sender phone numbers

After you successfully enable Twilio, you’ll see your synced phone numbers, short codes, and messages services below your credentials.

Using liquid to select your sender

You may want to dynamically select between multiple Sender IDs at the time each message is sent. Liquid code can be added as a Manual Sender ID to accomplish this. For example, if you wanted to send from a different phone number depending on which Customer Success Manager is assigned to the customer, you could insert a code block such as:

{% if customer.CSM == "stephen" %}
+1647STAPHEN
{% else if customer.CSM == "zack" %}
+1800GOTZACK
{% else %}
+1800CUSTOMR
{% endif %}

Syncing Phone Numbers and Message Services

If you add or change any of these sender identities in your Twilio account, you’ll need to re-sync them here before using them in your messages.

Using a Manual Sender ID

You’ll see Manual Sender IDs in your Twilio Settings. You can add an Alphanumeric Sender ID, a Message Service ID, or provide some Liquid that dynamically determines the Sender ID for each message here.

twilio_config.png
twilio_config.png

Adding an Alphanumeric ID

Alphanumeric IDs can help your messages stand out, but they have a few quirks:

  • They’re one-way: Your customers cannot reply to them.
  • Opt-in/opt-out: Customers must opt into messages from your ID, and be informed on how to opt out.
  • *Alphanumeric IDs aren’t supported in all countries, including the USA: If you try to send to an unsupported country from an Alphanumeric Sender ID, your message will fail to send.

To set up an alphanumeric ID:

  1. Enable alphanumeric IDs in Twilio first! You can add alphanumeric senders in Customer.io, but if you haven’t enabled the feature in Twilio, messages using your alphanumeric sender will fail.

  2. Go to Data & Integrations > Integrations > Twilio SMS and click Add Sender ID.

  3. Enter your Sender ID and the Name you’ll use to refer to your sender.

    • Name: this is how you’ll refer to the ID internally; your customers won’t see this.
    • Sender ID: You can use both upper- and lower-case ASCII letters, digits 0 through 9, and spaces in your ID. Your ID must contain at least one character that isn’t a number.

Add Twilio messages to your workflow

After you enable Twilio in your workspace, you’re ready to send SMS and MMS messages!

  1. Drag Twilio SMS into your workflow.

  2. Give your message a Name that makes sense to you. Your audience won’t see this name.

  3. Click Add Content to write up your message.

    image.png
    image.png
  4. In the From field, select the sender ID you want to send your message from. Remember, you can use liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}. to send from different numbers based on attributes or other criteria.

  5. In the To field, use liquid to set the customer’s phone number attribute—like {{customer.phone}} if you store your audience’s phone number in the phone attribute.

  6. (Optional) If you want to send an MMS message, enter a URL of your image (PNG, JPEG, JPG, or GIF) in the Image field. Remember, your image must be smaller than 1.5MB.

  7. Enter the body of your message. MMS messages support up to 1600 characters.

Send an SMS or MMS message
Send an SMS or MMS message

Send a test message

To make sure your SMS works, you can send a test message clicking Send test… in the top right-hand corner of the composer. You’ll see a modal, into which you can enter a phone number to which you can send your message.

image.png
image.png
Copied to clipboard!
  Contents
Is this page helpful?