Handling Inbound SMS Messages

Users can respond to your SMS messages if your sender ID supports it. Create unique and interactive user experiences for sign-ups, discounts, opt-outs, and more using two-way SMS messaging in Iterable.

# In this article

# About SMS replies

Here are some things to know about receiving SMS messages in Iterable:

# Eligible sender IDs

Not all sender IDs support SMS replies. This support varies depending on the type of sender ID that sent the message. Alphanumeric senders, for example, can't receive replies. You also need inbound SMS services activated with your SMS provider.

If you aren't sure if you can receive SMS replies, check with your Iterable customer success manager for help.

# Replies are lowercase

Iterable records SMS replies in all lowercase. If a user sends a reply of "JOIN", Iterable records the message as "join" in the SMS reply event's smsMessage field. You don't need to create regular expressions or exhaustive list filter conditions to parse or otherwise account for multiple casing (Title Case, camelCase, ALLCAPS, etc).

# Automated actions

Certain SMS replies are set up as keywords that have associated actions. These keywords vary depending on your SMS provider, but fit in these general categories:

• Unsubscribe keywords, that unsubscribe phone numbers in Iterable and with your SMS provider
• Subscribe keywords, that subscribe or re-subscribe phone numbers in Iterable and with your SMS provider
• Help keywords, that have an autoresponse from your SMS provider that sends opt-out instructions. Usually this is just "HELP".

To learn more about the default keywords that work for your SMS sender, read SMS Unsubscribes and Resubscribes.

SMS providers may also set up custom keywords, so make sure you're aware of how your account is set up with your SMS provider (Iterable SMS, Telnyx, or Twilio).

# Viewing inbound SMS messages

When a user replies to a two-way enabled SMS sender, Iterable saves these responses as SMS reply events on user profiles.

# Viewing the inbound SMS log

To see a list of the 250 most recent incoming SMS messages across your project, go to Insights > Logs > Inbound SMS.

Here, you'll see a log that includes:

• Email or User ID - the user's unique identifier.
• Created - The time the message was sent.
• Message - The SMS message body received.
• From Phone Number - The phone number that sent the message.
• To Phone Number - The sender ID the message was sent to.

# Viewing inbound SMS messages for a campaign

To view the inbound SMS associated with a particular campaign:

1. Go to Messaging > Campaigns and find the SMS campaign you want to view the replies for.
2. Click View Analytics (just under the delivery rate metric).
3. Adjust the time range filter to limit the range of data you want to export.
4. Click on Export Events, select SMS Received, and click Export.
5. When prompted, download and open the smsReceived.csv file.

# Viewing a user's inbound messages

To view an individual user's SMS messages, go to Contacts > Audience Lookup and look them up. Find the smsReceived events in the user's event history.

# Example SMS received event

{
  "createdAt": "2022-05-17T23:17:45.000Z",
  "email": "user@example.com",
  "eventType": "smsReceived",
  "fromPhoneNumber": "+14155550132",
  "itblInternal": {
    "documentCreatedAt": "2022-05-17 23:17:46 +00:00",
    "documentUpdatedAt": "2022-05-17 23:17:46 +00:00"
  },
  "smsMessage": "help",
  "toPhoneNumber": "+14155550132"
}

# Using Export API

To export all inbound messages for a project, use Iterable's Export APIs and specify smsReceived for dataTypeName.

You can use additional data filters to export more specific campaigns—by date, campaign, etc.

# Using SMS replies in journeys

All inbound SMS messages can trigger a journey. Consider discussing your use cases with your customer success manager before using a journey to respond to SMS replies.

There are many scenarios to anticipate when using a journey to respond to incoming SMS messages. Among these:

• Sending promotional discount codes as incentive for opting in to SMS.
• Sending a series of messages or reminders that users can sign up to receive.
• Creating an interactive user experience in general.

# Starting a journey with a SMS reply

To trigger a new journey to start from an incoming SMS message, use SMS Reply as the entry source in the Start tile. If necessary, add a filter on the contents of the incoming message's smsMessage field, with lowercase text of the keyword or messages.

For example, to trigger a journey with the keyword "join":

To learn more about using an event to start a journey, read Setting Up the Start Tile

# Pausing a journey until a SMS reply

You can use a Hold Until tile to delay a journey until a user sends a SMS reply, and use the text content of their reply to determine their next step.

To learn more, read Adding Delays to a Journey.

# Managing typos in SMS replies

When you create journey conditions that use SMS reply as a trigger, consider including a strategy to handle typos that accepts those that you can plan for and asks your users to try again when their response isn't accepted.

# Accept anticipated typos

Guess what typo responses may look like, and build filters for them. You can try and think through the typos that a user could make on their phone screen, and accept them all by using a filter with ANY criteria.

In this example, this filter accepts several variations of the word “JOIN”.

You can use this strategy when creating user segments as well as journey filters.

# Ask users to try again

If you use a Yes/no journey tile, responses that don't meet your accepted filters for "Yes" would go down the “No” path. You can have this path send a response message in reply, asking them to try again or contact support.

# Use unique keywords

Instead of asking users to send a generic keyword and planning for typos, you could alternatively use a unique code that is specific for your particular use case. This reduces ambiguity and requires your user to pay more attention when they are typing it to send. Examples: FALL2023, yesplease.