10

Respond to inbound keywords

When people send you SMS messages, you can use campaigns to handle the incoming messages and trigger responses.

How it works

We treat inbound messages like events in Customer.io: they can trigger campaignsCampaigns are automated workflows you set up to send people messages and perform other actions when they meet your criteria. and add people to segmentsA segment is a group of people in your workspace. Use segments to trigger campaigns, track membership over time, or fine-tune your audience. There are two types of segments: data-driven and manual. Data-driven segments automatically update when people start or stop matching criteria. Manual segments are static..

We handle inbound messages by looking for keywords. Think of it a bit like the menu you hear when you call somewhere that has an automated phone system: the phone system prompts the user to press an option on the keypad to advance to the next message.

Except in this case, rather than pressing the right button to advance in a menu, the user responds with a keyword from a list of supported keywords, and you send them down a path based on the keyword they used.

Set up an inbound message campaign

1. When you set up a campaign, click the Trigger.
2. Select the Event trigger option.
3. Change they perform the event to they send an inbound SMS.

The Inbound message event that triggers your campaign doesn’t differentiate between replies to different phone numbers. If you want to handle inbound replies to your different sender numbers independently, you should add conditions to your trigger based on the to value. (Inbound messages come from your audience and to your SMS “sender” number.)

Using inbound message data

Like other event-triggered campaigns, inbound message variables start with event. For example, referencing the keyword variable would be {{event.keyword}}.

Most of these values come directly from the inbound message, but there are rules to the keyword variable.

{
    "body": "start",
    "from": "+15551234567",
    "keyword": "START",
    "messaging_service_sid": "MG1c4d997a947f60dfaddf382a32dffc11",
    "sid": "SMec32f5db600322613b0c592d4d7417f1",
    "to": "+15559876543"
}

Keywords

We support the pre-defined keywords below. A person can respond with any of the supported terms—lowercase, uppercase, or any combination of cases—and we’ll match on the appropriate keyword. This simplifies the logic when you respond to inbound messages. You don’t have to account for each possible variation of our pre-defined keywords.

Beyond our pre-defined terms, you can also tell people to respond with custom keywords. For example, if you want to run a survey, you could ask people to respond 1-5 to indicate satisfaction.

If an inbound message contains multiple words, the keyword variable will be empty. If this happens, you can respond with a message that tells the user to try again with one of the supported keywords.

Example campaign and best practices

In the campaign below, you’ll see that we’ve done a few things:

1. We’ve set up a Multi-split branch to handle different keywords—STOP, START, and HELP. We’ve also added another branch to handle cases where we don’t recognize the incoming keyword.
2. For the STOP keyword, we can’t send a follow-up message. Instead, we set an attribute on the person to help us track that they’ve opted-out of SMS messaging for that number. This lets us add people to a segment that we can include or exclude from different campaigns.

Filter by sender number or outbound message

If you want to handle keywords differently based on the sender number or a specific message, you can add that as a Filter to your campaign trigger.

Set up branches to handle different keywords

As you can see below, we’re handling branches for STOP, START, and HELP. We’ve also added a branch to handle cases where we don’t recognize the incoming keyword.

We automatically treat all opt-out keywords as STOP and all opt-in keywords as START; this means you don’t have to create conditions for every possible matching keyword.

You cannot wait for subsequent messages in your campaign

In your campaign, you can’t wait for another inbound message or a follow-up event. You have to handle cascading inbound messages with subsequent campaigns.

You can still use the Wait Until action to wait for other conditions, but you cannot currently wait for a separate inbound message to continue through a campaign.

When to limit send rates

If you want to send an SMS broadcast or newsletter, and you want to respond to inbound messages on the same “sender” number in Customer.io, you should throttle your broadcast so that your inbound-based responses aren’t delayed by messages queued from your broadcast.

Imagine you send a broadcast to 100,000 people. SMS messages from a single phone number send at a maximum rate of 225 messages per second. This would take around 444 seconds to send, or around 7 minutes. If someone receives your message and responds immediately, and any subsequent message you try to send is added to the end of the queue. This means that any subsequent messages you send to your audience are be delayed by the time it takes to finish sending your broadcast.

Throttling broadcasts and newsletters ensures that your sender phone number can continue to send messages as it normally would, without being blocked by messages queued from your broadcast.