In this chapter we’ll look at how Rock handles incoming SMS messages using Rock’s SMS Pipeline feature.

Rock’s SMS Pipeline is the entry point for all incoming SMS messages. Think of it as a switchboard operator that's directing each message to its intended action.

The Fundamentals

Below is an overview of how the SMS Pipeline feature works. If some of these concepts are foreign to you right now, don’t worry. We’ll go over all the details in the next section.

1. An incoming SMS message is received into the pipeline.
2. The message flows down the pipeline, through a series of Actions. Actions are activities that the system performs, like launching a workflow.
3. Each action has filters. The pipeline uses filters to analyze the message and its contents against criteria you provide. If the message meets your criteria, then the action is performed. If not, the message moves to the next action. This process repeats until an action is performed.
4. When an action is performed, the pipeline looks at the action’s Continue setting. This determines if the message should continue down the pipeline to the next action, or if the matched action is all that’s needed.
5. If a message continues down the pipeline after an action has already been performed, it works the same way as described in #3 above. Satisfying the filter criteria for one action does not mean the message automatically satisfies the filters on the remaining actions.

These general steps are repeated for each new message you receive. That means you can use a single pipeline to perform different actions for a variety of scenarios.

Anatomy of Actions

Actions automate many of the tasks you would want to perform in Rock after receiving a text message. For instance, you might want to send the person an automated reply message. Or you might want to launch a workflow if the person’s message contains certain keywords.

Each action you add has its own settings and filters, giving you full control over what should happen and when.

There are four SMS Pipeline actions:

• Give
• Launch Workflow
• Reply
• SMS Conversations

We’ll use the Reply example pictured below to describe the properties of actions in general. Then in the following sections we’ll dive into each type of action individually. The below page can be accessed from Admin Tools > Settings > SMS Pipeline.

Add Actions

As noted in the prior section, all actions share some common properties. However, each type of action has unique features and properties that we’ll describe in detail below.

SMS Conversations

This action will send the message over to the SMS Conversations page, at which point you’re messaging with the person directly. There is only one filter for this action, and no additional unique properties.

Remember, the phone number filter references the number to which the person sent the message, not the person’s phone number. If this is left blank, then every message that reaches this action will go to the SMS Conversations page.

As pictured above, the SMS Conversations action is typically at the bottom of the pipeline. If the person’s message doesn’t meet the criteria for any of the other actions, this is how you can ensure it doesn’t fall through the cracks.

Reply

The Reply action is an easy way to automate responding to an incoming text. You can customize the content of your response and personalize it for the recipient using Lava. The reply action can in some cases eliminate the need for a workflow if a specific message is always to be returned.

1. Message Filter - You can check the content of the incoming text message against key words you provide. You can add as many of these conditions as needed. You can also select whether the message requires "any" or "all" of those criteria to match.
2. Response - This is the content of your organization's response, which will be sent if the incoming message meets the filter requirements. You can personalize the response using Lava, and you can even add an attachment. You can attach JPG, GIF, and PNG images for all carriers, but other file types may not work depending on the carrier and device. Send a few test messages to different carriers and phone types to confirm the attachment is delivered correctly before sending to a wider audience.

The example pictured above will only perform the Connect Response action if the words "serve" or "volunteer" are somewhere in the message's text. If the incoming text says "I would like to serve" then the contents of the Response field will be sent to the person as a text message. In this particular example a workflow might also be launched for this message, because the Continue option is enabled.

Launch Workflow

As the name implies, this action will launch a workflow. You’ll want to configure your workflow to receive information from the pipeline, using the same workflow attribute merge fields we cover in the SMS Pipeline Workflows chapter of the Blasting Off with Workflows guide.

Launch Workflow Action

Give

This action enables Text Giving functionality, allowing a person to send a text to donate using their phone.

The Give action isn't ready to use out of the box. An administrator will need to configure the settings for the Utility Payment Entry block in addition to SMS Pipeline setup. For details on Text Giving and the required configuration, head over to the Rock Solid Finances manual.

Use The Pipeline

Let’s look at a completed pipeline to see how this all comes together. This pipeline has four actions and was designed to handle inquiries about small groups and connecting. Below each screenshot we’ll highlight the key points.

As pictured above, when an incoming text contains the word 'group', an auto-response will be sent to the person with more information about joining a group. In this case the processing stops, because the Continue option is not enabled.

If the SMS message doesn't contain the word 'group' then the "Connect Response" action will be evaluated because it's the next in line. If the message contains the word 'volunteer' or 'serve' an auto response gets sent with more information about getting connected to a serving team. The arrow on the action indicates that the continue functionality is enabled, and the next action will run if the message meets the requirements.

You'll note in the screenshot above that the workflow action has the same filters as the "Connect Response" action. That means any message which activates the "Connect Response" action will also launch this workflow.

Lastly, the pipeline continues down to the “SMS Conversations” action so that a staff member can directly connect with this person.

In this case, the "SMS Conversations" action has no filters applied. Knowing this, and looking at the pipeline as whole, all incoming SMS messages will end up in the SMS Conversations page except messages that contain the word 'group'.

If we enabled Continue in the "Group Response" action, then every incoming SMS message would go to the SMS Conversations page. In that case, a message containing the word 'group' would not satisfy the "Connect Response" and "Launch Workflow" filter criteria, so those actions won’t be performed.

In this example pipeline, if an SMS message is received that says "I'd like to learn more about your services" it would pass through the pipeline straight to the "SMS Conversations" action. No automated replies would be sent, and no workflows would be launched for that message because it does not meet the criteria for those actions.

SMS Pipeline Lava

You can use Lava to customize and personalize your pipeline’s actions. There are different merge fields depending on whether you're working with the Reply or Launch Workflow action.

Launch Workflow Action Lava

Below is a list of Lava merge fields you can include in your pipeline when you're working with the Launch Workflow action. These are the same workflow attribute merge fields we cover in the SMS Pipeline Workflows chapter of the Blasting Off With Workflows guide.

SMS Pipeline Workflow Lava Merge Fields

Reply Action Lava

Below is a list of Lava merge fields you can use when you're working with the Reply action. Note that each uses a prefix of Message.

SMS Pipeline Reply Lava Merge Fields

Add a New Pipeline

Technically a single pipeline is all you need in Rock. After a while though, you might find that your single pipeline becomes complex, especially if you have multiple numbers that you are supporting. In this case you can create additional pipelines. Please note though that a single SMS phone number can only work with a single pipeline, but a pipeline can service multiple SMS numbers.

To start, navigate to Admin Tools > Settings > SMS Pipeline. From here you can add, delete or edit your list of pipelines.

Click the ti ti-circle-plus button to add a new pipeline or click an existing pipeline to access its details. You can edit the 'Default' pipeline that ships with Rock, or you can create your own. In this example we’ll add a new pipeline from scratch so you can see the process.

The first thing you’ll need to do is provide a name and description for the pipeline. If you have multiple pipelines, be sure to make the name and description clear.

Click the Save button, and that's all you need to start configuring your new pipeline using the instructions in the above sections. Remember, each pipeline can be associated with its own webhook (see below) for added flexibility.