# 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[](#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](#set-up-inbound-message-handling)
2.  [Capture a `phone` attribute](#you-must-use-the-phone-attribute) so we can trace inbound messages to the correct person in Customer.io

## Set up inbound message handling[](#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**.
    
    [![The Twilio services page showing a single messaging service](https://docs.customer.io/images/inbound-sms-twilio-services.png)](#94bd6d2bed58cf2c34f883f56006681f-lightbox)
    
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.
    
    [![The Twilio integration page showing the webhook set up for Customer.io](https://docs.customer.io/images/inbound-sms-twilio-integration.png)](#696732752c6f66d73be70bf4d6764f23-lightbox)
    
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[](#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.](/journeys/attributes/) in [E.164 format](https://en.wikipedia.org/wiki/E.164). 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](https://github.com/google/libphonenumber) library to parse phone numbers, and we skew towards US and Canadian numbers.)

### Reformatting phone numbers to E.164[](#phone-number-formatting)

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[](#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[](#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](#phone-number-formatting).

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[](#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](/journeys/inbound-campaigns#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](/journeys/sms-keyword-opt-out) 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.

[![A segment condition showing users opted out of a particular sender number](https://docs.customer.io/images/sms-opt-out-segment.png)](#8249f0de6bc6db95463951ff613f7012-lightbox)

## Twilio automatically responds to `STOP` keywords[](#twilio-stop)

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](https://www.twilio.com/docs/messaging/tutorials/advanced-opt-out).