10

Getting started with inbound messages

People can reply to your SMS messages using keywords. You can use replies to track engagement or trigger campaigns.

How it works

SMS messages frequently include keywords that trigger downstream actions—like STOP to opt-out of messages or HELP to understand the things people can do through SMS replies.

Customer.io handles these replies, helping you trigger campaigns and segment your audience based on replies to your messages.

For example, you might ask people to reply to a message with a keyword if they want updates for a particular event or product. You can then add people who reply with the appropriate keyword to a segment and trigger a campaign to send them follow-up messages.

Before you get started, you’ll need to:

1. Make sure you’re set up for inbound messages
2. Capture a phone attribute so we can trace inbound messages to the correct person in Customer.io

Set up inbound message handling

If you manage SMS sending entirely through Customer.io, this is already done for you. You don’t need to do anything to support inbound messages.

If you have your own Twilio account, you need to point your messaging service’s Inbound Request Config to Customer.io. This forwards inbound messages to Customer.io.

1. In your Twilio Console, go to the Develop tab and click Services.

   

   
2. Select the messaging service you use with Customer.io and go to the Integration page.
3. Under Incoming Messages, select Send a webhook and enter our URL: https://track.customer.io/inbound/sms for US customers or https://track-eu.customer.io/inbound/sms for EU customers.

   

   
4. Click Save to apply the change.

Now inbound messages are forwarded to Customer.io. You can test this by sending a message to your messaging service phone number and checking the Activity Log in Customer.io to check for your inbound message.

You must use the phone attribute

To successfully parse inbound messages, you must store phone numbers as a phone 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. in E.164 format. For example, you might typically represent a phone number like 555-123-4567, but the E.164 format for that same phone number is +15551234567.

When someone sends a message, we look for a person with the phone attribute that matches the phone number in the message. This works best if everybody in your workspace has a unique phone number.

If you don’t set a phone number in E.164 format, we’ll do our best to parse numbers into this format when we resolve inbound messages to people in Customer.io—but we can’t guarantee that we’ll be able to do this. (We use Google’s libphonenumber library to parse phone numbers, and we skew towards US and Canadian numbers.)

Reformatting phone numbers to E.164

You need to use this format in Customer.io so we can read them correctly. You typically write a US-based phone number like 555-123-4567 or a UK-based phone number like 020 7183 8750. But E.164 formatted-numbers look like +15551234567 or +442071838750.

To format your phone numbers in E.164, you’ll follow this structure:

• A plus sign (+), which replaces the International Call Prefix (like 011)
• The International Country Calling Code (like 44 for the UK, 1 for North America)
• The Local Area Code
• The Local Phone Number (or Subscriber Number)

Phone numbers should be unique

To ensure that you don’t send duplicate messages and help us attribute inbound messages to the correct person, you should make sure that each person has a unique phone number in your workspace.

While we recommend that you store unique phone numbers for each person, people in Customer.io can have the same phone number. If two people have the same phone number, and both of those people enter a campaign that sends SMS messages, you could send duplicate messages to the same phone number.

If two people have the same phone number and you get an inbound message from that number, we’ll attribute inbound messages to the oldest profile—the person who was created first in your workspace.

If two people share a phone number, and you receive an opt-out keyword from that number, we’ll opt both people out of messages. Opt-in and opt-out keywords affect a phone number, so everybody with the same phone number is opted in or out of messages when we receive an opt-in or opt-out keyword from that number.

Inbound messages for unrecognized numbers

If we can’t match an inbound message to a person we treat the inbound message as an anonymous event. You can’t respond to anonymous people with SMS messages in Customer.io.

This typically happens when:

• You receive an SMS from someone you haven’t identified
• Your phone attributes aren’t in the proper E.164 format.

Even if you identify the person who sent the inbound message, the inbound message will remain anonymous. There’s no way to reconcile the anonymous inbound message with the identified person later.

We automatically handle opt-in and opt-out keywords

You don’t need to set up anything special to handle opt-out or opt-in keywords.

We automatically opt people out of messages from appropriate numbers when they reply with keywords like STOP or UNSUBSCRIBE—or opt them in if they reply with keywords like START or UNSTOP.

You can add people to segments based on their opt-out status using the Opt out condition. Then you can use this segment to target (or exclude) people who’ve opted out of a particular sender number.

Twilio automatically responds to STOP keywords

When someone responds with a STOP keyword, Twilio sends users a reply indicating that they’ve been opted out. This message doesn’t go through Customer.io and isn’t logged by us.

When someone opts out of messages this way, Customer.io logs the inbound message containing the STOP keyword and reflects the person’s opt-out status, but won’t reflect the SMS response from Twilio. You can customize this response in the Twilio console using Twilio’s Advanced Opt-Out feature.