Table of Contents

  1. Getting Started
    1. Creating an Account
    2. Account Page Primer
    3. Multi-User Support: Adding, Editing & Removing Multiple Account Users
    4. Multi-Tier Accounts: Child Accounts & Credit Distribution
    5. Using the Support Widget
    6. Adding Credits
    7. Managing your Timezone and Date Format Settings
    8. Managing your Language Settings
    9. Message Content Basics
    10. Message Content Best Practices
    11. Using the Simulator
  2. Channels
    1. Introduction to Channels
    2. Adding a Channel
    3. Removing a Channel
    4. Using an Android phone as a Channel
    5. Using a Bulk Sender
    6. Adding a Twilio Number
    7. Adding a Twilio Messaging Service
    8. Managing Opt-Outs on Twilio Channels
    9. Integrating Using the External Channel API
  3. Messages
    1. Introduction to Messages
    2. Archiving Messages
    3. Exporting Messages
    4. Labeling Messages
    5. Deleting Messages
    6. Schedule a Message to be Sent Later
  4. Contacts
    1. Introduction to Contacts
    2. Creating a Contact
    3. Adding, Editing & Prioritizing Contact Addresses
    4. Adding Contact Fields
    5. Deleting Contact Fields
    6. Editing Contact Field Values
    7. Searching for Contacts
    8. Setting the Language for a Contact
    9. Blocking Contacts
    10. Importing & Exporting Contacts
    11. Contact Information Anonymization
  5. Groups
    1. Introduction to Contact Groups
    2. Creating a Contact Group
    3. Adding Contacts to a Group
    4. Dynamic Contact Groups
    5. Deleting Contact Groups
  6. Flows
    1. Introduction to Flows
    2. Flow Types
    3. Creating a Flow
    4. Navigating the Flow Editor
    5. Assigning Keywords to a Flow
    6. Starting a Flow
    7. ActionSets
    8. Sending Messages with a Flow
    9. Sending a Message to Someone Else
    10. Adding and Updating a Contact Field
    11. Sorting Contacts into Groups
    12. Setting a Contact's Preferred Channel
    13. Setting your Contacts' Language Preferences
    14. Adding Labels to Responses
    15. Sending an Email
    16. Starting another Flow
    17. Starting Someone Else in a Flow
    18. RuleSets
    19. Response Rules
    20. Split by Message Form
    21. Calling a Webhook
    22. Creating a Multi-Language Flow
    23. Introduction to Flow Variables
    24. RapidPro Variable Reference
    25. Organizing Flows with Labels
    26. Viewing and Exporting Flow Results
    27. Exporting a Flow
    28. Importing a Flow
  7. Triggers
    1. Introduction to Triggers
    2. Creating a Keyword Trigger that starts a Flow
    3. Creating a Keyword Trigger that allows people to join a Group
    4. Starting a Flow in the future or on a schedule
    5. Ignoring Keywords while in a Flow
    6. Start a Flow after receiving a message not handled elsewhere
  8. Campaigns
    1. Introduction to Campaigns
    2. Creating a Campaign
    3. Adding a Campaign Event
    4. Editing Events
    5. Deleting Events
    6. Editing Campaigns
    7. Archiving Campaigns
    8. Activating Campaigns
  9. Voice (IVR)
    1. Adding a Voice-enabled Twilio Number
    2. Adding a Voice-enabled Nexmo Number
    3. Adding IVR to your Android Channel
    4. Creating a Voice (IVR) Flow
    5. IVR Flow RuleSets
    6. Adding Audio to Play Message Actions
    7. Simulating an IVR Flow
    8. Replaying a Contact Recording
    9. Viewing Call Logs
  10. Zapier
    1. Integrate Zapier with your RapidPro Account
  11. Facebook Messenger
    1. Introduction to Facebook Messenger
    2. Create and Submit your Bot for Review
    3. Triggering a Flow When a Contact Initiates a Conversation
  12. Telegram
    1. Introduction to Telegram Channels
    2. Adding a Telegram Channel
  13. Twitter
    1. Introduction to Twitter Channels
    2. Connecting your Twitter Account to RapidPro
    3. Creating a Twitter Workflow
    4. Creating a Follow Trigger
  14. Surveyor
    1. Introduction to the RapidPro Surveyor App
    2. Creating a Surveyor Flow
    3. Adding Surveyors
  15. Expressions
    1. Expression Syntax
    2. Logical Comparisons
    3. Date & Time Arithmetic
    4. Function Reference
  16. Testing/Troubleshooting
    1. Conducting a Pilot Test
    2. A/B Testing your Flows
    3. Conducting a Usability Test
    4. Troubleshooting Protocol for Delivery Errors
    5. Tracking and Managing Opt-Outs
  17. F. A. Q.
    1. How does RapidPro Store and Secure my Data?
    2. What is RapidPro's Privacy Policy?
    3. What are RapidPro's Terms of Service?
    4. Can I use RapidPro for Voice (IVR)?
    5. Can I use RapidPro in my country?
    6. Can I use a dual SIM phone as an Android channel?
    7. What's the difference between @contact and @step.contact?
    8. Does RapidPro have an API?
    9. How does RapidPro decide which Channel sends a message?

Getting Started 1

1.1 Creating an Account

Creating a RapidPro account is quick, simple and free. We even provide 1,000 complimentary credits to help you get a feel for the platform.

To begin, you'll need to enter your email address at our landing page.



You'll be prompted to fill out the basic information required to construct your account: 
*We use your email address to send you service updates, account notifications and a weekly email containing feature updates, educational content and mobile communication articles curated for those operating SMS & IVR services.



The organization name you provide will become the name of your account. The timezone you provide should be the timezone in which you plan to send and receive messages or phone calls. 




1.2 Account Page Primer

Your account page is the heart of your RapidPro  account. From here, you can: 

1.3 Multi-User Support: Adding, Editing & Removing Multiple Account Users

Customers who purchase 100,000 or more credits unlock multi-user support, which allows them to add multiple users of varying roles to the account. This feature is intended for enterprise accounts, where multiple users may need to oversee your flows, campaigns, scheduled broadcasts and contacts, or routinely export information from the account.

To add additional users to your account, first navigate to your account's home page.

Scroll to the bottom and click the 'User Accounts..." icon.

Here, you can choose to manage account users via the 'Manage Accounts' button or, if you're using the RapidPro Surveyor app to collect information offline in the field, create a password that other Surveyor users can enter into the app to be able to submit responses to your account. Click the 'Manage Accounts' button.

The 'Manage User Accounts' page is where you'll add, edit and remove additional users of various roles. To add a users, simply enter their email address and select the permission you'd like to give them.

Account Roles

Surveyors

Surveyors have no administrative privileges, nor can they access the account. They may only submit flow results via our offline flow-based data collection mobile app, RapidPro Surveyor.

Viewers

Viewers can see every aspect of the account, but may not modify anything.

Editors


Editors can edit flows, campaigns, triggers and contacts; send messages; start flows; export flows, contacts and messages; and export/import flows. Editors cannot make changes to the account's home page, including managing account roles, changing language or timezone settings, and adding and removing channels.

Admins


In addition to editing privileges, admins may make the above-mentioned changes to the account's home page.

1.4 Multi-Tier Accounts: Child Accounts & Credit Distribution

Customers who purchase 1,000,000 or more credits unlock multi-tier account privileges, which allows you to add multiple child accounts and distribute credits to them through the originating, or parent, account. This feature is intended for organizations with multiple use cases across multiple countries, where it's useful to be able to create accounts for specific organizational branches and manage them from a central account.

Adding Child Accounts

To add a child account, first navigate to your account's home page.

Scroll to the 'Your organization is...' section and click the 'Manage Organizations' button.

Click the 'New' button in the top right corner of the page.

Distributing Credits


Select the 'Transfer Credits' option from the gear icon menu in the top right corner of the page.


On the resulting modal, select the origin and destination accounts, then enter the amount of credits you'd like to transfer.

Managing Accounts

To enter one of your child accounts, simply click the new account icon in the top right corner of the screen and select the account you'd like to enter.

1.5 Using the Support Widget

In the bottom right corner of each page you'll notice our support widget. The support widget is the best way to contact us, whether you've got a question, comment or suggestion, as it will alert the whole team and you'll be guided to the appropriate team member. 



To contact us, click the support widget and type your message.



You can include an image of your screen by clicking the "camera" icon. 



You can also use the support widget to help us decide which feature to add next. Cycle through others' suggestions or post your own. 



Once you've crafted your message and taken a screenshot, you can click the Skip and send message button to submit.



You're guaranteed a response within a business day, though we're often much quicker.

1.6 Adding Credits

Our pricing reflects our values: simplicity and transparency. We charge on a per-credit basis, and allow you to purchase credits in packages as you need them. A credit is equal to any message sent or received, and we provide 1,000 complimentary credits at sign-up to encourage you to test the flows you design.

Once you've used your credits, you'll need to top up to continue sending messages. Your remaining credits and the amount of credits you've used will be displayed on your account page 

Topping Up


To add more credits to your account:  

1. Click the link to your account page in the top right corner of the site, then click the "Add Credits" button on the right side of the screen.



2. Select the bundle that best suits the scale of your deployment. If you're unsure how many credits you'll need, we can help you decide on a package.  



3. Input your billing information. We also process payments via bank transfer - you can use the support widget to request an invoice.





1.7 Managing your Timezone and Date Format Settings

It's important that your account's Timezone and Date Format match those of the region in which you're sending and receiving messages. These settings affect features that require date & time values, such as campaignstriggers that fire on a schedule and anything operating on an @date variable

To edit your account's Timezone and Date Format, first navigate to your account page and click the organization icon to edit organizational settings. 



Then, select the appropriate Timezone and Date Format from their corresponding drop-down menus. If you plan to collect date & time values from your contacts, it's best to choose the most widely-used format in your region. 





1.8 Managing your Language Settings

Primary Language


Your account's Primary Language is the language in which your flows appear within the flow editor. Note that the Primary Language setting does not dictate the language in which your contacts receive messages. Rather, a contact's preferred language setting dictates the language in which (s)he receives messages. 

Additional Languages


Adding Additional Languages to your account is the first step in translating your flows. You may add any language that has been assigned an ISO 639-2/B code:


Once you've added Additional Languages to your account, they will be represented within the flow editor beneath the "Start Flow" button and settings menu. Below, the language in black is the Primary Language


Default Flow Language


The leftmost language displayed beneath the "Start Flow" button and settings menu represents the default language of a flow which, if other than your account's Primary Language, can be changed when creating a flow using the "Language" drop-down menu on the "Create Flow" dialogue: 



If the Primary Language of a flow is different from the Primary Language of your account as a result of being changed during flow creation, it will then become the leftmost language displayed beneath the "Start Flow" button and the settings menu: 



Click here to learn how to set a contact's primary language preference. 


1.9 Message Content Basics

Learn the basics to ensure a high completion rate:

Message Length


When entering your content into a message action, keep in mind that messages exceeding 160 characters will be sent as two messages. We provide a character counter beneath the message input of each message action to help you keep track: 


Educating your contacts on your service's intended purpose lessens the amount of content you'll need to fit into each message. This can be accomplished through marketing efforts, demonstrations, and training sessions.

Flow Length 


Indicating the length of flow in the initial message is a small but crucial step towards increasing a flow's completion rate. This allows you to immediately communicate the commitment required to complete a flow, which serves as subtle reminder that the interaction is automated and decreases the likelihood of receiving uncategorized responses:


Adhere to Industry Standards


+ Provide an opt-out (STOP) and assistance (HELP) keyword in your initial message to satisfy carrier requirements. Twilio handles these keywords themselves, so the important thing is having those words present somewhere in the message. Refer to this article for more information about managing opt-ins and opt-outs within RapidPro.

+ Establish 2-way messaging. An easy way to immediately establish 2-way messaging is to have your contacts start your flows using keyword triggers. Once a contact has entered your flow, contacts will respond asynchronously with varying answers. 

+ Vary message content. If you’re sending out a large broadcast, consider the amount of unique words in each message, as large amounts of identical messages may irritate a carrier. An easy way to ensure message variation is to reference variables within each message. The simplest way to do so is to reference each recipient’s first name (@contact.first_name), but you can create and reference other variables as you see fit.

Clarity


Try to be clear with your contacts regarding the types of responses you're looking for and what to expect from your flow. We advise including possible responses in each question whenever possible to increase response accuracy. In the example below, we're showing our target end users - health care professionals - the expected date format. In this case, our explanation is short and discrete; in others, you may need to provide a more descriptive explanation.



Use response rules to define acceptable answers and minimize the possibility of receiving responses in an undesired format. The more precise the response, the more accessible and better organized your data will be. 

In the example pictured below, we ask our contacts to tell us how they get their water. We've used multiple choice response rules to define the acceptable range of answers. These answers will be stored as values in a flow field called "Water Source". 



The response rule has all of the words indicates that any answers that don't have only the designated words Well, Tap, Stream, and Water Point will be categorized as "other."

Redirect Errant Responses


In rare instances, a contact may misinterpret a question or command and respond with a value that doesn't match the response rules you've created. To redirect responses, you may create a connection from the "other" category to an action step that reiterates the correct response format and then create a connection back to the initial split step: 


Language


Make sure your content is appropriate to your target audience. This can be accomplished by: 
While engaging Liberian youth, UNICEF translated the following questions using local, abbreviated language:

“Are you aware of the Ebola disease” became “do pple no abt Ebola.” 

“What information source do you trust” became “which 1 will pple take on d info abt Ebola.”
 
“What has changed the most in your community because of Ebola” became “wat bother U d most abt Ebola.” 

1.10 Message Content Best Practices

The following guide draws from the experiences of the US Centers for Disease Control & Prevention, Kaiser Permanente, and Code for America's GetCalFresh project. 

1) The CDC’s Guide to Writing for Social Media 2012

Be Clear and Concise:

Be Action-Oriented:

Be Useful and Relevant:

Use Web Content as a Source of Material:

Customize your Texts:

Provide Access to More Information:

2) CDC: Social Media Guidelines and Best Practices (2010), Sample Messages

Sample Messages:


"Test your smoke alarms and carbon monoxide detector when u turn your clocks back on Nov 1; replace batteries if needed. Call CDC 800-232-4636 or http://m.cdc.gov."

"Cover cough & sneezes to protect others. Call CDC 800-232-4636 or http://m.cdc.gov for more info. Reply HEALTH QUIT to end."

"Spread the word! Tell friends & family to text 4HEALTH to 87000 to get these weekly H1N1 messages & impt health tips. Call CDC 800-232-4636 or http://m.cdc.gov"

"Thanksgiving is Nat'l Family History Day. Talk to UR family about health conditions that run in UR family. Learn more http://m.cdc.gov/family. CDC 800-232-4636"

3) Kaiser to Roll out Text Messaging Appointment Reminders (2009), Lessons Learned

Lessons Learned:

4) Additional Tips



1.11 Using the Simulator

A important part of building something is testing it out. For this reason, we've included a simulator in the flow editor that allows you to test your flows from an end user's perspective - so you can quickly identify what works and what might need to be tweaked.

Accessing the Simulator


The simulator is accessed through the phone icon on the right side of the flow editor: 



Once clicked, the simulator will initiate the first step in your flow. The text in the orange boxes below represents the action log. The action log describes actions that occur within RapidPro that aren't visible to the end user when interacting with a flow. The action log in the flow simulated below indicates that the following: 


Check out this short video to see it in action: 


Channels 2

2.1 Introduction to Channels

Channels allow you to send and receive messages or phone calls through your RapidPro account. You can connect as many channels to your account as you want. Visit our deployment page for additional information on channels. 

Channel Types


Available channel types include Aggregators (SMS & Voice), Android Phone (SMS), Facebook Messenger, the RapidPro Surveyor Android app, Telegram and Twitter. We're always looking to add channels, so feel free to recommend one to support@app.rapidpro.io. 

Aggregator (SMS & Voice)


Aggregators are services that process messages across multiple carriers with exceptional speed and efficiency. They provide virtual mobile numbers and short codes that are easily connected to your RapidPro account through an API integration.

Examples of aggregators include, but are certainly not limited to:

Throughput


Throughput is the speed of the messages sent by your channel, measured in messages/second. For example, with toll-free Twilio numbers, throughput is 3 text messages/second, whereas standard virtual numbers send 1 message/second. . 

Adding Aggregators


We're always extending our network of local aggregators. If you don't see an option for your country, let us know. We'd be happy to help source a local aggregator that we can integrate with RapidPro for your country.

Voice 


See our IVR docs for more info. 

Nonprofit Discount:

Twilio.org offers $500 in credit and a 25% discount to nonprofit organizations who can furnish a determination letter.

Android Phone


RapidPro's proprietary channel, an Android Phone channel uses our free Android app to turn your phone into a message relayer for your RapidPro account. When your RapidPro account sends a message, it notifies your Android phone. The phone will then send the message out from your local number on your behalf. If somebody responds to that message, the phone will then relay that message to your RapidPro account. You can send up to 330 messages/hour by downloading our free message packs from the Google Play Store. 

Ideal for those who:
Click here to view our setup guide. 

Bulk Sending:

This channel option is ideal for Android channel deployments that need to send more than 330 messages per hour. It entails creating and connecting a Nexmo account to your RapidPro account. With bulk sending enabled, Nexmo handle your outbound messages while maintaining your Android phone's sender ID, and your Android phone will handle incoming messages.

Click here for information about Nexmo's performance in your country. 

Click here to view our guide to enabling bulk sending.

External API

The External API channel allows you to send and receive messages via external providers (those not already listed when adding a channel). This could be an external chat/messaging service or an aggregator not already listed (though we're happy to integrate with aggregators for a commitment of 100,000 or more credits). 

For example, if you want to leverage the automation RapidPro provides through an external service, you could write hooks for your system and connect them through your external API. RapidPro would then send and receive messages on via the external service.

As long as your contacts have the URN type your channel is configured to correspond with, we'll send outgoing messages using the endpoint you configure.

2.2 Adding a Channel

Adding your First Channel


Navigate to the channels tab and choose the channel that suits your project.
 Once you've connected a channel to your account, the channels tab will disappear and your channels will be listed in your account page.



 


Adding an Additional Channel


If you already have one or more channels connected to your account, you can add an additional channel by navigating to your account page, clicking the gear icon menu, and selecting the "Add Channel" option. 






2.3 Removing a Channel

To remove a channel from your account:

1. Go to your account page by clicking the link to your account page in the top right corner of your screen, then c
lick the channel you want to remove. 



2. In the selected channel's performance page, click the "gear" icon and select the "Remove" option.





2.4 Using an Android phone as a Channel

We understand that deploying SMS applications has traditionally been one of the trickiest parts when launching ICT4D projects. In fact, it's the primary reason we created RapidPro in the first place. It's also why we developed the Nyaruka RapidPro Android application

It's simple
: when your RapidPro account sends a message, it notifies your Android phone. The phone will then send the message out from your local number on your behalf. If somebody responds to that message, the phone will then relay that message to your RapidPro account. 

Message Packs


By default, each Android channel is capable of sending 30 messages/hour. You can send up to 330 messages/hour by downloading our free message packs from the Google Play Store. 

1. Buy an Android phone


We recommend purchasing a single-SIM Android phone, and dedicating it to processing your RapidPro messages. Android phones are both capable and inexpensive, and becoming more so every month. 

2. Acquire a local SIM card


If you don't already have one, you'll want to acquire a SIM card from your local carrier of choice. We recommend setting the account up to be data enabled. However, if you feel comfortable relying on your Wi-Fi connection, that's okay too. We also encourage that the account be on a post-paid plan so you don't have to worry about the phone running out of credit.

3. Install the RapidPro mobile application


You can download the free Android app from Google Play. Once the app is installed, it will give you a 9-digit claim code that you then enter on the website. That's all there is to it. From then on, that phone will handle sending and receiving messages for your RapidPro account.

4. Give the phone a good home


Android phones are great because they can be used in even the most challenging environments. You only need to locate one place in the country where you will have the most reliable power and good phone signal. You will need either a Wi-Fi or GSM data connection, but if you can get both, even better. The phone will be smart about which network to use if one connection isn't working well. Note that you can use the Alarm Events webhook to keep track of the status of your phone and make sure it's connected to the network, charged and able to send text messages. In order to hep you manage it's state, RapidPro will send you events when an alarm condition occurs with your phone. 

Installing the Android Application


To review, you'll need:
1. Open the Google Play store on your Android phone, search "Nyaruka RapidPro," then tap the application icon to open the download page. 



2. Tap the "Install" button to begin the download process.  



3. Tap the "Accept" button to accept the terms and initiate the download.



4. Once the download is complete, tap the "open" button to open the application.  



5. Take note of your claim code; it will link your Android phone to your RapidPro account. 



6. Sign-in to the RapidPro website to add the phone to your account.


 


7. Either click the "channels" tab or navigate to your account page, click the "gear" icon, then select the "Add Channel" option.





8. Click the "Android Phone" option. 



9. Enter the claim code found in your Android application, then enter the phone number attached to the SIM card present in your Android phone. 



Navigating the Application


You can increase your hourly sending capacity by installing our message packs. One pack is equal to a 30 message increase, and there are 10 packs to download. If you want to send more than 330 messages per hour, you can enable bulk sending through Nexmo



While the Android application is active and communicating with the RapidPro website, all incoming and outgoing messages will be recorded. To stop recording messages, you may tap the "RapidPro Active" panel to pause the application. You will receive an email notification if the application is paused.

Android phones have redundant network connections and a backup battery. So, if the office where it is located loses power or the network goes down, the RapidPro app will continue to relay messages. In most cases, using an Android phone with RapidPro means you can just "set it and forget it." We'll automatically notify you if the phone is running low on battery, out of credit, or doesn't have network connectivity so someone can check up on it.

 

Configuring your Settings


Tap the icon in the top right corner of the application to navigate to the "Network Settings" screen, where you can toggle your settings or reset the application to remove it from your account. 


Make sure to enable Airplane Reset mode to ensure your phone stays connected to WiFi even during long periods of inactivity:


Activity Log


Tap the bottom panel to view your activity log, including phone registration and message history. 


Android Application F. A. Q. 


What if I need to send a lot of messages?

We encourage people to validate their ideas and experiment before focusing on scaling. Starting with Android phones is a logical starting point for most projects and you'll have no problem sending up to around 1,000 messages per hour. If you do outgrow that, we can help you connect your RapidPro account with a local aggregator or even a direct connection with the carriers themselves.

What happens if the battery dies?

Android phones are great because they have redundant network connections and a backup battery. So, if the office where it is located loses power or the network goes down, the RapidPro app will continue to relay messages. In most cases, using an Android phone with RapidPro means you can just set it and forget it. We'll notify you automatically if the phone is running low on battery, out of credit, or if it doesn't have network connectivity so someone can check up on it.

Can I use a short code? What about reverse billing?

While these features are generally viewed as unique to SMPP accounts, in some countries the carriers will allow short codes to point to sim accounts. This means texting or calling that short code would route to your Android phone. In some cases these sim-based accounts can also be reverse-billed.

Does the fee I pay to RapidPro include messaging fees?

No, the fee covers the use of the RapidPro platform. Any messaging rates imposed by your carrier apply.

Will RapidPro work for my remote ICT4D project?

We understand that deploying SMS applications has traditionally been one of the trickiest parts when launching ICT4D projects. In fact, it's the primary thing that drove us to create RapidPro in the first place. We try hard to make it as easy as possible but we realize that you probably have questions on what this all means for your specific project. Please contact us with any questions and we'll help you work through your options.




2.5 Using a Bulk Sender

If you want to send more than the 330 messages/hour allotted by the Nyaruka RapidPro Android application, you can enable a bulk sender like Nexmo to send messages on your Android channel's behalf. Nexmo will enable you to send bulk messages in over 200 countries while providing an intelligent routing scheme to guarantee message delivery*.

*Check Nexmo's Country-Specific Features and Restrictions for your country before proceeding.  

This configuration allows your Android phone to receive incoming text messages through it's SIM card while Nexmo sends outbound messages using a sender ID that matches the phone number associated with the SIM. 

To enable bulk sending:

1. Sign up for an account with Nexmo. Make sure you enter the phone number associated with the SIM card of the Android phone you're using as a channel through our Android application. 



Note: 
Make sure you're phone's on; you'll need to complete 2-factor verification to get to the Nexmo dashboard.



2. Locate your "Key" and "Secret" on the dashboard. 



3. Within the account page of your RapidPro account, click "Enable Bulk Sending" next to your the number of your Android relayer. 



4. Click the Nexmo option, then enter your Nexmo "Key" and "Secret." 





5. Top-up your Nexmo account to remove it from Demo status. You can visit this page to estimate outgoing message costs. With bulk sending enabled, you won't be charged for outgoing messages by the carrier associated with your SIM card. 

6. Once enabled, you'll see a Nexmo icon beneath your Android channel. 



2.6 Adding a Twilio Number

To send and receive messages through a Twilio channel, you'll need to create a Twilio account and purchase a virtual number and connect it to your RapidPro account. We recommend purchasing a toll-free number ($2/month) if you're deploying in the US or Canada. Trial virtual numbers provided by Twilio are not sufficient for testing; if you'd like to test your flows prior to committing to a Twilio number, you can begin with an Android channel

Purchasing a Number


To purchase a toll-free virtual number through Twilio, you'll first need to sign-up for an account or sign-in to an existing Twilio account. 

Once inside the Twilio dashboard, click the PRODUCTS menu in the top left corner:



Select PHONE NUMBERS from the drop-down menu: 



Once you've reached the Manage Numbers page, click the Buy a number button in the top right corner: 



Once you've reached the Buy A Number page, click Advanced Search, select the country in which you'll be sed, and check the Toll-Free search parameter if available (if not, proceed with a standard number):


Connecting your Number to RapidPro


Once a number has been purchased, you'll need to connect your Twilio account to your RapidPro account. You can do so by adding a channel, then selecting the Twilio option. Next, you'll be prompted to enter your Twilio account SID and Token. 



These can be found on the bottom of your Twilio ACCOUNT SETTINGS page: 



Scroll down to the API Credentials section: 



After you've entered your Twilio account credentials, you'll be directed to a page that contains the Twilio numbers you've purchased. Choose the number you'd like to connect, and you'll immediately be ready to send and receive messages :)






2.7 Adding a Twilio Messaging Service

Twilio recently optimized its platform to accommodate programmatic SMS messaging at scale. This upgrade allows for the creation of a messaging service, which enables you to dedicate multiple local Twilio numbers to a single RapidPro channel, and improve SMS delivery with phone number intelligence via the new Copilot features available in your Account Portal.  

Phone Number Intelligence

Twilio Copilot's phone number intelligence allows you to rely on Twilio backend logic to select the best phone number for every message. Whether it's using multiple numbers to send high volume messages or the same local recognizable number for each person to increase response rate, the aim is to remove the burden of carrier routing and regulations from the user through four dynamic features:

Channel Relationships

Twilio's Geo-Match and Sticky-Sender features ensure that the relationships between your phone numbers and contacts remain constant from your first broadcast.

When multiple channels of the same type are connected to your RapidPro account, the channel that the contact last messaged will be prioritized. Contacts can be locked-in to a relationship with a specific channel (they'll only received messages from this channel). Geo-Match and Sticky-Sender ensure that even if your contact sends a message to the wrong channel, they'll always receive a response from the same number.

Content Intelligence

Messages with special characters or attachments can be lost in transmission due to ever-changing carrier specs. Copilot allows you to automatically format every message to ensure your content stays in tact. These are the features that allow you to do so:

Adding a Twilio Messaging Service

Follow these instructions to setup your own messaging service and add it to your account:

1. Login to your Twilio account's Programmable SMS tab and click "Messaging Service":

2. Create a new messaging service:

3. Give it a name:  

4. In a separate tab, login to your RapidPro account, navigate to the Add Channel page, and select "Twilio Messaging Service" option:

5. Copy your Messaging Service SID from your Twilio portal:

6. On the "Add Twilio Messaging Service" page, select your country and paste your Messaging Service SID in the appropriate box:

7. On the next page, copy the the request URL that RapidPro provides you:

8. In your Twilio portal, paste the request URL underneath the "Inbound Settings" header:

9. Scroll down to the "Copilot Features" header and select the features you'd like to enable for your messaging service:

10. Scroll back to the top of the page, click the "Numbers" tab, and either add existing numbers or purchase numbers to add to your service. Click "Save" to finish configuring your messaging service:

You're ready to start sending messages. Start a flow to test out your service. 

2.8 Managing Opt-Outs on Twilio Channels

Opt-outs are common among SMS ("Robotext") and IVR ("Robocall") services. According to the TCPA (see our guide here), your contacts should have the ability to do so at any time. Use this guide to learn how to track and manage these contacts via Twilio and your RapidPro account.

How Twilio Manages Opt-outs


When a contact sends STOP, STOPALL, UNSUBSCRIBE, CANCEL, END or QUIT to one of your Twilio numbers, Twilio will prevent them from receiving any additional messages until that contact responds START. Specifically, they'll receive the following message:

"You have successfully been unsubscribed. You will not receive any more messages from this number. Reply START to resubscribe."

When that contact resubscribes, they'll receive the following message:

"You have successfully been resubscribed to messages from this number. Reply HELP for help. Reply STOP to unsubscribe. Msg&Data Rates May Apply."

How RapidPro Manages Opt-outs

When Twilio notifies us that a contact has blacklisted one of your Twilio numbers, we place that contact in the default 'Stopped' group in your account's Contacts tab. The contact is removed from all other groups and specially marked so that any outbound message attempts are blocked.

(Use this guide to have Twilio notify you of errors–like the 21610 blacklist error mentioned in this article–via email.)

For more information on proper SMS or IVR-based communication, consult our TCPA compliance guide

2.9 Integrating Using the External Channel API

Although RapidPro provides integrations with dozens of various aggregators such as Twilio, Nexmo and others, you may need to integrate with other systems. Our External Channel API makes this quick and easy.

Here are the steps:

1. Go to your account page by clicking your account name in the upper right then click the drop down and select "Create Channel".

2. On the next page, select "External API".

3. Here you can configure how you want RapidPro to send you new messages that need to be sent. RapidPro can send messages using a standard GET, POST or JSON body, and you can configure the parameters as you wish. Select the type of URN you will be using (likely Phone Number) and fill out the other information detailing how you want RapidPro to receive incoming messages.

4. Once you submit this form, RapidPro will provide a URL for you to send incoming messages. RapidPro expects messages to be delivered using a POST to the URL provided with the following parameters:
text: The text of the message, utf-8 encoded
from: The number which sent the message, this should be fully qualified with country code, ex: +12065551212
date (optional): The ISO 8601 date when the message was sent, this field is optional.

RapidPro will respond with a 200 status code if the message is accepted, otherwise 400 if there is an error in your submission with more details as to why.

5. That's it! RapidPro will respond to incoming and outgoing messages for your channels as it would for any other. If you experience problems sending outgoing channels with your external channel you can check the sending log from your channel's page to get a detailed log of those requests.

Messages 3

3.1 Introduction to Messages

Much like an email client, RapidPro lets you view, label and archive messages as you receive them. RapidPro also keeps track of calls that are received on your channel so you can return any calls which may have been made to it.

Messages represent the incoming and outgoing interactions your RapidPro account has had with:
Unless submitted by the RapidPro Surveyor App, all messages are sent to and from the channel(s) connected to your RapidPro account are stored in the messages tab, where they're organized into folders in the messages column on the left side of the page. 

Inbox


Messages stored in the "Inbox" folder include all incoming messages that haven't triggered or been received by a flow. Messages in this folder are sent by contacts that aren't active in a flow. 

Flows


Messages stored in the "Flows" folder include messages received by your flows. Messages in this folder are sent by contacts who are active in flows at the time the messages are sent. 

Archived


Archiving removes messages from your inbox, but keeps them in your account so you can find them later. Messages from your "Inbox" or "Flows" folders can be stored in the "Archived" folder. Messages must be placed in "Archived" folder before they can be deleted, and can be returned to their original folder at any time. 

Outbox


The "Outbox" folder contains pending messages that may build up when sending a large broadcast. Once a message is sent, it moves from the "Outbox" folder to the "Sent" folder. 

Calls


The "Calls" folder contains calls made to and from the channel connected to your RapidPro account. You are provided the date, direction, and duration of each call. 


Scheduled


The "Scheduled" folder contains messages that have been scheduled to be sent in the future or on a recurring schedule. Navigate to this folder to view or edit scheduled messages. 

Failed


The "Failed" folder contains messages that weren't able to send when broadcasted. 

Message Statuses


Each message is assigned a status represented by one of the following icons: 

The "delivered" icon denotes a delivered message, and is followed by the text of the message.




The "sent" icon denotes a message that has been sent but hasn't returned a delivery receipt. Some carriers and channels aren't able to provide delivery receipts. These messages should be considered delivered unless they're present within the "Outbox" folder in the messages tab.​



The contact icon denotes a message received from a contact, and is followed by the text of that message.

The broadcast icon denotes a message broadcast, and is followed by the number of contacts targeted by the message as well as its contents.



The caution icon denotes a message that has failed to send, and is followed by the text of the message.

Note that hovering over each of these icons will reveal the channel through which it has been sent or received. 

3.2 Archiving Messages

Much like email, RapidPro allows you to archive incoming messages, while outgoing messages are kept to verify the origin of messages sent via the channels connected to your RapidPro account. 

To archive incoming messages: 

1. Click the "messages" tab.

2. Select the boxes to the left of the messages you'd like to archive. 

3. Click the "archive" icon.

Archived messages will appear in the "Archived" folder to the left of the message list. 


3.3 Exporting Messages

Messages can be exported to a spreadsheet document for review outside RapidPro.

To export incoming and outgoing messages: 

1. Click the "messages" tab.

2. Click the "export" box above and to the right of the message list.



3. Select the group(s) of contacts whose messages you'd like to export, then choose a start and end date to establish a time frame in which the messages will have been sent or received. 



4. You'll receive an email at the address associated with your RapidPro account containing a download link protected by your username and password. The exported file will contain the date, contact number, contact type, contact name, contact UUID, direction, text and status of each message: 


3.4 Labeling Messages

RapidPro allows you to add labels to classify responses. You can also create your own labels to keep track of messages as you receive them. This makes it easier to organize your messages and sort through them when exported from RapidPro. Note that you may also label messages within a workflow

To label your messages: 

1. Click the "Messages" tab.

2. Check the boxes to the left of the messages you'd like to label. 

3. Click the "Add Label" icon that appears once messages are selected.



4. You may either create a new Label or choose from a previously created Label. 



5. Give your Label a name. 



6. Once created, the Label will appear to the right of your message inbox.




3.5 Deleting Messages

Messages must first be archived in order to be deleted. Only incoming messages may be deleted; outgoing messages are kept to verify the origin of all messages sent via RapidPro.  

1. Click the "messages" tab.

2. Check the boxes next to the messages you would like to delete. 

3. Once selected, click the "Archive" icon that appears above your message inbox.

4. Click the "Archived" folder to the left of the messages. Check the boxes of the messages you'd like to delete. Once checked, click on the "trash can" icon that appears above the message list. 



3.6 Schedule a Message to be Sent Later

RapidPro allows you to schedule messages to be sent at a later date and time, and repeat them daily, weekly or monthly.

To schedule a message: 

1. Navigate to the "messages" tab and click "Send Message."

2. Enter the text you want to send, select your desired recipients, and then click the "Schedule" box.  

3. Select the date and time you'd like your message sent. 

4. Select your desired level of repetition. Options include never, daily, weekly and monthly. 


Contacts 4

4.1 Introduction to Contacts

A contact is an end-user that has or will interact with your RapidPro account. Communication with contacts occurs via a channel. A contact can be:

From the contacts tab, you can:

Contact Fields


Each contact is assigned attributes, called contact fields, that hold values such as their names, phone numbers, and any other individual information you want to include. Contact fields are divided into two types, default fields and custom fields, and they can hold three types of values: textnumeric, or date & time

Default Fields


Default fields include the contact's name, addresses, and groups:


Custom Fields


Custom fields are created by you. Click here to learn how. 

Contact Addresses

Each contact has an address, or URN, to which messages from your RapidPro account are sent. Contact addresses are a type of default field, just like Name and Groups. Addresses represent the ways in which you can connect with your contacts. The most common address type is a Phone Number, though a contact can also have a Twitter Handle, Telegram Identifier, Email Address, and any External Identifier you wish to add. Each contact can be assigned multiple addresses of the same type - meaning you can now assign multiple phone numbers to a single contact. A contact's addresses can be prioritized, in which case they'll appear on a contact's profile page in the order in which they're prioritized:

Additionally, only a contact's prioritized address will appear in the contacts tab view:


Channel Types & Contact Address Types




The table above maps each channel type to its corresponding contact address type. Each contact may have multiple addresses of the same type (e.g. multiple phone numbers). A contact's address type priority will dictate which channel type will send messages to the contact. If you have multiple channels of the same type connected to your account, the channel that the contact last initiated contact with will be prioritized. Contacts can be locked-in to a relationship with a specific channel (they'll only received messages from this channel) under three conditions:
  1. You have multiple channels of the same type connected to your account.
  2. The contact's address type priority corresponds with the channel type (e.g. phone number) that possess multiple channels (e.g. multiple phone numbers).
  3. The contact initiates contact through an incoming message.

Contact Variables


@contact variables represent contact field values specific to each individual contact present in a flow.

@contact - The full name of the contact if one is set, otherwise their number, e.g. "Ben Haggerty"
@contact.name - Also the full name of the contact if one is set, otherwise their number, e.g. "Ben Haggerty"
@contact.first_name - The first name of the contact if one is set, otherwise their number, e.g. "Ben"
@contact.tel - The phone number of the contact in human readable format, e.g. "(206) 555 1212"
@contact.tel_e164 - The phone number of the contact in E164 format, e.g. "+12065551212"
@contact.groups - The groups in which the contact has been placed. 
@contact.uuid - The universally unique identifier assigned to each contact. 
@contact.[contact-field] - any contact fields you've created for your contacts, e.g. "@contact.age"

Referencing a Contact within a Flow


There are two ways to reference contacts and their fields within a workflow:

@contact - references the contact receiving the message. In most cases, this is the active contact - the person whose responses are being handled by the workflow. When using the Send a Message to Someone Else action, @contact refers to the contact or group of contacts to which the message is being sent.

@step.contact - references the contact who sent the last message handled by the workflow. In most cases, this is also the active contact. When using the Send an SMS Response action, @step.contact and @contact are the same contact. When using the Send a Message to Someone Else action, @step.contact refers to the contact who has reached the Send a Message to Someone Else action within the flow, thus triggering it to send.

Here's an example:



Since the message created by the Send a Message to Someone Else action is being sent to Edward, @contact.first_name will be replaced with Edward's first name. @step.contact.name and @step.contact.tel will be replaced with the name and phone number of the patient that just registered via the workflow containing the Send a Message to Someone Else action.

For more information about variables, visit the Flow Variable Reference.







4.2 Creating a Contact

To create a contact:

1. Navigate to the "contacts" tab. 

2. Click the "Create a Contact" box in the bottom left corner of the page. 

3. Enter the name and phone number* of the contact. You may also enter the contact's Twitter handle if you're using a Twitter account as a channel. 

*All phone numbers added to RapidPro must contain a country code, thus adhering to the E164 format.

4. Your new contact will appear at the top of the "contacts" tab. 


4.3 Adding, Editing & Prioritizing Contact Addresses

Contact addresses are a type of default contact field, just like Name and Groups. Contact addresses can be added, edited and prioritized from the Update Contact dialogue, accessed through the "Edit" option in each contact profile's settings drop-down menu: 

The Update Contact menu, accessed via the 'Edit' option above, provides an input for you to add connections of all types. One connection can be added at a time; multiple connections will need to be added one at a time.

The upward-pointing arrows to the right of the address fields are what you'll use to prioritize your contact's addresses. RapidPro recognizes the topmost address as the priority, which is an important indicator for outbound messages. Let's assume your account has Phone Number, Twitter and Telegram channels connected and you send a message to 3 contacts, each with a different address priority. The channel that corresponds with each contact's address priority will send them the message. That is to say, you'd have 3 channels processing 1 send message request; your Twitter channel will send to those with a Twitter address priority, your Telegram channel will send to those with a Telegram address priority, and so on. Otherwise, channel priority behavior remains the same: A contact's address type priority will dictate which channel type will send messages to the contact.

If you have multiple channels of the same type connected to your account, the channel that the contact last initiated contact with will be prioritized. Contacts will be locked-in to a relationship with a specific channel (they'll only received messages from this channel) if each of the following conditions is met: 
  1. You have multiple channels of the same type connected to your account.
  2. The contact's address type priority corresponds with the channel type (e.g. phone number) that possesses multiple channels (e.g. multiple phone numbers).
  3. The contact initiates contact through an incoming message.

Using a Contact Import

Contacts can be imported with multiple address types, but only one address for each type.

You can update a contact's field values by including the contact field and its value in your import. Contact addresses, a type of default field value, can be added but not replaced via an import, so long as the UUID column contains the UUID(s) of the contact(s). Contact UUIDs can be obtained by exporting your contacts (UUIDs are included in each contact export) or by using the List Contacts query in the API Explorer. Simply log into your account, add the appropriate parameters to filter to your desired contacts (or leave the query blank to list all of your contacts), and click the "GET" button:

RapidPro will return all of the information associated with your contact(s), including their UUID(s).

Replacing Addresses

At this time, contact addresses may only be replaced via the Contacts API Endpoint or a contact’s profile page as outlined above.

4.4 Adding Contact Fields

Each contact can be assigned attributes, called contact fields, that hold values such as their names, phone numbers, and any other individual information you want to include. Contact fields are divided into two types, default fields and custom fields, and they can hold three types of values: text, numeric, or date & time. When a contact field is created, the default value is null unless the field is imported from a spreadsheet with a pre-existing value or updated when a contact reaches an Update the Contact action in a workflow.

Default Fields


Default fields include the contact's name, addresses, and groups:


Custom Fields


Custom fields are created by you. Click here to learn how. 

Adding Fields


Contact fields can be added within the contacts tab using the method described below, or by interacting with a flow using the
Update the contact action.  

To add a contact field:

1. Navigate to the contacts tab and click the "Manage Fields" button:

2. Type the name the contact field you want to add in an empty box.

3. Select the type of value this field will hold (Text, Numeric, or Date & Time).  

Once you've added a contact field, you can refer to its value using the variable @contact.[field_name]. For example, the "Email" contact field in the tutorial below can be referenced using @contact.email. Click here to learn more about using variables


Updating Field Values


To change the value of a recently-created contact field, you can update it using the Update the contact action or by editing a contact field value via the contacts tab. For example, when a new phone number sends a message to a channel connected to your account, a new contact will be created with a null Name value and null values for each contact field you've added. The new contact will only be identifiable by their phone number until their other field values are updated. 

4.5 Deleting Contact Fields

If you no longer need a contact field, you can remove it by simply clearing its name in the Manage Fields dialogue. Note that this will remove all values associated with that field.

To remove a contact field:

1. Navigate to the "contacts" tab.

2. Click the "Manage Fields" button.

3. Find the contact field you want to remove and clear its name.

4. Click the "Ok" box to validate deletion.


4.6 Editing Contact Field Values

Editing Default Fields


Default fields can be added and edited manually via the Update Contact dialogue located within each contact's profile page. Default fields include a contact's name, groups and addresses. To access the Update Contact dialogue, navigate to a contact's profile page and select the "Edit" option from the settings menu:  

The Add Connection drop-down menu provides an input for you to add connections of all types. One connection can be added at a time; multiple connections will need to be added one at a time.

The upward-pointing arrows to the right of the address fields are what you'll use to prioritize your contact's addresses. RapidPro recognizes the topmost address as the priority, which is an important indicator for outbound messages. Let's assume your account has Phone Number, Twitter and Telegram channels connected and you send a message to 3 contacts, each with a different address priority. The channel that corresponds with each contact's address priority will send them the message. 




You can change the value of a contact field via the contacts tab, or by adding the Update the contact action to a workflow. When a new address sends a message to a channel connected to your account, a new contact will be created with an empty name value and empty values for each custom contact field you've added. The new contact will only be identifiable by their address until their other field values are updated.

Editing Custom Fields

Custom fields, while created via the "Manage Fields" button on the contacts tab, can be edited via the Custom Fields dialogue also located within each contact's profile page. To access the Custom  dialogue, navigate to a contact's profile page and select the "Edit" option from the settings menu:  


The custom fields you've added to your account will be listed in the dialogue, where each contact's individual values will appear. To edit these values, simply replace them and click "Ok":

Editing Date Values


Note that hen manually adding a date value without a time specification to a contact field, RapidPro will replace the corresponding time value with the time at which you updated the field. 

Using a Flow


Contact fields can also be created and edited via a workflow containing an Update the Contact action.

Using a Contact Import

Contacts can be imported with multiple address types, but only one address for each type. 

You can update a contact's field values by including the contact field and its value in your import. Contact addresses, a type of default field value, can be added but not replaced via an import, so long as the UUID column contains the UUID(s) of the contact(s). Contact UUIDs can be obtained by exporting your contacts or using the List Contacts query in the API Explorer. Simply log into your account, add the appropriate parameters to filter to your desired contacts (or leave the query blank to list all of your contacts), and click the "GET" button: 

RapidPro will return all of the information associated with your contact(s), including their UUID(s). 

Replacing Addresses

At this time, contact addresses may only be replaced via the Contacts API Endpoint or a contact’s profile page as outlined above.


4.7 Searching for Contacts

In addition to searching for contacts by name or phone number, you can place queries in the search bar on your contacts tab to search for contacts based on the values in their contact fields. 

Queries

The query you enter will operate on all contact fields present in your account. Note that fields and values are not case sensitive within a query.

Operators


In the query pictured above, we're referencing a contact field called 'Age' and using the operators "greater than or equal to" '>=' and "less than or equal to" '<=' to specify the desired characteristics of the contacts you're searching for. Note that with contact fields containing two or more words, spaces need to be replaced with underscores, e.g. id_number=409328

Statements


You can use 'OR' statements to match two or more contact field values, and 'AND' statements to filter contacts by contact field. For example,

(city="Oakland" or city="Berkeley")

will return only those contacts whose 'City' field contains "Oakland" or "Berkeley", and

(city="Oakland" and gender="Male")

will return only those contacts whose 'City' field contains "Oakland" and whose "Gender" field contains "Male".

Field Types


Text values containing multiple words must be enclosed in quotation marks, e.g. city = "san francisco", while operators like '>=' only work with Numeric and Date & Time values.


Dynamic Groups


Groups resulting from queries are called dynamic groups. Dynamic groups are unique in that they will continue to collect contacts who match the query that created them.

Creating a Dynamic Group


Once you enter a query, RapidPro will return the group of contacts who match it:

You can save this new group by clicking the "Save as Group" button underneath the search bar:



Once a Dynamic Group is saved, any new contacts that match the query will be automatically placed in it.

4.8 Setting the Language for a Contact

RapidPro allows you to set each of your contacts' language preferences. Once set, these will be the languages in which your contacts receive messages.

Contacts Tab


To set a contact's language preference via the "contacts" tab:  

1. Navigate to the "contacts" tab, then click the contact whose language you want to update

2. Click on the gear icon and select the "edit" option.

3. The Upate Contact dialogue will appear. Click the "Language" menu to select a language from the primary and secondary languages you've added to your account, then click "Ok."



Please note: 
  1. The default Language contact field, representing preferred language, is visible through the following pathway: navigate to contacts tab > click contact > click gear icon menu > select edit. A contacts' language preference can be referenced using the @contact.language variable, returning its ISO 639-2/B standardized nomenclature (Spanish becomes 'spa'). 
  2. You’ll need to translate your flows into each of the secondary languages you’ve added to your account page.

Using a Flow


You can achieve the same result at scale by creating a flow that contains the Set language action, then adding the contacts or groups whose language preferences you want to modify.

Using a Contact Import


You can add a column titled 'Language' containing the ISO 639-2/B language code (e.g. 'spa' for Spanish) to a contact import to set your contact's preferred languages. Note that all additional languages must first be added to your account via your account page

4.9 Blocking Contacts

In rare instances, contacts may abuse your service or send offensive messages. You can block these contacts by navigating  to the "contacts" tab, highlighting the contact, and clicking the "Block" icon. All incoming messages from blocked contacts will be archived.



You may unblock a contact at any time by clicking on the "Blocked" sub-category underneath the "Contacts" header, clicking the box to the left of their name, and clicking the "Unblock" button. 




4.10 Importing & Exporting Contacts

Importing Contacts


Importing contacts allows you to add entire groups of contacts to RapidPro using a simple XLS (MS Excel) spreadsheet. 



Your contacts will be placed into a new contact group that matches the name of the imported spreadsheet file. Note that you must have a channel connected to your account to import contacts. To import contacts, simply import an XLS spreadsheet containing:
*Note that when importing a date value into RapidPro without a time value, RapidPro will assign the date a time value of 00:00 (12 AM):



Additionally, when manually adding only a date value to a contact field, RapidPro will replace the corresponding time value with the time at which you updated the field. 



To import contacts:

1. Navigate to the contacts tab. 

2. Click the "Import Contacts" button.



3. Download and edit the template we provide (or choose a your own file) and upload it using the "Choose File" button. 

4. Confirm any custom fields present in your import spreadsheet and choose each field's value type: TextNumericor Date & Time. Make sure to check the boxe(s) corresponding to the fields you wish to import: 


Importing Address Types

Contacts can be imported with multiple address types, but only one address for each type:

Contact addresses can be added via an import, so long as the UUID column contains the UUID(s) of the contact(s). Contact UUIDs can be obtained by exporting your contacts or using List Contacts request in the API Explorer:

Exporting Contacts

Contact exports will contain your contacts' UUIDsNamesAddresses, and Custom Contact Fields. To export your contacts, simply navigate to the contact tab and select the "Export" option from the gear icon drop-down menu: 


4.11 Contact Information Anonymization

We understand that some use cases require contact information to be handled sensitively. This in mind, we added an anonymization feature that'll replace each contact's name with a random code and completely remove their address (their phone number, or an ID associated with their Facebook, Telegram or Twitter accounts):


Note that 'None' is the default value displayed for empty custom contact fields. 

When the anonymization feature is enabled, each new contact profile, whether imported into RapidPro via a spreadsheet or generated when a new contact interacts with one of your channels, is anonymized. No user will be The contact's UUID, groups, language preference and custom fields will still be accessible. By the same token, exported contact and flow information will also be anonymized. 

This feature is permanent once an account has been anonymized, and only affects the account in which it's enabled. Parent and child accounts aren't affected. 

If this isn't sufficient, we're interested to learn how we might improve this feature to accommodate a broader range of use cases. 

Contact us to enable this feature. 

Groups 5

5.1 Introduction to Contact Groups

Contact groups allow you to segment your contacts into clusters based on their attributes or responses. Contacts can be placed in multiple groups, and you can create as many as you need.

Within a flow, contacts can be moved to and from groups using the Add a contact to a group and Remove contact from a group actions explained in further detail here. A contact's groups can be referenced using the @contact.groups variable. 

5.2 Creating a Contact Group

To create a group: 

1. Navigate to the "contacts" tab and click the "Create Group" box in the bottom left corner of the page.

2. Give your group a name and click the "Create" box. Your new group will appear in the group directory on the left side of the page.




5.3 Adding Contacts to a Group

Contacts Tab

To add a contact to a group via the contacts tab:  

1. Navigate to the "contacts" tab, check the box to the left of the contact whom you'd like to place in a group, then click the group icon that appears above your contacts to select a group or create a new one: 



To remove a contact from a group via the contacts tab, click the group from you which you want to remove your contact, check the box to the let of the contact whom you'd like to remove, then click the "remove from group" icon that appears above your contacts:


Using a Flow


You can attach an Add contact to a group or Remove contact from a group action to a split step to move multiple contacts between groups instantly.

In the example below, we're using a Split by Contact Field action to direct contacts who reside in Nigeria's northern states to an Add to Groups action that places them in the "Northern States" group. 



We achieve this my splitting our contacts on the State contact field. The has any of these words response rule allows us to create a rule that places any contacts whose State field contains any of the words "Adamawa", "Bauchi", "Benue", etc. in the "Northern States" category, which leads to the Add to Groups action above. 



5.4 Dynamic Contact Groups

Groups resulting from contact searches are called dynamic groups. Dynamic groups are unique in that they will continue to collect contacts who match the query that created them.

Creating a Dynamic Group


Once you enter a query, RapidPro will return the group of contacts who match it:

You can save this new group by clicking the "Save as Group" button underneath the search bar:



Once a Dynamic Group is saved, any new contacts that match the query will be automatically placed in it.

Queries


The query you enter will operate on all contact fields present in your account. Note that fields and values are not case sensitive within a query.

Operators


In the query pictured above, we're referencing a contact field called 'Age' and using the operators "greater than or equal to" '>=' and "less than or equal to" '<=' to specify the desired characteristics of the contacts you're searching for. Note that with contact fields containing two or more words, spaces need to be replaced with underscores, e.g.id_number=409328

Statements


You can use 'OR' statements to match two or more contact field values, and 'AND' statements to filter contacts by contact field.

For example,

(city="Oakland" or city="Berkeley")

will return only those contacts whose 'City' field contains "Oakland" or "Berkeley", and

(city="Oakland" and gender="Male")

will return only those contacts whose 'City' field contains "Oakland" and whose "Gender" field contains "Male".

(tel has 123)

will return only those contacts whose phone number contains '123'. 

(name has "Be")

will return only those contacts whose 'Name' field contains 'Be'. 

Field Types


Text values containing multiple words must be enclosed in quotation marks, e.g. city = "san francisco", while operators like '>=' only work with Numeric and Date & Time values.



5.5 Deleting Contact Groups

Contact groups can be deleted by navigating to the group page and selecting the "Delete Group" option from the gear icon drop-down menu. 


Flows 6

6.1 Introduction to Flows



A flow is a visual representation of conditional branch logic that's applied to your contacts once they enter it. Once a contact has entered a flow, they interact directly with its steps. Steps are composed of ActionSets and RuleSets, and determine the length of a flow, which can be as short as a single step or as long as you want. 

ActionSets




An ActionSet represents some action taken on behalf of your flow. Essentially, they're commands that allow you to: 
ActionSets comprise actions that are executed immediately in order from top to bottom: 


RuleSets

RuleSets are the pivot points in a flow, "splitting" it into new branches. They're conditional statements that enable you to direct your contacts after evaluating:

Anatomy of a RuleSet




RuleSets comprise 5 inputs that allow you to construct a powerful conditional statement:

A - The type of RuleSet you'd like to create:  



  • Wait for response waits for an incoming message, then evaluates it against response rules. Optionally, you may choose to add a timer to Wait for response RuleSets to send a reminder message to a flow participant after a period of inactivity, or create a 'pause' in a flow to stagger messages.
  • Call WebHook calls a URL, passing it the flow context and, if the external service responds in JSON, makes the response available for reference using the variable @extra. Flow context comprises the variables available in a given flow, including the active contact's responses and contact information. This RuleSet contains two categories, Successful and Failed, to account for errors returned by the external service.
  • Call Zapier allows you to add a flow event at any step in a flow that corresponds with a Zapier Flow Event trigger. Once a contact reaches a flow event, all of their responses up to that step will be sent to Zapier, which can be configured to send that data to one of over 500 other apps without writing a single line of code. Use this guide to get started with Zapier.
         
  • Transfer Airtime enables you to transfer airtime to prepaid phones on over 400 networks across 100 countries. When a contact reaches a Transfer Airtime step, they'll received the amount you specify. Use this guide to get started with airtime transfer.
         
  • Run a flow enables you to start the active contact in a 'child' flow at any step, then return them to the original 'parent' flow. Two new conditions are introduced, Completed and Expired, giving you the ability to branch the active contact based on their activity in the child flow. Variables captured in the calling, or parent flow can be referenced using the @parent.[field] format, while variables captured in the child flow can be referenced using the @child.[field] format. More on flow variables here.
         
  • Split by contact field runs response rules against a value stored in a contact field (Name, Phone, etc.), referenced using the variable @contact.[variable-name], e.g. @contact.state.
  • Split by flow field runs response rules against a value collected by a previous RuleSet, referenced using the variable @flow.[variable-name], e.g. @flow.city.
  • Split by expression runs response rules against the result of an expression, such as @(REMOVE_FIRST_WORD(step.value)), which includes a function that removes the first word from the message last received, represented by the @step.value variable. Expressions can include a single variable, a single function, or a combination of variables and functions.
  • Split by message form runs response rules against a value separated by a delimiter (a space, plus sign, or period), e.g. 1+2+3+4+5 (+ is the delimiter, while 1 is the first value, 2 is the second value, 3 is the third value, etc.). See this guide for more information.
  • Split randomly enables you to create as many evenly-distributed buckets as you'd like for the purpose of randomly branching a contact for an A/B test or the like. See this guide for more information on A/B testing with RapidPro.         
          
  • Split by group membership enables you check if a contact is a member of a particular group. Simply select the 'Split by group membership' option from the RuleSet menu and add the groups you'd like to check for membership. Each will become its own category. 


B - Depending on the selected RuleSet type, this is the value that response rules are evaluated against. This value, called an operand, represents a variable or expression. In the RuleSet pictured above, "if the message response.." indicates the operand is @step.value, or the incoming message.

C - The response rules that evaluate the selected operand. Response rules are executed from left to right. The first rule that matches takes effect and no other rules are evaluated after there is a match.



D - The option to set an amount of time after which a contact will be routed if they don't respond. If the contact hasn't responded in the amount of time you've chosen, they'll be routed through a 'No response' category. You can connect this category to a 'Send Message' action that encourages them to continue, or leave it unconnected to prompt an exit.  



E - The value(s) your response rules will attempt to match against the operand. In the example above, we've created a RuleSet that attempts to match the names of each of the northern states in Nigeria. With the Wait for response RuleSet type selected and the has any of these words response rule selected, incoming responses will be placed in a category called "Northern States" if they match any of the words we've listed. This allows us to place the response "I live in Adamawa" in the "Northern States" category because the word "Adamawa" matches. Note that a flow will always match at least one response rule in a RuleSet as the last response rules must always be a catch-all (placing contacts in the "Other") category.

F - The category in which contacts are placed if the the operand matches the corresponding response rule. Categories are pathways from which connections can be drawn to new steps, thus directing the contact onward. A contact's passage through a category is represented in the analytics tab as a response.



G - The name given to the flow variable created and populated by the RuleSet. In the example above, the sample RuleSet will save the result of the evaluation to the flow variable @flow.state.

Flow Membership


Flows are states that your contacts will enter and exit. Once a contact enters a flow, (s)he becomes an active member of that flow until (s)he exits. Passage through a flow from entrance to exit–and all activity that takes place in between–constitutes a run. Runs and the activity that took place therein are displayed in flow results. Flow runs can be listed and started externally via the Flow Run API endpoint

Active members are represented by the blue icon that appears on the top left corner of each RuleSet: 



You can click the icon to view the names of the contacts active at that step and, if appropriate, send them a followup message: 


Entering a Flow




Contacts can enter flows in any of the following ways:

Exiting a Flow


Contacts will exit flows when: 


Flow Membership Rules

Contacts may only interact with one flow at a time. While a contact is active in a flow, their responses are handled solely by that flow until they exit or the run expires.  



6.2 Flow Types

RapidPro provides three flow types that are made available depending on the capabilities of the channel you've connected to your account. Text Messaging workflows are applied to SMS and social media channels, as well as our Surveyor application, while voice workflows differ in structure. 

Flow type is chosen when creating a flow:  


Text Messaging


Text messaging is the default flow type, as every channel type necessarily includes text-based messaging functionality. Text messaging flows can be sent over an Android channel, a virtual number, or a social media platform like Twitter. 

Phone Call


If you have a voice-enabled channel connected to your account (e.g. a voice-enabled virtual number purchased from Twilio) you will be given the choice to create an Interactive Voice Response (IVR) flow when you enter the "Create Flowdialogue. IVR flows allow you to apply flow logic to voice-based messages sent via phone calls. Check out our IVR section for more information about IVR flows. 

Android Phone


Select this option to create a flow to run offline using our Surveyor Android application. 

6.3 Creating a Flow

To create a flow, navigate to the "flows" tab and click the "Create Flow" button:



The "Create Flow" dialogue will appear, where you can:
  1. give the flow a name
  2. assign it keyword triggers
  3. specify how long inactive contacts will remain in the flow before being removed
  4. select the type of flow you'd like to create
  5. set the language in which you'll edit it 



Once you've assigned your flow the proper attributes click the "Create" button to enter the flow editor. 

Note that when building a flow, we recommend prioritizing vertical movement over horizontal movement. The flow editor is designed to support horizontal movement to a point, but will support vertical movement indefinitely. 


6.4 Navigating the Flow Editor

The flow editor is where you'll edit your flows. Each time you create or click on a flow, you'll enter the flow editor:  


Anatomy of the Flow Editor


1. Name


The name you gave the flow when you created it. 

2. Create Message


This button brings up the step editor, which comprises two distinct dialogues, the action dialogue and the split dialogue. We generally recommend beginning a flow with a Send Message action, though you may find a RuleSet is more appropriate. 

Action Editor


The action editor begins with a Send Message action, though you can click the drop-down menu to toggle between the various action dialogues. To access the split editor, click the branch icon in the top right corner of the action editor. 

Split Editor


The split editor allows you to create pivot points in your flow in the form of conditional statements. As we explain in our introductory article, RuleSets are comprised of:
  1. A value type - "When somebody arrives at this point in your flow..."
  2. Response rules that evaluate the selected value type - "If the message response..."
  3. The specific values you're evaluating for. 
  4. The categories in which values that match a response rule are placed. 
  5. The name given to the resulting flow variable

3. Simulator


The simulator is a handy testing tool we've added to enable you to test your flows from an end-user's perspective as you build them. Once clicked, the simulator will initiate the first step of your flow. 

4. Settings Menu


The settings menu

Results


Click the results option to view the results attached to the flow you're editing. 

Edit


Click the edit option to: 
  1. change the name of the flow
  2. assign keyword triggers to the flow
  3. adjust the flow expiration window
  4. tell the flow to ignore keyword triggers once a contact has entered it


Copy


Click this option to make an identical copy of the flow you're editing. 

Export


Click this option to export the flow you're editing as a JSON file. 

Revision History


Click this option to view the revision history of the flow you're editing. Click a revision to view that version of the flow. 


Delete 


Click this option to delete the flow you're editing. 

5. Start Flow


Click this button to place contacts in the flow. You may add specific contacts or multiple groups. Checking the Restart any of the above contacts already participating in this flow box to restart contacts who are already active members of the flow. 







6.5 Assigning Keywords to a Flow

You can assign keywords to a flow to allow your contacts to start it at their discretion. A keyword is the first word in an incoming message. 

To assign a keyword to a flow: 

(1) Navigate to the "flows" tab and choose a flow. 

(2) Select "Edit" from the gear icon in the top right portion of the flow editor. 



(3) Add your keyword(s). Note that they aren't case sensitive - REGISTER, Register and register will be treated the same.  


Ignore Triggers


You can check the "Ignore triggers" box to prevent your contacts from triggering other flows while active in the flow you're editing. When this box is checked, a contact can't enter a new flow if they send a keyword assigned to a different flow. 

6.6 Starting a Flow

A flow can be started in one of a many ways: 
To start a contact or group in a flow through the flow editor:

(1) Navigate to the "flows" tab and click the flow you want to start. 

(2) Click on the "Start Flow" button in the top right portion of the flow editor.



(3) Enter the contacts or groups you want to start the flow, mark the appropriate settings, then click the "Ok" button to start them.

 







6.7 ActionSets






A flow is a visual representation of conditional branch logic that's applied to your contacts once they enter it. Once a contact has entered a flow, they interact directly with its steps. Steps are composed of ActionSets and RuleSets, and determine the length of a flow, which can be as short as a single step or as long as you want. 

ActionSets




An ActionSet represents some action(s) taken on behalf of your flow. Essentially, they're commands that allow you to: 
ActionSets comprise actions that are executed immediately in order from top to bottom: 


When you create a new flow, you'll notice that we recommend sending a message to begin. This is an example of an action. 


Creating an ActionSet


Click the "Create Message" box to open the ActionSet editor pictured below.



Or, create a connection from an existing step: 



Adding an Action to an Existing ActionSet


Actions can be attached to other ActionSets, or exist on their own as a step. Actions attached to other actions are executed immediately in order from top to bottom.



In the example below, three actions are grouped to register a new patient. When a contact passes through this step, the actions occur in the order in which they're stacked: 
  1. A message is sent to the "Doctors" group alerting them that a new patient has registered.
  2. The contact is added to the "New Patient" group.
  3. The contact is sent a message using the Send Message action that asks for her due date. 
To add an action to an existing ActionSet, click on the "+" symbol on the bottom right corner of the existing action step and select an action from the action editor. 


Changing the Order of Actions within an ActionSet


To change the order of actions within an ActionSet, move your cursor over the top left corner of the action you want to move, then click the  "^" icon. 


Deleting an Action


To delete an action, move your cursor over the action you want to delete and click on the "x" icon. The action will turn red and ask for confirmation. Click the "x" icon again to complete the deletion process.


6.8 Sending Messages with a Flow



Use the 'Send Message' action to send your contacts an automated message when they reach a particular step in a flow.

In the example below, we're creating a 'Send Message' action that asks expecting mothers who have indicated this is their first pregnancy if they want to receive additional information throughout. Actions are created each time you drag a connection from the red square at the bottom of each RuleSet.


Attach Media


Click the paperclip icon to attach media to messages sent via Twilio (US & CA only), Facebook Messenger and Telegram channels. 

Note the following:

Send to All Numbers for Each Contact




Check the 'Send to all contact addresses' setting to include each phone number for contacts who have multiple phone numbers attached to their profile. 

SMS Character Limit


If a 'Send Message' action exceeds 160 characters, it'll be split by carriers and sent as two messages. There's a character-counter beneath the dialogue box that shows how many characters remain until you've entered 160 characters. In the example below, the message contains exactly 160 characters.  



Note that it's possible to split messages that exceed more than 160 characters by adding an additional action containing any characters that remain after the 160 character limit has been reached. Also note that each SMS channel handles lengthy messages differently, so whereas a single long message might work best for Twilio channels, it may not for others. As always, we encourage you to test and see ;)

UNICODE


Note that certain content will trigger your messages to be sent as Unicode instead of standard GSM7. SMS messages by default are 160 characters, but only if they contain the standard GSM7 alphabet. If you use characters outside this (e.g., the special quotes Word inserts into text), the message gets sent as Unicode, which changes the limit to 57 characters. 



6.9 Sending a Message to Someone Else

Note: Beginning October 1, 2017, references to @contact inside the "Send a message to someone else" action will be refer to the active contact in the run, not the recipient for the message. To reference the details for the recipient, instead start that contact in a flow and use the normal Send Message action with @contact.

 Place this action at any step in a flow to send a message to someone other than the active contact that reaches that step. For example, this action can be used to:
Message Forwarding

The following is an example of a flow configured to forward a contact's response to a specific question to members of your team: 



After the contact receives the initial message ("Thanks for reaching out..."), they'll reply with their question, comment or concern (handled by the "Wait for QCC" RuleSet). Next, they'll pass through a Split by Contact Field RuleSets that will determine whether or not the contact has been assigned a name up to this point. If they haven't they'll be directed to a branch that asks for their name and updates it to their "name" field before placing them in the last step. If they have been assigned a name, they'll continue on the the last step. To reference the active contact, add the @step prefix to the contact variables you'd like to call, e.g. @step.contact.name

+ Responses to the initial question are collected by the "Wait for QCC" RuleSet, which saves all responses as the flow variable @flow.qcc.

+ By attaching a Send Message to Somebody Else action to a step that follows the Wait for QCC step, we're able to capture the responses it collects:



In the message above, we use variables to represent the following information about each contact that reaches this step:

+ @step.contact.name - represents the name of the active contact - the contact who passes through the Send a Message to Somebody Else action.

+ @flow.qcc - represents the individual contact's response to the initial question, collected by the Wait for QCC step.  

+ @flow.qcc.time - the time at which the individual contact's response was collected by the Wait for QCC step.

+ @step.contact.tel - the locally-formatted phone number of the active contact (as opposed to the E_164-formatted phone number (@step.contact.tel_e164), which would also provide the country code prefix). 

@step.contact vs. @contact


Note that there are two ways to reference contacts and their fields within a workflow:

@contact - references the contact receiving the message. In most cases, this is the active contact - the person whose responses are being handled by the workflow. When using the Send a Message to Someone Else action, @contact refers to the contact or group of contacts to which the message is being sent.

@step.contact - references the contact who sent the last message handled by the workflow. In most cases, this is also the active contact. When using the Send an SMS Response action, @step.contact and @contact are the same contact. When using the Send a Message to Someone Else action, @step.contact refers to the contact who has reached the Send a Message to Someone Else action within the flow, thus triggering it to send.

Here's an example:



Since the message created by the Send a Message to Someone Else action is being sent to Edward, @contact.first_name will be replaced with Edward's first name. @step.contact.name and @step.contact.tel will be replaced with the name and phone number of the patient that just registered via the workflow containing the Send a Message to Someone Else action.

For more information about variables, visit the Flow Variable Reference.

6.10 Adding and Updating a Contact Field

When a contact field is created, the default value is null unless the field is imported with a pre-existing value. To change the value of a recently-created contact field, you can update it using this action or by editing a contact field value via the contacts tab. For example, when a new phone number sends a message to a channel connected to your account, a new contact will be created with a null Name value and null values for every contact field you've added. The new contact will only be identifiable by their phone number until their other field values are updated. 

Use the Update the contact action to:

Using RapidPro Variables & Expressions


Contact fields can be updated with a fixed value, expressions, or RapidPro variables:

Creating a New Contact Field



To create a new contact field using the Update the contact action, simply type the name of the field you want to add in the Save to field input.



Then, input the field value you'd like to give contacts that reach this step in the flow (in the form of a fixed value, variable, or expression). In the example below, we're creating a City field and updating that value to the fixed value Oakland for contacts who reach this step in the flow:


Updating an Existing Contact Field


In the example below, we're updating the Due Date field for contacts who have indicated they're pregnant using @flow.due_date, a variable collected earlier in the flow: 



Incrementing Numeric Values


Contact fields must contain a number in order to be incremented. You can use RapidPro's expressions language to test a field for a value before incrementing it, e.g:

@(IF(contact.<field> <> "", contact.<field>, 0) +1)

6.11 Sorting Contacts into Groups

Adding Contacts to a Group


Use the Add contact to a group action to add a contacts to a group from within a flow. 



In the example below, we're placing expecting mothers who've indicated they're giving birth for the first time a group called "First Child". This allows us to identify and follow-up with new mothers, who may need extra support.


Removing Contacts from Groups


Use the Remove contact from a group action remove a contact from a group from within a flow. 



In the example below, we're removing expecting mothers who've opted-out of SMS updates from the "Expecting Mothers" group.






6.12 Setting a Contact's Preferred Channel


Default Behavior

By default, RapidPro will match contacts with channels using the following criteria: 

If you have multiple channels of the same type connected to your account, the channel that the contact last initiated contact with will be prioritized. Contacts can be locked-in to a relationship with a specific channel (they'll only received messages from this channel) under three conditions:

  • You have multiple channels of the same type connected to your account.
  • The contact's address type priority corresponds with the channel type (e.g. phone number) that possess multiple channels (e.g. multiple phone numbers).
  • The contact initiates contact through an incoming message.
  • If the contact has never interacted with a channel linked to your account, RapidPro will prioritize the channel whose number has the largest prefix overlap. 
For example, if your channels are +12505661212 and +2505551212, and you are sending an SMS to or calling +2505661231, RapidPro will use the +2505661212 Channel because it overlaps the most.

In most cases, RapidPro is able to discern the carrier associated with a contact's phone number and prioritize channels based on carrier, though this depends on carrier behavior.

Custom Behavior

Using the 'Set preferred channel' action, you can create your own channel-matching logic to either assign or switch a contact's preferred channel without waiting for an incoming message. This new action will allow you to do things like:

Considerations

RapidPro will match contacts with channels according to the above-mentioned criteria until a contact enters a flow containing a 'Set Preferred Channel' action. The contact will be permanently mapped to the selected channel until (a) they send a message to a different channel or (b) their preferred channel is changed by another 'Set Preferred Channel' action.

6.13 Setting your Contacts' Language Preferences

Using a Flow


Use the Set language for contact action to update your contacts' language preferences from within a flow. Contacts will then receive messages in their preferred languages if the flow they're interacting with has been translated. 

In the example below, we're asking our contacts which language they prefer - English, Spanish or Chinese. Once the RuleSet evaluates their responses for language preference, contacts will pass through one of three Set language for contact actions we've added for each language. They'll then receive the final message in their preferred language. 


From the Contacts Tab



To set a contact's language preference via the "contacts" tab:  

1. Navigate to the "contacts" tab, then click the contact whose language you want to update

2. Click on the gear icon and select the "edit" option.

3. The Upate Contact dialogue will appear. Click the "Language" menu to select a language from the primary and secondary languages you've added to your account, then click "Ok."



Please note:
  1. The default Language contact field, representing preferred language, is visible through the following pathway:navigate to contacts tab > click contact > click gear icon menu > select edit. A contacts' language preference can be referenced using the @contact.language variable, returning its ISO 639-2/B standardized nomenclature (Spanish becomes 'spa').
  2. You’ll need to translate your flows into each of the secondary languages you’ve added to your account page.

Using a Contact Import


You can add a column titled 'Language' containing the ISO 639-2/B language code (e.g. 'spa' for Spanish) to a contact import to set your contact's preferred languages. Note that all additional languages must first be added to your account via your account page

6.14 Adding Labels to Responses

Use the Add Label action to label incoming messages handled by your workflow. Whereas sorting contacts into groups allows you to segment contacts based on their responses, labeling incoming messages allows you to isolate responses to a specific question. Message labels can be viewed - and also created - in the messages tab: 



How it Works


Let's say you're running a therapy adherence study in which participants are asked to indicate how they're feeling each day - healthy or ill: 



Adding an Add Label action after the "Wait for Condition" RuleSet pictured above allows you to filter responses that pass through a particular category. In the example pictured above, we've placed an Add Label action in a branch that stems from the "Ill" category. Accordingly, only responses that are registered as "Ill" will be labeled. You can then view these messages by navigating to the messages tab and click the "Feeling Ill" label. 

Adding a Label


Adding a label is as simple as creating an ActionSet, or adding an ActionSet to an existing ActionSet. You may choose an existing label, or create a new one via the Add Label dialogue: 




6.15 Sending an Email

Use the Send an Email action to send an email from within a flow. The resulting email may contain values referenced using:
In the example below, we demonstrate how a clinic might use this action to send an email to staff notifying them that a mother has been registered. 



@flow.due_date references the due date collected at a previous step in the flow. The same is true for @flow.first_child.


Create an Email Pipeline

This action is also a super simple way to push a contacts’ inquiry to a team member. Simply create a flow that asks for a contact’s name, inquiry and preferred response method, and configure RapidPro to send an email containing that info off to your support feed or Slack channel. Team members will be able to instantly access the ticket via your CRM or Slack feed and respond accordingly. 


The variable @flow.name references the name of the contact if you collected it at a previous step, while @flow.inquiry and @flow.preferred_channel reference the contact’s inquiry and the way they’d like you to respond (SMS, Call, Email), respectively. Note that if a contact's "Name" field has already been given a value, you may substitute @flow.name for @contact.name or @contact.first_name

Using your Own Address


By default, RapidPro sends emails from no-reply@app.rapidpro.io. If you’d like to add your own address, simply navigate to your account’s settings page and click the email icon.


Here we’re using a Gmail-hosted email address. You’ll want to plugin your email address, host URL, credentials, port and encryption preference. In the example above, encryption needs to be set to TLS because that’s the protocol Gmail’s SMTP port 587 uses.

Gmail-Specific Considerations

If you want to link a Gmail address to RapidPro, you’ll need to switch the ‘Allow less secure apps’ setting in your Gmail account’s ‘Connected apps & sites’ page to ‘ON’:

https://myaccount.google.com/security#connectedapps

Note that a standard Gmail account is limited to 500 emails per day. Learn more about Gmail’s limits here:

https://support.google.com/mail/answer/22839?hl=en


6.16 Starting another Flow

Use the Start another flow action to move your contacts from one flow to another from within a flow. Once a contact passes through this step, they will be removed from the current flow and start another. 

In the example below, we're directing expecting mothers who are pregnant with their first child from the "Registration" flow to a different flow titled "Concerns" where we will discuss their concerns surrounding their first pregnancy and complete registration. 


Parent Variables


When a Start another flow action is placed within a flow, all flow variables created up to that step may be passed to the next flow. This flow becomes a 'parent' flow. Within the 'child' flow, flow variables collected in the parent are referenced using the @parent prefix. 

For example, if you collect a contact's Age (@flow.age) and Location (@flow.location) in FLOW A, then use the Start another flow action to place that contact in a new flow, FLOW B, you can reference those previously collected flow variables by calling @parent.age and @parent.location



Note that @parent variables are only capable of referencing values from a previous flow when a contact starts a flow through either a Start another flow or Start somebody else in a flow action.  

6.17 Starting Someone Else in a Flow

Use the Start someone else in a flow action to place a separate contact or group in a flow when a contact reaches this step.

In the example below, we're starting fathers - referenced using the contact variable @contact.spouse - in the "Questions for Dads" flow when the expecting mothers reach the second step of the "Registration" flow. 


Creating a New Contact


This action can also be used to create a new contact through the flow it starts.

In the example flow below, Register Patient, contacts are being asked to submit the names and phone numbers of the patient's they're registering. Once that information is collected, the Start Someone in a Flow action triggers a new flow, Create New Patient, that will create a contact whose default fields, Name and Phone, are populated using an Update the Contact action with the flow variables (@flow.name @flow.phonecollected in the previous flow, Register Patient.

The first flow collects the patient's information, while the second flow updates it and creates a contact profile for the patient. 

Register Patient




The name and phone number of the new contact is collected, then the new contact's phone number is started down the "Create Contact" flow. 


Create New Patient




Once the new contact's phone number starts the "Create Contact" flow, they'll be added to your contacts tab. You'll just need to update their Full Name field to complete their profile. You can do so using an Update the Contact action that places the name collected in the previous flow (referenced using the @parent.name variable; all flow variables from the previous flow can be called by placing "@parent" in front of the variable name) in the new contact's Full Name field. 


Using @new_contact


Say you'd like a single contact - an expecting mother, for example - to receive reminders pertaining to her pregnancy as well as reminders pertaining to the medical care of her other children. The key is to create separate profiles for each child, all containing the mother's phone number, so that she can receive campaign events for each of her children. 

Creating Additional Contacts


First, you'll need to start the mother in a flow that collects relevant information about each child, so that each flow run will result in the creation of a new child: 



After you've collected relevant information about the child, you'll use @new_contact to create a placeholder for that child's contact profile, and the Start Someone in a Flow action to start a flow that will update the new contact's field values: 


Updating Each New Contact's Profile


The next flow will contain a series of Update the Contact actions that will update the values collected by the previous flow (name, gender, age) to the placeholder for the child, @new_contact:

First, you'd create a contact field for the child that will contain the mother's phone number (you can create new contact fields within the Update Contact flow action). Then, you'll populate that field with the mother's phone number using the @step.contact.tel_e164 variable. @step.contact refers to the mother - the contact who sent the previous message:

Then, you'd place the @parent variable in front of each of the values collected from the previous flow: 



Once each child's contact profile is created, you can assign them their own campaign

Sending Reminders Intended for the Child


To send reminders to the mother for her child, you'll need to create a campaign event to be sent to the child's contact profile that contains a flow that uses either the Send a Message to Someone Else or Start Someone Else in a Flow actions to message the mother. The address you'll use is the contact field containing the mother's phone number, @contact.mother_phone:








6.18 RuleSets

RuleSets are the pivot points in a flow, "splitting" it into new branches. They're conditional statements that enable you to direct your contacts after evaluating:

Anatomy of a RuleSet




RuleSets comprise 5 inputs that allow you to construct a powerful conditional statement:

A - The type of RuleSet you'd like to create:  



         
         
         
          
  • Split by group membership enables you check if a contact is a member of a particular group. Simply select the 'Split by group membership' option from the RuleSet menu and add the groups you'd like to check for membership. Each will become its own category.


B - Depending on the selected RuleSet type, this is the value that response rules are evaluated against. This value, called an operand, represents a variable or expression. In the RuleSet pictured above, "if the message response.." indicates the operand is @step.value, or the incoming message.

C - The response rules that evaluate the selected operand. Response rules are executed from left to right. The first rule that matches takes effect and no other rules are evaluated after there is a match.



D - The option to set an amount of time after which a contact will be routed if they don't respond. If the contact hasn't responded in the amount of time you've chosen, they'll be routed thorugh a 'No response' category. You can connect this category to a 'Send Message' action that encourages them to continue, or leave it unconnected to prompt an exit.  



E - The value(s) your response rules will attempt to match against the operand. In the example above, we've created a RuleSet that attempts to match the names of each of the northern states in Nigeria. With the Wait for response RuleSet type selected and the has any of these words response rule selected, incoming responses will be placed in a category called "Northern States" if they match any of the words we've listed. This allows us to place the response "I live in Adamawa" in the "Northern States" category because the word "Adamawa" matches. Note that a flow will always match at least one response rule in a RuleSet as the last response rules must always be a catch-all (placing contacts in the "Other") category.

F - The category in which contacts are placed if the the operand matches the corresponding response rule. Categories are pathways from which connections can be drawn to new steps, thus directing the contact onward. A contact's passage through a category is represented in the analytics tab as a response.



G - The name given to the flow variable created and populated by the RuleSet. In the example above, the sample RuleSet will save the result of the evaluation to the flow variable @flow.state.

6.19 Response Rules

Response rules evaluate the operand designated by the RuleSet type. In the example below, we see that a Wait for Response RuleSet evaluates the incoming message, or the @step.value operand. 

Response rules provide a series of tests that you can run against the selected operand.
For example, the 'has any of these words' response rule tests the operand for any of the words you designate. Response rules are executed from top to bottom–the first rule that matches takes effect and no other rules are evaluated after there is a match. 




If the operand matches a response rule, the contact will pass through the category assigned to that rule. In the example below, the RuleSet is waiting for an incoming message, which it will evaluate against the response rules assigned to the ADULTCHILD and Other* categories. 

*Note that a
 flow will always match at least one response rule in a RuleSet as the last response rule must always be a catch-all (the "Other" rule).

Passage through categories is represented in the analytics tab as well as the flow editor. For example, the number of times a contact passed through the Yes or No categories of a RuleSet that evaluates responses to yes or no questions. 



Multiple response rules that share the same category name will be represented as one category within a RuleSet from the view of the flow editor. 

Examples


Response rules allow you to: 

Special Response Rules


Has a phone number


You can use the Has a phone number response rule to validate that the response includes something that looks like a valid phone number.  The response itself will be saved as a fully qualified number. For example, if someone responds with 0788123123 the number will be saved as +250788123123.  If a valid number isn't submitted you can follow-up asking contacts to respond again.

Matches Regex


In some cases, like validating an ID number or coupon code, you may need a more complicated rule to determine if a response is valid. Regular expressions (regex) are a standard used to describe an acceptable submission format. A great resource for testing your regular expressions is Regex101, which allows you to test any of the responses you expect against a regular expression. 

For example, say we are asking someone to enter a serial number for a device they are registering:



We know that valid serial numbers must begin with the letter "U" and be exactly nine digits, so we can match the serial numbers using:



Notes on regular expressions:


6.20 Split by Message Form

Use this RuleSet to evaluate a sequence of values separated by a space ( ), period (.) or plus sign (+).

As an example, you might record the birth of a child by soliciting messages in the following format: 

"birth [gender]+[name]+[mother's birth year]," which could yield the result "birth f+Noel+1985".

In the case above, the term "birth" acts as a keyword trigger, initiating the flow. 

To create a flow that collects and evaluates a sequence of values: 

1. Click the "gear" icon and select the "Edit" option in the drop-down menu to create the "birth" keyword trigger that will direct messages to this flow. 



2. Begin the flow by creating a Wait for Response RuleSet with an open-ended response rule to collect messages directed to this flow via the "birth" keyword trigger. Save the result as "Message."

Note: This split step must remain open-ended, as it will collect all messages that contain the keyword we've designated, "birth". Once we've stripped the initial message of its keyword, we can go about evaluating each field using a series of Split by Message Form RuleSets.



3a. Remove the keyword trigger to isolate the submission as the flow variable @flow.message (Split by Message Form RuleSets may only evaluated flow variables). To do so, create a RuleSet that splits the initial message by expression. In the example pictured below, we apply the @(REMOVE_FIRST_WORD()) function to the incoming message (referenced using @step.value). The resulting expression should read @(REMOVE_FIRST_WORD(step.value))

3b. Save the resulting flow variable as "Fields" to yield only the values delimited by a plus sign. To review, the values we'll submit will follow the format [gender]+[name]+[mother's birth year]. Each bracket value is assigned its own field. Gender is the first field, name the second and mother's birth year the third.



4. Add a Split by Message Form RuleSet to evaluate gender, the first field delimited by a plus sign. Create a response rule for each gender that categorizes the short form values "m" or "f" as their long form counterparts, and save the resulting flow variable as "Gender." 



5a. Add a Send an SMS response ActionSet that addresses incorrectly formatted "Gender" values and asks the contact to resubmit the message.



5b. In the example pictured below, we've formatted the error message to repeat the contact's initial message using the @flow.fields variable, so they can see how their response compares to the expected format, and ask them to resubmit. 



6. Add a second Split by Message Form RuleSet to evaluate name, the second field delimited by a plus. This time, it's the name of the child. You can create an "is not empty" response rule to ensure the second field has a value, then categorize it as "Has Name" and save the resulting flow variable as "Name."



7. Add a Send an SMS response ActionSet that addresses incorrectly formatted "Name" values and asks the contact to resubmit. 



8. Add a third Split by Message Form RuleSet to evaluate birth year, the third field delimited by a plus. Add a "has a number between" response rule to ensure the third field contains a valid birth year and save the resulting flow variable as "Birth Year."



9. Add a Send an SMS response ActionSet that addresses invalid "birth year" values and asks the contact to resubmit. 



10. Finish the flow by adding a Send an SMS response ActionSet that confirms the message form submission by referencing the values submitted by the contact. 



To the contact, a successful exchange will look like this: 



The resulting flow should look similar to the example pictured below.



6.21 Calling a Webhook



Webhooks simply POST flow data structured as JSON to an external service every time a contact reaches a Call Webhook RuleSet. When a user reaches a Call Webhook RuleSet, we'll call the URL you've configured, passing it all of the variables collected up to that point in the flow. See the Flow Event webhook documentation for a full list of the values included. If your service returns a JSON object, RapidPro will save its values and allow you to access them in the flow using the @extra variable prefix.

For example, the Order Status Checker sample flow in your account asks the contact for their order number, then looks it up by POSTing it to an example external service that we've configured. That service responds with a JSON object similar to the following: 

{
"status": "Shipped",
"number": "CU001",
"name": "Ben Haggerty",
"ship_date": "October 9th",
"delivery_date": "April 3rd",
"description": "Vogue White Wall x 4"
}

You're then able to reference these keys anywhere in the flow via the @extra variable prefix, e.g. @extra.status or @extra.number

Configuring a 'Call Webhook' RuleSet 


In this example, we'll show you how to add a webhook to a flow. You can follow along using the Order Status Checker sample flow located on the flows tab within your account.

Generate a Flow Field


Create a Wait for response RuleSet that collects the target value from your contacts and saves it as a flow variable. In the example below, the Wait for Response RuleSet collects our contacts' order numbers and save them as the flow variable @flow.lookup_response.


Make a Request


Create a Call Webhook RuleSet, toggle the request to "POST", and enter your URL:



If your service returns JSON, it'll be stored to the Lookup Webhook flow variable @flow.lookup_webhook. The action log within the simulator will show you the returned JSON object: 


Evaluate the External Variable


Next, create a Split by Expression RuleSet that evaluates one of the returned values against a response rule. In the example below, because the status key (@extra.status) can only contain one of three values (shipped, pending or cancelled), we can use the has all of the words response rule to discern which value is present for the contact: 



If the returned status value matches "shipped", "pending" or "cancelled", the contact will be directed accordingly. Otherwise, the contact will pass through the "other" category and receive a prompt to resubmit an @flow.lookup_response value: 


Viewing Webhook Events


To view Webhook events, navigate to your account page, click the Webhook icon, then click the "API Log" button in the bottom right corner: 



Your recent events will be listed chronologically with event type, status, channel values and attempts provided: 



You can click an event to view the contents of the request and the corresponding JSON properties: 


Troubleshooting


Unsuccessful requests are captured by the 'Failure' category. We connecting it to a Send Email action to ensure they you're alerted the moment an error occurs. 


There are lots of tools available that can help you to mimic, intercept and capture webhook requests so you can understand and fix problems, here are just a few of them:

Give it a Try


Use our webhook simulator to test your URL's performance when called by RapidPro. 

6.22 Creating a Multi-Language Flow

Once you've set your account's primary and secondary languages, you can edit your flows to toggle between multiple languages depending on your contacts' language preferences. Once you have selected the languages for your organization, you can create multi language flows by following these steps: 

1. Navigate to the flows tab and create a flow. 

2. Select the flow's primary language. This will be the language you'll see when designing your flow. If your flow is missing translations, this will be the default language used.



2. Author the flow as you normally would.




3. Once you've finished designing your flow, click the secondary language you want to add. You'll be shown the percentage of characters translated. 



4. Each "Send Message" action with turn yellow, indicating it hasn't been translated. 



5. Click each "Send Message" flow action to add a translation. 



Note: @contact.first_name, @contact.appointment, and other variables should not be translated, as they will be replaced by their corresponding values when the messages are sent. 

6. Translated steps will appear white while the language they're translated in is selected. 



7. Once your flow is fully translated, contacts will receive messages according to the language preference that appears in their contact profiles. 

6.23 Introduction to Flow Variables

By default, a flow containing RuleSets contains a collection of variables resulting from each RuleSet evaluation. For example, the RuleSet below will produce the flow variable @flow.phone when a contact responds and passes through it to the next step.  



Each variable starts with the '@' symbol, which triggers an auto-complete drop-down menu containing a complete list of available variables: 



After selecting a variable type, pressing "enter" will show a list of variables available within each variable type. In the example below, typing @flow and pressing "enter" shows us a list of flow values collected within the current flow from each RuleSet: 



Pressing "enter" again will allow you to specify the RapidPro-specific metadata associated with each value. In the example below: 



Each variable is replaced with the value if represents when a contact is active in a flow. If you insert an invalid variable, the message will instead contain the variable name.

Next Steps


Check out our Flow Variable Reference for a full list of variables.  

6.24 RapidPro Variable Reference

Contact Variables


@contact references the contact receiving the message. In most cases, this is the active contact - the person whose responses are being handled by the workflow. When using the Send a Message to Someone Else action,@contact refers to the contact or group of contacts to which the message is being sent. Each extension, e.g. @contact.name or @contact.tel, references a specific contact field. 

@contact - The full name of the contact if one is set, otherwise their number, e.g. "Ben Haggerty"
@contact.name - Also the full name of the contact if one is set, otherwise their number, e.g. "Ben Haggerty"
@contact.first_name - The first name of the contact if one is set, otherwise their number, e.g. "Ben"
@contact.tel - The phone number of the contact in human readable format, e.g. "(206) 555 1212"
@contact.tel_e164 - The phone number of the contact in E164 format, e.g. "+12065551212"
@contact.groups - The groups in which the contact has been placed. 
@contact.uuid - The universally unique identifier assigned to each contact. 
@contact.[contact-field] - any contact fields you've created for your contacts, e.g. "@contact.age"

Flow Variables


@flow variables refer to values collected at each RuleSet within a flow. @flow variables only reference values collected by the flow in which they're called. This allows you to refer to previously collected values or update contact fields with a value sent by a contact.

The name of the variable will correspond with the name of the result of the RuleSet that collects it:  



When you type @flow into a step, an auto-completion drop-down menu will appear listing the current flow variables in the flow: 


For example...


We've created a flow that allows health professionals to record the name, village and date of last missed period (LMP) from expecting mothers:



The Wait for Village RuleSet collects responses to the "Which village does @flow.name live in?" Send Message step using an open-ended response rule and saves the resulting values to a flow field titled "Village": 



Your contacts' responses can then be referenced using the @flow. prefix:


We can then use @flow.village to save a contact's village to a new contact field of the same name:  



Here's a list of extensions that give you the power to filter flow variables depending on your needs ([variable-name] is a placeholder for any result present in a flow):

@flow - All flow variables collected to this point, e.g. "Name: Jane, Age: 32"
@flow.[variable-name] - The value collected, e.g. "32"
@flow.[variable-name].category - The category a response is evaluated to, e.g. "Valid" (above ^)
@flow.[variable-name].text - The raw text evaluated within a RuleSet, e.g. "My age is 32"
@flow.[variable-name].time - The date and time when a flow value was collected, e.g. "2014-05-02 19:11:50" (dependent on your timezone and date format settings).

Step Variables


The @step variable references the contact who sent the last message handled by the workflow. In most cases, this is also the active contact. When using the Send an SMS Response action, @step.contact and @contact are the same contact. When using the Send a Message to Someone Else action, @step.contact refers to the contact who has reached the Send a Message to Someone Else action within the flow, thus triggering it to send. 

@step - The value of the step, usually the content of the last message, e.g. "help"
@step.value - Also the value of the step, usually the content of the last message, e.g. "help"
@step.date - The date and time when the last message was received, e.g. "11-12-2015 13:24"
@step.contact - The contact (and all associated variables) active in the flow. 
@step.contact.[contact-field] - The value of a contact field associated with the contact active in the flow. 

Channel Variables


@channel variables refer to the channel through which a message is received. For example, if a contact sends a message to an Android channel connected to your account, the @channel variable will refer to number assigned to that phone's SIM card.

@channel - the phone number that received the last message from a contact, in a human readable format, e.g. "(206) 555 1212"
@channel.name - the name of the channel (this can be edited by clicking a channel) ex: "Nexus 5"
@channel.tel - the phone number that received the last message from a contact, in a human readable format, e.g. "(206) 555 1212"
@channel.tel_e164 - the E164 format of the phone number that received the last message from a contact, e.g. "+12065551212"

Date Variables


@date variables refer to time values in the timezone you've assigned to your account. Note that the format of @date variables are dependent on your date format settings

@date - The current date and time, e.g. "02-05-2014 20:08"
@date.now - The current date and time, e.g. "02-05-2014 20:08"
@date.today - The current date, e.g. "02-05-2014"
@date.tomorrow - The date tomorrow, e.g. "03-05-2015"
@date.yesterday - The date yesterday, e.g. "01-05-2014"

Parent, Child Variables


In child flows, entered through Start Another Flow actions and Subflow RuleSets@parent can be used to reference the flow fields collected in the previous (parent) flow, e.g. @parent.[field]

Likewise,
@child can be placed in the parent flow to reference flow fields collected by the child flow up to the point the contact either finished the child flow or expired from it.

Extra Variables


@extra references variables returned from an external application via a WebHook. 

6.25 Organizing Flows with Labels

Labels are intended to help you manage a large number of flows. By applying the same label to more than one flow, you can better organize them. You can even create child labels:



To label your flows, first check the boxes next to the flows you want to group together. By clicking on the label button at the top of the list, you'll have the option to apply an existing label or create a new label for the selected flows.



After clicking on the label button, you will see options for all of the labels you have previously created as well as an option to add a new label.



If you've created other labels, you'll be given the option of adding the new label to a parent label: 



Parent labels are denoted by a "play" icon: 



6.26 Viewing and Exporting Flow Results

Viewing Results


When your contacts interact with a flow, their responses are stored as flow results which you can access by selecting "Results" from the gear icon drop-down menu in the flow editor. 



The results page will provide a "Download Results" button in addition to listing each contact that has interacted with the flow and the number of runs they've made. Passage through a flow from entrance to exit - and all activity that takes place in between - constitutes a run. Contacts exit a flow when: 


Viewing Runs


Clicking the Runs value for a contact will bring you to a page that displays the contents of each run via the simulator: 



Runs comprise the rows that make up your results export spreadsheet. Columns will contain each contact's:


Deleting Runs


You can search for and delete runs via the flow results page, simply hover over the run and click the 'X' icon that appears. 


Exporting the Results of Multiple Flows


To export the results of multiple flows, navigate to the "flows" tab and select the boxes of the flows you'd like to export, then click the export icon that appears above your flows when one or more is selected.

Downloading Your Results


After clicking the "Download Results" button, the 'Export Flow Results' dialogue will appear: 



Here, you can choose to: 
After clicking 'OK', a prompt will appear indicating that a link to the page where you can download your results has been sent to the email address attached to your account.

Depending on the settings you select in the 'Export Flow Results' dialogue, the exported XLS file will contain 3 tabs: 
Here's an example of how the runs tab of an export spreadsheet might look: 



Here are the response rules assigned to the split step that categorizes responses to that message ("1 Begin" above): 



Each response is presented in three columns - Category, Value, and Text 

6.27 Exporting a Flow

Use this action to export flows from RapidPro. You can export a flow to share with other accounts, or to save a specific version of your flow for later use. 

To export a flow: 

1. Navigate to the flows tab.  

2. Click the flow you want to export. 

3. Once in the flow editor, click the gear icon:



4. Select the "Export" option within the gear icon drop-down menu. 

5. A JSON file will begin downloading in your browser. 

6.28 Importing a Flow

Use this action to import flows into your account.   

In order to import a flow to your account, you must have purchased credits. Accounts that have not purchased credits may not import flows.

To import a flow: 

1. Click on your account in the top right corner of the page. 



2. Click on the gear icon to access its drop-down menu and then click on the Import to begin the import process. 

3. Choose the file you wish to import. 



4. Click the Import button. 



Please note that if the flows you're importing match the names of others that exist in your account, the pre-existing flows will be replaced and all history associated with them will be lost.




Triggers 7

7.1 Introduction to Triggers

Triggers allow you to control how or when a flow begins. A flow can be triggered by a keyword or missed call, and scheduled on a future date.


7.2 Creating a Keyword Trigger that starts a Flow

A keyword is the first word in a message, and can be used to initiate a flow. For example, you can set a trigger using the keyword "JOIN" to start a flow that registers contacts for your service.

To create a new keyword trigger:

1. Navigate to the "triggers" tab, then click the "Create Trigger" box. 

2. Click the "Create an SMS keyword that launches a Flow" option.

3. Enter your keyword, then select the flow you want it to trigger. 

4. Optional: You can choose the group(s) to which your keyword trigger will apply. If you leave this field empty, your keyword trigger will apply to anyone who sends it. 

5. Click the "Create Trigger" box. 


7.3 Creating a Keyword Trigger that allows people to join a Group

Use this trigger to add contacts to a group. This trigger is useful for managing contacts that unsubscribe using common the common opt-out keywords "stop" or "unsubscribe."

To create a keyword trigger that adds contacts to a group: 

1. Navigate to the "triggers" tab, then click the "Create Trigger" box.

2. Click the "Create an SMS that allows people to join a group" option. 

3. Enter your keyword, then choose the group you'd like your contacts to join.

Optional: You can also choose to trigger a flow or send a single message. 

In the example below, we've set the keyword trigger "Register" to place contacts in the "Customers" group and start the "Customer Registration" flow. 


7.4 Starting a Flow in the future or on a schedule

Use this trigger to schedule a flow sometime in the future, or repeat it on a daily, weekly or monthly basis. 

To trigger a flow in the future or on a schedule: 

1. Navigate to the "triggers" tab and click the "Create Trigger" box. 

2. Click the "Start a flow in the future or on a schedule" option. 

3. Choose the Flow you want to start, which Contacts you want to receive it, and the date and time you want the Flow to start.

4. Optional: You can also choose to repeat the flow on a daily, weekly, or monthly basis.

5. Click "Create Trigger" box. 




7.5 Ignoring Keywords while in a Flow

When a contact sends a message that matches a keyword you've set to start a flow, they'll automatically be placed inside it by default. This means that if a contact has been placed inside flow A and has responded with a message that contains a keyword that starts flow B, they'll leave flow A for flow B. This is useful in situations where you want to allow your contacts to move between flows at will using keywords.

If you want to keep your contacts in a flow until they've either completed it or expired from it, you can configure it to ignore keyword triggers until your contacts' have left it. 

To tell a flow to ignore keyword triggers: 

1. Navigate to the "flows" tab and click the flow you'd like to modify. 

2. click on the gear icon in the top right corner of the flow editor, then click the "Edit" option.



3. Click the "Ignore keyword triggers while in this flow" box. 



4. Click the "Save Changes" box to complete your flow edit.  

7.6 Start a Flow after receiving a message not handled elsewhere

Use this trigger to start a flow after receiving an uncaught message (a message not handled by any of your other flows or triggers). We refer to this as the "catch-all" trigger, as it can be used to route uncaught messages to any of your flows. 

To create a catch-all trigger: 

1. Navigate to the "flows" tab and click the "Create Trigger" box. 

2. Click the "Start a flow after receiving a message not handled elsewhere" option. 

3. Choose the flow you want to start. 

4. Click the "Create Trigger" box


Campaigns 8

8.1 Introduction to Campaigns



Campaigns allow you to schedule messages and workflows around a specific date, such as a registration or purchase date. Campaigns are often used for DRIP communication such as maternity health reminders, therapy adherence messages, or messages that correspond with the lifecycle of a product or service.

Creating a Campaign

Use this guide to create your first campaign. Specifically, we'll show you how to create a campaign that sends a customer satisfaction flow 7 days after the customer's purchase date.

To create the campaign, you'll need:

(1) A contact group to which the campaign will send messages. A group can be created via the Contacts page using the 'Create Group' button in the bottom left corner. Alternatively, a group can be created within the 'Add contact to a group' flow action.

(2) A date & time contact field. A contact field can be created via the Contacts page. Click the 'Manage Fields' button to add the field and set its value type:

(3) A campaign. Campaigns can be created via the Campaigns page using the 'Create Campaign' button.

Note that each campaign operates on a single contact group:

(4) A flow to be sent out over the duration of the campaign. In this case, we'll be sending the 'Sample Flow - Customer Satisfaction' present in all new RapidPro accounts.

(5) A campaign event to send our customer satisfaction flow. An event can be created via the 'Add Event' button present within your campaign.

Note that a campaign event requires a contact field containing a date & time value around which it can be scheduled.

    Scheduling the Campaign


    Once your contact field has been created, you'll need to initiate the campaign. You can accomplish this by starting the contact in a flow containing a purchase confirmation message, an 'Add contact to a group' action that places the contact in the campaign's group, and an 'Update the Contact' action that'll record the time the contact received the message.

    The 'Update the Contact' action uses the '@date.now' variable to update the 'Registration Date' contact field with the date and time the contact receives the message.

    Once the contact has been placed in the campaign's group and our event's contact field has been updated, the campaign becomes active. You click each event to view it's upcoming messages:

    8.2 Creating a Campaign

    A campaign requires a name and a contact group to send events to. Note that each campaign may only operate on one group.

    Creating a Campaign


    1. Navigate to the campaigns tab.

    2. Click the "Create Campaign" button on the top left side of the page.



    3. Give the campaign a name and
     select the group the campaign will operate on. 


    8.3 Adding a Campaign Event

    A campaign event represents an action that is performed at a time relative to a datetime value stored within a contact field. As such, a campaign event must define the contact field it's relative to, the offset to that field (the amount of minutes, hours, days, weeks before or after the contact field value), as well as the action to perform (send a message or start a flow).

    Creating a Campaign Event


    1. Navigate to the campaigns tab, then click the campaign to which you'd like to add an event.



    2. Click on the "Add Event" box in the upper right corner.

    3. Select the action you'd like to assign to the event.

    4. Set the date and time you want your event to fire (this is referred to as the "offset"). The following inputs comprise an offset: 



    5. If you've added additional secondary languages to your account, you can toggle them to add your own translations to the message. In the example below, a Spanish translation is being added for those contacts who prefer to receive messages in Spanish


    8.4 Editing Events

    To edit when a Message or Flow is sent out, to change the Flow, or to switch from sending a Message to starting a Flow as part of a Campaign Event:

    1. Click on the "Campaign Icon" in the top, right of the page and then click on the "Campaign" that contains the Event that you want to edit.



    2. Click on the grey-shaded "Due Date" box for the Event that you want to edit.  NOTE: You can also access the Contacts Group and the Flow associated with an Event from this page by clicking on the blue, hyperlinked text.



    3. Click on the "Edit" box in the upper, right of the page.

    4. Using the drop-down menus on the Update Event dialog box you can change:


    5. Click "Save Changes."

    8.5 Deleting Events

    To delete an Event from a Campaign:

    1. Click on the "Campaign Icon" in the top, right of the page and then click on the "Campaign" that contains the Event that you want to edit.



    2. Click on the grey-shaded "Due Date" box for the Event that you want to delete.  



    3. Click on the "Gear Icon" in the upper, right of the page and select "Delete".



    4. Click "Remove." Remember, once the Event is removed it can't be undone and you will need to recreate it if you change your mind.



    8.6 Editing Campaigns

    To update or edit the Name of a Campaign or the Group that it operates on:

    1. Click on the "Campaign Icon" in the top, right of the page and then click on the "Campaign" that you want to edit.



    2. Click on the "Gear Icon" in the upper, right of the page and select "Edit."

    3. Change the Name of your Campaign and/or the Group that the Campaign operates on and click "Save Changes."


    8.7 Archiving Campaigns

    To inactivate a Campaign you can Archive it.

    1. Click on the "Campaign Icon" in the top, right of the page and then check the box to the left of the Campaign you want to Archive.

    2. Click on the "File Box Icon" above the names of the Campaigns and the Campaign will be Archived.  



    You can view all of your Archived Campaigns by going to the Campaign page and clicking on "Archived" in the box on the left of the screen.

    8.8 Activating Campaigns

    If you want to reactive a campaign you previously archived, you can do so by following these steps:

    1. Click on the "Campaign Icon" in the top, right of the page and then click on "Archived" in the box on the left of the screen to pull up a list of your Archived Campaigns.

    2.  Check the box to the left of the Campaign you want to Activate and then click on the "Stopwatch Icon."  This will Activate your Campaign.



    You can view all of your Activate Campaigns by going to the Campaign page and clicking on "Active" in the box on the left of the screen.

    Voice (IVR) 9

    9.1 Adding a Voice-enabled Twilio Number

    You can purchase a voice-enabled Twilio number and connect it to your RapidPro account in minutes, or, if you're in a country where Twilio doesn't yet provide virtual numbers, you can either try Nexmo or test your voice flows with an Android channel (see process here).

    You can add a voice-enabled Twilio number by following the steps outlined here. Make sure to check the 'Voice' capability in addition to SMS:


    9.2 Adding a Voice-enabled Nexmo Number

    First, signup for a Nexmo account and add a voice-enabled number:


    Next, login to your RapidPro account, navigate to the channels page and click 'Connect Nexmo'. If this is the first time you’re connecting a Nexmo account to your RapidPro account, you’ll be prompted to enter the API key and secret listed on your Nexmo account’s settings page

    Once you’ve connected your accounts, all you need to do is select your number, create a voice flow and start sending.

    Learn how to add your own audio to outgoing messages here.

    9.3 Adding IVR to your Android Channel

    Adding IVR functionality to your Android Phone is useful for:
    *Having a contact call your number and hang-up with the expectation you'll call them back (the caller picks up fees while it's free to receive calls). Useful in the absence of a toll-free number. 

    To enable IVR functionality on your Android Relayer, you'll need to sign up for a Twilio account. Twilio's TwiML API will handle outbound calls, while the Android Relayer will handle inbound and outbound SMS messages. 

    Use your Twilio account to verify new outgoing caller ID numbers. To use your dashboard, log into your Twilio account and visit the Phone Numbers tab. Click the Verify a number button at the top of the page.

    Twilio now imposes International Voice Dialing Permissions on each new account. You'll need to complete a request form to call countries not listed on this page (must be logged-in to your Twilio account to view). 

    This guide assumes that you've connected an Android channel to your account.

    Connecting your Twilio Account



    1. Navigate to your account page and click the gear icon in the top right corner, then select the Add Channel option. 

    2. Click the Twilio Number button. 



    3. You'll be prompted to enter your Twilio Account SID and Account Token.




    These can be found on your account page: 



    4. Verify the phone number of the Android phone you've connected to your RapidPro account. 



    5. After you've entered your Twilio account credentials and verified the phone number of your Android channel, navigate to your account page and click on the "Enable Voice" button.



    You're ready to create a voice flow! See this article to get started. 





    9.4 Creating a Voice (IVR) Flow

    Interactive Voice Response (IVR) workflows allow you send recorded voice messages to which your contacts can respond by using their keypad or recording their own message. 

    Voice workflows are handy for three reasons: 
    Voice flows are only available to accounts who've added voice-enabled Twilio or Nexmo numbers. If neither Twilio or Nexmo provide voice-enabled phone numbers in your country, you can use Twilio to add voice functionality to an Android channel.

    To create a voice flow, navigate to the flows tab and click the 'Create Flow' box. At the bottom of the dialogue, adjust the Run flow over setting to Phone Call. Click 'Ok'. 











    9.5 IVR Flow RuleSets

    The RuleSets available within a voice workflow vary slightly from standard messaging RuleSets to conform to the keypad input method. 

    Menu Selection 


    The menu selection RuleSet allows you to provide up to 10 menu options to your Contacts. 

    E.g. "To make a deposit press 1, to add or update card details press 2, to cancel last deposit press 3, to speak with a representative press 4, to replay this message press 5."

    Simply type the name of the menu option in each blank space, like the example below:  


    Wait for Multiple Digits


    The wait for multiple digits RuleSet allows you to collect information from a contact such as an ID number, serial number or phone number followed by the # symbol to indicate the end of the input.  

    E.g. "Please enter your member ID number followed by the # symbol."

    You can choose select the Rule that corresponds with the format of the information you desire to collect. If the code you're collecting must start with a particular number, you can elect to run the "starts with" response rule to match that particular number.


    Wait for Recording


    The wait for recording RuleSet allows you to record a message from a user. The contact will hear a short beep, indicating they can speak. 



    Voice responses can be played: 

    1. From the results page accessed within the flow editor gear icon menu: 



    2. By clicking the phone icon next to the Made a recording events listed within each contact's profile page: 



    Note that your contacts' voice recordings will be stored in your flow results exports as links, which you can listen to by placing them in your web browser's address bar and pressing enter. 


    9.6 Adding Audio to Play Message Actions

    You can add your own audio to your messages by grabbing a microphone or headset and record yourself using Quicktime or Windows' Sound Recorder. Once your messages are recorded, head over to media.io to convert them to WAV files, then click the microphone icon in the bottom right corner of the messages to add them to your workflow. 


    Once uploaded, you can click the play button in the bottom right corner to listen to each message's voice file. 


    Note that services like IVONA provide high quality text-to-speech voices for most languages. 

    9.7 Simulating an IVR Flow

    RapidPro allows you to simulate a voice workflow using the nearest phone. Simply click the simulator, enter the phone number you'd like RapidPro to call, and you'll experience the call as your contacts would. 

    9.8 Replaying a Contact Recording



    The play a contact recording flow action allows you to play a contact's voice message collected by wait for recording RuleSet. 

    This action is useful for verifying a contact's response or allowing them to hear their message and re-record if they aren't satisfied. 

    Create a Recording Step


    First, create a wait for recording RuleSet. In the example pictured below, we're saving the recordings we collect to the flow variable "Recording", which we can call at a later step using the variable @flow.recording.  



    Next, create a play recording step by selecting Play a contact recording from the ActionSet menu. Choose the recording you'd like to play by referencing the flow variable created a Wait for Recording RuleSet. In the example pictured below, we use @flow.recording





     


    9.9 Viewing Call Logs

    Call logs provide an audit trail for both successful and unsuccessful calls. To access a channel's call log, navigate to your account's settings page and click on the number that initiated the call: 



    Next, click the 'Sending Log' button to access the channel's sending log: 




    You'll arrive at the messages portion of the channel's sending log. To access the calls portion, click the 'Sessions' button: 



    You'll see a list of outgoing call sessions. Click one to view the requests made during the call: 




    Each request is expandable, so can view relevant parameters. It's best to compare our logs with those provided by Twilio or Nexmo. 

    Zapier 10

    10.1 Integrate Zapier with your RapidPro Account


    Zapier allows anyone to integrate RapidPro with over 500 other apps like Google Sheets, Slack and Salesforce without writing a single line of code.

    Specifically, it enables you to create connections that pass information fro one app to another. For example, you might use Zapier to:

    How it Works

    Zapier watches your apps for new data and kicks off triggers and actions based on the rules you set. Each trigger and action pairing is called a 'zap'. Here are some examples:


    Supported Zaps

    The RapidPro Zapier app currently has one action and one trigger, though we're happy to explore additions based on your feedback.

    The action, 'Start Flow', allows you to start one or more contacts in a flow using data from another app. Check out this video for a quick tutorial:

    The trigger, 'Flow Event', sends all of the responses collected by a flow up to the 'Call Zapier' step to the app of your choice. Check out this video for a quick tutorial:


    Try it Out

    If you haven't already, head over to Zapier to discover more use cases and sign up for a free account. You can use the templates listed below to get started: 

    Add new RapidPro flow responses to new rows on Google Sheets
    Post new RapidPro flow responses to a Slack channel
    Create Zendesk tickets from new RapidPro flow events
    Create Freshdesk tickets from new RapidPro flow events
    Add new Mailchimp subscribers to a RapidPro flow
    Create HubSpot contacts from new RapidPro flow events
    Add Mailchimp subscribers from new RapidPro flow events
    Add new Typeform respondents to a RapidPro flow
    Create Zoho CRM leads from new RapidPro flow events
    Add Salesforce contacts from a new RapidPro flow event

    Have a workflow you need to automate, but aren't sure how? We're happy to help.

    Facebook Messenger 11

    11.1 Introduction to Facebook Messenger

    In 2016, Facebook launched the Messenger Platform, a platform that allows developers to build interactive chat bots to communicate with over 900 million monthly Facebook Messenger users on behalf of any Facebook Page (brand, business or cause). Accordingly, we released a Facebook Messenger channel that will allow you to leverage RapidPro’s visual, comprehensive drag-and-drop interface to build and deploy your own Messenger bot. Build just one bot, and your experience is available on all platforms where Messenger exists, including iOS, Android, and the Web.

    Bots on Messenger will have the same functionality as anything you’d normally build with RapidPro, like weather and traffic updates, and receipts, shipping notifications, and live automated messages. Contextual, convenient, and delightful.

    Facebook is focused on facilitating business <> customer interactions that provide meaningful value to both participants—a cause that aligns with our own.

    We’ve always advocated for SMS and voice (IVR). They’re among the most effective communication channels in today's mobile centric world. That being said, web-based bots appear to be the next step in the evolution of mobile interaction and we’re bullish on their future. See this guide to submit a Messenger bot for review and connect it to your RapidPro account.

     

    11.2 Create and Submit your Bot for Review

    Facebook requires each new Bot to be submitted for review. Before beginning this process, login to your RapidPro account and build your Bot. This is an important step, as Facebook recommends submitting a video depicting an interaction with your Bot. 

    Getting Started

    Login to your RapidPro account to use the following links to access specific pages in your account.

    For this integration, you’ll need:

    Creating your Bot

    First, create an account on Facebook's Developer Platform. Once logged in, use the ‘My Apps’ menu in the top righthand corner to select ‘Add a New App’.


    An ‘Add a New App’ dialogue will appear, asking you to select a platform. Click the ‘basic setup’ link near the bottom; you can add your platform at a later step.

    Next, you’ll be prompted to create an App ID for your new app.


    Once you've registered your app, navigate to the ‘Messenger’ tab and click ‘Get Started’.

    At this point, you’ll need to generate a Page Access Token. If you already own a Page, you’ll be able to select it from a drop-down menu. If you don’t, a link will be provided to create a new one.


    Once you’ve received your Page Access Token, navigate to your RapidPro account in a separate tab and claim a Facebook channel. Enter your Page Access Token to receive your callback URL.


    Back in the 'Messenger' tab, within the 'Webhooks' section, click ‘Setup Webhooks’ to enter your callback URL and check all boxes to subscribe to all incoming Facebook events.


     Within the same section, select the page whose events you'd like the webhook to subscribe to.


    Next, navigate to the ‘Settings’ tab and click ‘Add Platform’.


    There, you can add the URL of your website as your platform. Once added, click ‘Save Changes’ to continue.

    Prior to submission, navigate to the ‘App Details’ tab and complete it.

    Submitting your Bot

    Now you’re ready to submit your app. Note that each new Messenger Bot is subject to an internal review process; use the information in this link to ensure your content is acceptable per Facebook's approval criteria.

    Navigate to the ‘App Review’ tab and click ‘Start a Submission’. Select ‘pages_messaging’ from the list on the lefthand side of the dialog and continue.


    Once you've selected the 'items' you'd like to add, click the 'edit' links next to them to fill out their corresponding forms.


    Finally, click 'Submit for Review' to complete the submission process.

    Considerations


    11.3 Triggering a Flow When a Contact Initiates a Conversation

    When a person starts a new conversation with your bot, you can set expectations with a get started flow to kickoff the experience. 

    To create your conversation trigger, simply navigate to your RapidPro account's Triggers page and click the 'Start a flow when a conversation is started by a contact' trigger: 


    Note that 'Channel' references the Page your Bot is attached to, while 'Flow' represents the flow you'd like to start when a contact initiates contact with your Bot. 

    Telegram 12

    12.1 Introduction to Telegram Channels

    Telegram channels give you access to a super-fast, simple and free platform used by over 62 million people around the world through any mobile device. Telegram is a cloud-based instant messaging service - similar to WhatsApp and WeChat - with a focus on speed, openness and security. It's open source and encrypted end-to-end, meaning that all data sent and received via Telegram cannot be deciphered when intercepted by your ISP, network administrator or other third parties.

    Why Telegram?

    There are five key factors that make Telegram our first choice for cloud-based messaging:

    1. Unlike most cloud-based chat applications, Telegram provides an open API that encourages integration and development.
    2. Telegram's values of openness and security fall in line with our own, allowing us to provide an encrypted channel for organizations communicating sensitive information.
    3. It's completely free.
    4. Telegram will allow you to send up to 30 messages per second - the same throughput a short code would allow at no cost.
    5. Telegram provides a web app; a desktop version for Mac, PC and Linux; and mobile apps for all iOS and Android devices. It can be used anywhere an internet connection is available.

    How Does it Work?

    Your Telegram channel will be represented by a Bot. Telegram Bots are special accounts that will serve as an interface for the workflows and messages you send via RapidPro. Bots differ from standard accounts in that they:

    Much like RapidPro, Telegram Bots allow you to create custom tools that provide you with alerts, weather forecasts, translations, or other services upon request, e.g. Poll bot.

    Bulk Messaging

    As it stands, Telegram doesn't provide a method for sending bulk messages or notifications. In fact, a Bot not connected to RapidPro can't initiate conversations with new users. A new user must either add them to a group or send them a message first (they can use telegram.me/<bot_username> links or username search to find your bot). However, when a Bot is connected to your RapidPro account, your Telegram contacts become RapidPro contacts, allowing you to leverage our broadcast functionality to initiate conversations and send bulk notifications with ease. 

    12.2 Adding a Telegram Channel

    You can add a Telegram channel just like you would any other channel: simply log-in, navigate to the Add Channel page and select the Telegram option at the bottom of the page:

    You'll be asked to enter an authentication token from your Telegram Bot, which is provided after you create it in Telegram.

    Follow the instructions provided to create your Bot. The first step is to find and initiate a conversation with the BotFather:

    After initiating the conversation, send the /newbot command and give your bot a name. You can follow the link provided to give your Bot a picture and description. Then, plug the authentication token you're provided into your RapidPro account.

    Multimedia


    Each link placed in a Telegram message is automatically expanded to that content or media. Here's an example:


    Considerations

    Each time a new contact initiates a conversation with your Bot, they'll do so by tapping or typing the /start command*. You can assign an introductory workflow, e.g. a registration workflow, to your Bot by creating a 'start' keyword trigger.

    Try it Out

    We've created some RapidPro Bots to demonstrate what's possible. You can interact with them by creating or opening a Telegram account and searching for Purrington, a Bot that provides facts about cats, or Snowman, a Bot that provides weather reports for the Northwest Washington area:


    Twitter 13

    13.1 Introduction to Twitter Channels

    In addition to voice and SMS, RapidPro allows you to apply our unique workflow engine to Twitter direct message interactions. Twitter workflows are useful for greeting new followers or polling pre-existing ones. Moreover, they allow you to engage constituents or clients who are active on a platform that serves 320 million monthly active users, 80% of which access the platform via a mobile phone. UNICEF's U-Report program, for example, utilizes Twitter workflows to disseminate polls among youth in various countries with great success. 

    How it Works - Managing your Followers

    RapidPro allows you to connect your Twitter account, which then constitutes a channel. Once connected, anyone who direct messages your Twitter account will appear as a contact within your RapidPro account, and may interact with any of your SMS workflows in this manner. RapidPro provides a default field that stores your contact's twitter handles:

    Any incoming direct messages will be automatically stored by RapidPro, and you'll be able to send direct messages to contacts using their twitter handle so long as their account is enabled to receive direct messages from anyone. For example, if a follower sends you a direct message containing a keyword trigger you've assigned to one of your flows, they'll receive a response just as they would via SMS. Alternatively, you may create a trigger that sends a workflow or message to anyone who follows you. This is how we've structured our RapidPro account.

    Give it a Try

    See what it's like to interact with a Twitter workflow triggered by a follow by following RapidPro on Twitter. As always, make sure to follow Twitter's rules and best practices :)


    13.2 Connecting your Twitter Account to RapidPro

    To connect your Twitter account, simply add a channel and select the Twitter option:

    Then, make sure your account is enabled to receive direct messages from anyone. You can do so from your Twitter Security Settings.

    Note that Twitter currently limits accounts to 1,000 direct messages sent per day. If you expect to exceed this number, you'll need to contact Twitter directly to request that they lift that restriction for your account.

    Authorize the integration, then you're ready to send direct messages:

    Your twitter handle will appear on your account page as a channel:

    13.3 Creating a Twitter Workflow

    Twitter workflows are created just like SMS workflows, simply select 'text messaging' from the creation dialogue, then start building:

    Note that Twitter direct messages are no longer limited to 140 characters, so you can ignore the Send Message character counter:

    13.4 Creating a Follow Trigger

    You can trigger a flow to send each time you gain a new follower by navigating to the triggers tab, scrolling to the bottom, then selecting the "Start a flow after being followed by a new contact" trigger:

    Choose the Twitter account you'd like the trigger to apply to, then select the flow you'd like to send:


    Surveyor 14

    14.1 Introduction to the RapidPro Surveyor App

    Introducing Surveyor

    Our Surveyor Android application is a rugged compliment to our web application, allowing you to author, field, and manage mobile chat-based data collection workflows anywhere in the world - all you need is an Android device and a charge. Specifically, it provides an out-of-box solution for users to:

    See it in Action



    You can download Surveyor for free from the Google Play Store and link it to your RapidPro account. 

    14.2 Creating a Surveyor Flow

    Surveyor workflows differ from SMS or voice workflows in that they're intended for use within the RapidPro Surveyor Android application in environments where internet and cellular connections are weak, if not non-existent. Messages submitted are answered immediately, and flow runs (flow results) are saved until you're able to upload them to your RapidPro account via an internet connection. Note that Surveyor flows are started via the Surveyor Android app.

    Creating the Flow


    To create a flow, navigate to the "flows" tab and click the "Create Flow" button:



    The "Create Flow" dialogue will appear, where you can:
    1. give the flow a name
    2. assign it keyword triggers
    3. specify how long inactive contacts will remain in the flow before being removed
    4. select the Android phone flow type
    5. set the language in which you'll edit it



    Once you've assigned your flow the proper attributes click the "Create" button to enter the flow editor.

    Contact Creation



    (accessed via the "Edit" option in the settings menu in the flow editor)

    By Run


    By default, a new Surveyor flow will create a new contact for each run completed. You can use the Update Contact action to save each of the responses submitted to that contact's profile. The intended use case is to allow enumerators, project managers and M&E officers to collect information about a person, place or event and save the results as a contact. In the example Surveyor flow pictured below, the resulting contact will be the medical facility the enumerator is collecting information about:


    By Login


    Alternatively, Surveyor flows can be run just like SMS flows by contacts who've downloaded the Surveyor app. Like a Twitter or Telegram channel, this provides a free communication channel for your contacts. To use Surveyor in this way, you must unlock account roles and assign Surveyor privileges to the email addresses of the contact who will be using Surveyor in this way. Then, simply toggle the flow to create a contact for each login. Each contact with a Surveyor role will then be able to download and run the flow by logging-in with their email address and password.

    14.3 Adding Surveyors

    Accounts that have purchased 100,000 or more credits may add additional users with varying levels of access

    One of these users types is a SurveyorSurveyors may download the RapidPro Surveyor application, gain access to an account using the account's password, and then run flows on behalf of the account.

    Adding a Surveyor


    There are two ways a Surveyor can gain access to an account: 

    1. Anyone given a password can download Surveyor, create an account, and access Surveyor flows for the associated workspace. 



    You can create a password for your Surveyor users via the User accounts link at the bottom of your account page. 



    2. Surveyors can be manually added through the Manage Accounts  button that is displayed after clicking the User accounts for... link at the bottom of your account page. 




     
    Once at the Manage User Accounts screen, simply enter the person's email address, select their User group and click the "Save Changes" button. 



    Expressions 15

    15.1 Expression Syntax

    All expressions begin with an "@" symbol and an open parenthesis, e.g. '@(HOUR(NOW()))' or '@(SUM(contact.<field>, 1))'. Once entered, "@(" will trigger a completion dialogue that lists and explains each function: 


    Simple Syntax


    This is used to embed single values, e.g.

    Hi @contact, you entered @flow.age for age. Is this correct?
    
    An expression can also be a function call, e.g.

    Hello @(UPPER(contact.first_name))
    Function names are not case-sensitive so UPPER is equivalent to upper. RapidPro supports a subset of the functions available in Excel and these are listed below.

    Advanced Syntax


    This is used to build more complex expressions using similar syntax to Excel formulae, e.g.

    Hi @(PROPER(contact)), you are @(YEAR(NOW()) - flow.year_born) years old. Is this correct?

    Expressions can also include arithmetic with the add (+), subtract (-), multiply (*), divide (/) and exponent (^) operators, e.g.

    Result is @(1 + (2 - 3) * 4 / 5 ^ 6) units

    Note that the expression is enclosed in parentheses to tell RapidPro where it ends.

    You can also join strings with the concatenate (join) operator (&), e.g.

    Hello @(contact.first_name & " " & contact.last_name)

    15.2 Logical Comparisons

    A logical comparison is an expression which evaluates to TRUE or FALSE. These may use the equals (=), not-equals (<>), greater-than (>), greater-than-or-equal (>=), less-then (<) and less-than-or-equal (<=) operators, e.g. 

    @(contact.age > 18)
    
    Note that when comparing text values, the equals (=) and not-equals (<>) operators are case-insensitive.

    15.3 Date & Time Arithmetic

    RapidPro emulates most of the date and time operations available in Excel. For example, to add 7 days to a date, just add the number 7, e.g.

    See you next week on the @(date.today + 7)
    To rewind a date by a certain number of days, just subtract that number, e.g.

    Yesterday was @(date.today - 1)
    To add or subtract months, use the EDATE function, e.g.

    Next month's meeting will be on @(EDATE(date.today, 1))
    To change the time of datetime value, add or subtract the result of the TIME function, e.g.

    2 hours and 30 minutes from now is @(date.now + TIME(2, 30, 0))

    15.4 Function Reference

    Function Reference


    Function arguments in square brackets ([ ... ]) are optional. Note: when substituting RapidPro variables, e.g. @(TIMEVALUE(flow.12_hour_time.category)), quotes aren't necessary. 

    Date & Time Functions


    DATE(year, month, day)

    Defines a new date value, e.g.
    This is a date @(DATE(2012, 12, 25))
    DATEVALUE(text)

    Converts date stored in text to an actual date, using your organization's date format setting, e.g.
    You joined on @(DATEVALUE(contact.joined_date))
    DAY(date)

    Returns only the day of the month of a date (1 to 31), e.g.
    The current day is@(DAY(contact.joined_date))
    DAYS("end_date", "start_date")

    Returns the number of days between two dates.
    @(DAYS("02-28-2016", "02-28-2015"))
    DATEDIF("start_date", "end_date", "units")

    Calculates the number of days, months or years between two dates. Units are abbreviated "D", "M", and "Y".
    @(DATEDIF("02-26-2015", "02-26-2016", "M"))
    EDATE(date, months)

    Moves a date by the given number of months
    , e.g.
    Next month's meeting will be on @(EDATE(date.today, 1))

    HOUR(datetime)

    Returns only the hour of a datetime (0 to 23)

    The current hour is @(HOUR(NOW()))

    MINUTE(datetime)

    Returns only the minute of a datetime (0 to 59), e.g.

    The current minute is @(MINUTE(NOW()))

    MONTH(date)

    Returns only the month of a date (1 to 12), e.g.

    The current month is @(MONTH(NOW()))

    NOW()

    Returns the current date and time, e.g.

    It is currently @(NOW())

    SECOND(datetime)

    Returns only the second of a datetime (0 to 59), e.g.

    The current second is @(SECOND(NOW()))

    TIME(hours, minutes, seconds)

    Defines a time value which can be used for time arithmetic, e.g.

    2 hours and 30 minutes from now is @((date.now + TIME(2, 30, 0)))

    TIMEVALUE(text)

    Converts time stored in text to an actual time, e.g.

    Your appointment is at @((date.today + TIMEVALUE("2:30")))

    TODAY()

    Returns the current date, e.g.

    Today's date is @(TODAY())

    WEEKDAY(date)

    Returns the day of the week of a date (1 for Sunday to 7 for Saturday), e.g.

    Today is day no. @(WEEKDAY(TODAY())) in the week

    YEAR(date)

    Returns only the year of a date, e.g.

    The current year is @(YEAR(NOW()))

    Logical Functions

    AND(arg1, arg2, ...)

    Returns TRUE if and only if all its arguments evaluate to TRUE, e.g.

    @(AND(contact.gender = "F", contact.age >= 18))

    FALSE()

    Returns the logical value false. 

    IF(arg1, arg2, ...)

    Returns one value if the condition evaluates to TRUE, and another value if it evaluates to FALSE, e.g.

    Dear @(IF(contact.gender = "M", "Sir", "Madam"))

    OR(arg1, arg2, ...)

    Returns TRUE if any argument is TRUE, e.g.

    @(OR(contact.state = "GA", contact.state = "WA", contact.state = "IN"))

    TRUE()

    Returns the logical value true. 

    Math Functions

    ABS(number)

    Returns the absolute value of a number, e.g.

    The absolute value of -1 is @(ABS(-1))

    AVERAGE(number, ...)

    Returns the average (arithmetic mean) of the arguments.

    MAX(arg1, arg2, ...)

    Returns the maximum value of all arguments, e.g.
    Please complete at most @(MAX(flow.questions, 10)) questions

    MIN(arg1, arg2, ...)

    Returns the minimum value of all arguments, e.g.

    Please complete at least @(MIN(flow.questions, 10)) questions

    POWER(number, power)

    Returns the result of a number raised to a power - equivalent to the ^ operator, e.g.

    2 to the power of 3 is @(POWER(2, 3))

    RAND()

    Returns an evenly-distributed random real number greater than or equal to 0 and less than 1, e.g.

    0.6160317611

    RANDBETWEEN(bottom, top)

    Returns a random integer number between the numbers you specify.

    ROUND("number", number of digits)

    Rounds a number to a specified number of digits. 

    @(ROUND(9.4378, 3))

    ROUNDDOWN(number, number of digits)

    Rounds a number down towards zero to the specified number of digits. 

    @(ROUNDDOWN(9.4378, 3))

    ROUNDUP(number, number of digits)

    @(ROUNDUP(9.4378, 2))

    Rounds a number up towards zero to the specified number of digits.

    @(ROUNDUP(9.4378, 2))

    SUM(arg1, arg2, ...)

    Returns the sum of all arguments, equivalent to the + operator, e.g.

    You have @(SUM(contact.reports, contact.forms)) reports and forms
    TRUNC(number)

    Truncates a number to an integer by removing the fractional part of the number. 

    Text Functions

    CHAR(number)

    Returns the character specified by a number, e.g.

    As easy as @(CHAR(65)), @(CHAR(66)), @(CHAR(67))

    CLEAN(text)

    Removes all non-printable characters from a text string, e.g.
    You entered @(CLEAN(step.value))

    CODE(text)

    Returns a numeric code for the first character in a text string, e.g.

    The numeric code of A is @(CODE("A"))

    CONCATENATE(args)

    Joins text strings into one text string, e.g.

    Your name is @(CONCATENATE(contact.first_name, " ", contact.last_name))
    FIXED(number, [decimals], [no_commas])

    Formats the given number in decimal format using a period and commas
    You have @(FIXED(contact.balance, 2)) in your account

    INT(number)

    Rounds a number down to the nearest integer.

    LEFT(text, num_chars)

    Returns the first characters in a text string, e.g.

    You entered PIN @(LEFT(step.value, 4))

    LEN(text)

    Returns the number of characters in a text string, e.g.

    You entered @(LEN(step.value)) characters

    LOWER(text)

    Converts a text string to lowercase, e.g.

    Welcome @(LOWER(contact))

    MOD(number, divisor)

    Returns the remainder after a number is divided by the divisor.

    PROPER(text)

    Capitalizes the first letter of every word in a text string, e.g.

    Your name is @(PROPER(contact))

    REPT(text, number_times)

    Repeats text a given number of times, e.g.

    Stars! @(REPT("*", 10))

    RIGHT(text, num_chars)

    Returns the last characters in a text string, e.g.

    Your input ended with ... @(RIGHT(step.value, 3))

    SUBSTITUTE(text, old_text, new_text, [instance_num])

    Substitutes new_text for old_text in a text string. If instance_num is given, then only that instance will be substituted, e.g.

    @(SUBSTITUTE(step.value, "can't", "can"))

    UNICHAR(number)

    Returns the unicode character specified by a number, e.g.

    As easy as @(UNICHAR(65)), @(UNICHAR(66)), @(UNICHAR(67))

    UNICODE(text)

    Returns a numeric code for the first character in a text string, e.g.

    The numeric code of A is @(UNICODE("A"))

    UPPER(text)

    Converts a text string to uppercase, e.g.
    WELCOME @(UPPER(contact))!!

    RapidPro Functions


    These RapidPro-specific functions are not found in Excel but have been provided for the sake of convenience.

    FIELD(text, index, [delimiter])

    Reference a field in a string separated by a delimiter.
    @FIELD("hello world", 2, " ")
    FIRST_WORD(text)

    Returns the first word in the given text - equivalent to WORD(text, 1), e.g.
    The first word you entered was @(FIRST_WORD(step.value))
    PERCENT(number)

    Formats a number as a percentage, e.g.
    You've completed @(PERCENT(contact.reports_done / 10)) reports
    READ_DIGITS(text)

    Formats digits in text for reading in TTS, e.g.
    Your number is @(READ_DIGITS(contact.tel_e164))
    REMOVE_FIRST_WORD(text)

    Removes the first word from the given text. The remaining text will be unchanged e.g.
    You entered @(REMOVE_FIRST_WORD(step.value))
    WORD(text, number, [by_spaces])

    Extracts the nth word from the given text string. If stop is a negative number, then it is treated as count backwards from the end of the text. If by_spaces is specified and is TRUE then the function splits the text into words only by spaces. Otherwise the text is split by punctuation characters as well, e.g.
    @(WORD("hello cow-boy", 2)) will return "cow"
    @(WORD("hello cow-boy", 2, TRUE)) will return "cow-boy"
    @(WORD("hello cow-boy", -1)) will return "boy"
    WORD_COUNT(text, [by_spaces])

    Returns the number of words in the given text string. If by_spaces is specified and is TRUE then the function splits the text into words only by spaces. Otherwise the text is split by punctuation characters as well, e.g.
    You entered @(WORD_COUNT(step.value)) words
    
    WORD_SLICE(text, start, [stop], [by_spaces])

    Extracts a substring of the words beginning at start, and up to but not-including stop. If stop is omitted then the substring will be all words from start until the end of the text. If stop is a negative number, then it is treated as count backwards from the end of the text. If by_spaces is specified and is TRUE then the function splits the text into words only by spaces. Otherwise the text is split by punctuation characters as well, e.g.
    @(WORD_SLICE("RapidPro expressions are fun", 2, 4)) will return 2nd and 3rd words "expressions are"
    @(WORD_SLICE("RapidPro expressions are fun", 2)) will return "expressions are fun"
    @(WORD_SLICE("RapidPro expressions are fun", 1, -2)) will return "RapidPro expressions"
    @(WORD_SLICE("RapidPro expressions are fun", -1)) will return "fun"

    Troubleshooting


    Why is only part of my expression evaluated?

    If the expression is not a single variable or function call, then you must enclose it in parentheses to tell RapidPro where it begins and ends, e.g.
    @(SUM(contact.reports, step.value)) * 2  <-- the "* 2" isn't evaluated
    should be written as
    @(SUM(contact.reports, step.value) * 2)

    Testing/Troubleshooting 16

    16.1 Conducting a Pilot Test

    After testing your flows in the simulator, you’re ready to move to the second step in our recommended testing protocol: the pilot test. A pilot test, or "pilot," is your first trial run; a small-scale version of your larger project, and arguably the most important step in testing your SMS program. Your SMS program will be an automated system comprised of multiple components (contacts, phones, carriers, channels and flows). Moreover, it represents your organization - so it's best to test each one thoroughly.

    A pilot allows you to:

    Pilot requirements

    1. A group of 5-10 independent test contacts that represent your target population.
    2. The current version(s) of your flow(s).
    3. One or more pilot facilitators. This person will conduct the pre and post-pilot evaluations as well as the test itself.  
    4. Observants. These people will observe the test contacts’ responses through the RapidPro dashboard in addition to their overall behavior. See below.
    During a pilot, it’s best to be present with your test contacts. If your flows are scheduled using a campaign, or you want to allow your contacts to respond asynchronously (throughout the day/week at their own leisure), you might compensate by communicating with them at the start or end of each day. Run the pilot 3-5 days prior to your usability test so that you have time to deal with any technical issues and/or make scenario/materials changes.

    Things to look for:

    Best practices


    Remain neutral. If the participant asks a question, reply “What’s your best guess?”Don’t lead your test contacts. If a test contact gives up, you’ll need to decide whether to provide a hint or end the test.

    Focus your observations. Give productive and unproductive paths equal attention. Observants should focus on what the test contacts did in as much detail as possible as well as what they say (in their words). The more you can understand about your contacts’ SMS behavior, the more effective your SMS program will be.

    Measure both performance and preference. People’s performance and preferences don’t always match. This is especially true with regard to their mobile phones. Often, users will perform poorly even though their subjective ratings are high. Conversely, they may perform well but give your program a poor subjective rating.

    Evaluating a pilot


    At the end of a pilot, you should be able to answer the following questions:
    1. Was the test group’s overall reaction positive or negative? The test group’s feedback can help confirm whether or not your program is a good fit for your population and whether minor changes to the program are appropriate and/or necessary.
    2. Are you allocating your time and resources properly? The pilot will help you determine whether you need to spend more time or resources on particular aspects of your program. For example, you might learn that changes to your method of engagement, flow length, or flow timing are necessary.
    3. Does your evaluation strategy need improvement? Look at this as an opportunity to test your evaluation method as well. Are there metrics you’d like to have that you aren’t collecting? The pilot will give your evaluation and implementation teams a chance to work together before increasing scale to troubleshoot any logistical issues that might arise with the distribution and collection of evaluation data.
    4. Are you ready to increase scale? A pilot can shed light on unforeseen challenges that might arise during a larger-scale implementation, and ensure your team is prepared to handle issues that might accompany an increase in scale. This question is largely dependent on the answers to the others.

    16.2 A/B Testing your Flows

    Within RapidPro, you can use the 'Split randomly' RuleSet to create equally distributed pathways through which your contacts will randomly pass, enabling you to test the efficacy of your flows. We also provide a handy simulator on the same page you build your flows to allow you to test them as you build.

    Outside the platform, we encourage you to use your 1,000 complimentary credits to measure flow performance and conduct A/B tests pilot users.

    A/B testing (also called split or multivariate testing) is a method you can employ to test the effectiveness of two or more versions of a single message, flow or campaign with respect to a desired outcome. It's a type of controlled experiment conducted on similar audiences, the initial version being the control and any additional versions being treatments.

    Getting Started

    Conducting an A/B test

    Test one item at a time.

    Let’s say version A addresses your contacts by name while version B doesn’t. When testing two versions of a flow, make sure you’re only measuring the impact of a few changes at a time. If version A is too dissimilar toversion B, you’ll have trouble isolating the variable responsible for the result.

    Send the flow to similar representative samples.

    Show version A and version B to similar groups and ensure each is representative of the entire target population. If you show version A to only experienced contacts and version B to only new contacts, your results may be skewed. Ideally, you want to split your target population evenly.

    Be patient.

    One of the best things about RapidPro is time to deployment. You can sign-up, connect a channel and send messages in as little as 5 minutes if you want to, but this doesn’t mean everyone should take that approach. Being that SMS is just as much an extension of an organization's brand as email, larger deployments need to conduct tests to make sure flows are well-received and driving results.

    Creating flow versions

    Creating a new version of a flow is simple: click the gear icon menu in the flow editor and select the “copy” option. This will produce an exact copy of the flow for you to edit and rename.

    You can link your versions using a 'Split randomly' RuleSet.

    Evaluating the results of an A/B test

    In addition to the primary marker of success you select when you identify your objectives, we provide a completion rate for each flow represented by a percent value. The completion rate allows you to see how many of the contacts that have entered the flow have finished it. Comparing the completion rates of two versions of a flow is easiest way to measure effectiveness.







    16.3 Conducting a Usability Test

    Why conduct a usability test?

    Now that you've chosen the perfect flow, you can conduct a usability test to make sure it’s provides a good experience for your contacts. Usability tests encourage you to focus on your contacts’ experience by assessing ease of use and learnability. This step is important - it allows you to make the best possible impression when you send out the final version of your flow. 

    Usability test requirements

    1. A large group of test contacts representative of your target population.
    2. A clear and precise protocol for your test contacts to follow. This might include a pre-test questionnaire, the test itself, and a post-test questionnaire.
    3. A point of contact who is trained to offer instructions and answer questions. In your pilot test, the facilitator took a more hands-on approach. In your usability test, the facilitator will take a supporting role while your test contacts take the lead. 
    4. Observants who will track the behavior of the test contacts.

    Elements of a usability test plan

    Subjective metrics

    Background questions. Ask these questions prior to the test.

    Ease of use, comfort and satisfaction. Ask these questions after each task is completed.

    Overall ease of use, comfort, and satisfaction. Ask when the test is completed.

    Likes, dislikes and recommendations. Ask test contacts what they liked most about your service, what they liked least about your service, and if they have recommendations for improving it.

    Continued use. The likelihood your test contacts will use your service when the test is completed.

    Net promoter score. On a scale that ranges from extremely unlikely to extremely likely, measure the likelihood that your test contacts would recommend your service to (1) a family member (2) a friend and (3) a colleague.

    Quantitative metrics

    Flow completion. The flow is completed when a contact has successfully passed through each step - be it an action or split step.  

    Critical errors. Critical errors result in your contacts being unable to finish a flow. For example, consistently responding with the wrong answer, an incorrectly formatted answer, an answer you haven’t accounted for, or an opt-out.

    Non-critical errors. Non-critical errors are errors that the contact can recover from. The most common error you’ll experience is a response that is categorized as “other,” causing the contact to be redirected to a split step. These errors result in the flow being completed less efficiently. You’ll want to keep a tally of the amount of non-critical errors occur per contact, per contact per flow, per flow, and overall.

    Error-free rate. The error-free rate is the percentage of contacts who complete the flow(s) without experiencing or committing any errors.

    Time on task. The amount of time it takes the contact to complete the flow(s) - the time a flow was completed minus the time it was started. 

    Test Results  

    Construct an analysis of what you’ve observed. Isolate the flows that had the highest and lowest completion rates. If possible, include a summary of the completion rates by contact, step, and flow. Depending on the metrics you collected you may want to show the:

    Findings and Recommendations

    List your findings and recommendations using all your data. Each finding should have a basis in what occurred during the test.  You’ll want to sort findings and recommendations by flow. Finally, it’s important to keep in mind that identifying positives is equally as important as identifying negatives - what’s working well should be maintained moving forward.

    Implement and Retest

    For a usability test to have value, you’ll need to use what you’ve learned to improve your service. You may not be able to implement all recommendations or requests - developing anything is a series of trade-offs in which you balance a number of factors, such as budget, timeframe, and a handful of external factors.  If you can’t implement all the recommendations, assign priorities based on the most common and prevalent problems. As you prioritize, push to get the changes your contacts want.

    16.4 Troubleshooting Protocol for Delivery Errors

    This guide is intended to help you troubleshoot delivery errors on SMS channels. There are a few possible causes depending on the channel you're using:

    Android Channels 


    An Android channel will experience sending issues if:
    Log into your account, navigate to your account page, and then click your Android channel to view performance stats: 


    Twilio Channels 


    If you're using a Twilio channel and a message failed to deliver, you may be encountering one of the these sending errors

    To view your error and sending logs, navigate to your account page and click your Twilio channel: 



    Next, click either the "Sending Log" button or "View Log" link to view bring up your sending log: 



    You can use your sending log to isolate the issue and make the necessary adjustments. In the log pictured below, the user connected their trial Twilio number to RapidPro and sent messages to a contact whom they hadn't verified through their Twilio account.



    Please include links to errors when sending us a support request :)



    Alternatively, you can send us a link to the profile of the contact to whom the failed messages were sent: 


    Other Channels

    Failed Messages 


    The first step in tracking down failed messages is to navigate to the messages tab and flick the "Failed" folder:

     

    Clicking the red "Failed" icon to the right of the messages will either take you to the channel error description or the profile of the contact to which the message was sent, depending on the status of the channel you used to communicate with them. Please include a link to the error or contact profile in your support request. 

    Flow Issues


    If you suspect a workflow isn't behaving as expected, select "Results" from the gear icon menu located in the flow editor to bring up the most recent runs your contacts have made: 



    Click a run to see what they received: 





    16.5 Tracking and Managing Opt-Outs

    You may want to inform your contacts that they have the ability to opt-out at any time. Here's how to track and manage those that do so: 

    Using an SMS gateway

    Twilio will automatically unsubscribe your users (preventing them from receiving a response) when they send a message containing one of the following keywords: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, and QUIT. START and YES will opt contacts back in to the messages if and only if they’ve been unsubscribed. HELP and INFO will return a stock message informing the contact that they can use the above keywords to control the delivery of messages. If a contact wants to unsubscribe, they’ll receive the following stock message from Twilio:



    The opt-out keyword prevents your contacts from receiving additional messages from your number unless they opt back in. Despite this, they’ll remain in your flow until they expire from it. 

    Tracking opt-outs from your account page

    You can track opt-outs manually within your account page by clicking your Twilio number, then clicking "View Log" in the "ERRORS" panel.

    1. 


    2. 

     
    You'll see the number of the contact who has opted out, as well as the error description: "HTTP 400 error: 21610: The message From/To pair violates a blacklist rule." Twilio returns this error if you attempt to send an SMS to a recipient who has previously replied STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, or QUIT to you. You will not be charged for the message attempt. As mentioned prior, to be able to send messages to such recipients, they must first text START or YES to the Twilio number to opt in again.



    Other ways to tracks opt-outs


    To track opt-outs, you can:

    Create a group that represents your unsubscribed contacts.

    Create a flow that adds contacts to your “unsubscribed” group and assign it keywords. If you’re using a Twilio phone number, you should create keyword triggers that mimic the keywords STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, and QUIT

    .


    Add an Update the contact action that indicates whether a contact has unsubscribed. We’ve created a contact field called “Unsubscribed” that will allow us to see if a contact has opted-out by checking their contact profile. Each time a contact sends one of the keywords that trigger the “Unsubscribe” flow, the “Unsubscribed” contact field will be updated to contain the word “Yes.”




    You can even use the Send a message to somebody else and Send an email actions to notify yourself or others when a contact unsubscribes:

     




     

    Once you’ve completed these steps, you’ll have 4 ways to track opt-outs:
    Educating your contacts

    Unless you’ve notified them, your contacts aren’t likely to know that they can use certain keywords like “start” or “yes” to re-subscribe to your service. This in mind, it may be helpful to add opt-out and opt-in information to your service during registration. Assuming you’ve collected your contacts’ email addresses, the Send an email action also allows you to follow-up with a contact after they've unsubscribed to ask why they unsubscribed and let them know that they can opt-in using certain keywords.

    F. A. Q. 17

    17.1 How does RapidPro Store and Secure my Data?

    Hosting & Data Security Compliance

    We host with Amazon Web Services, and all RapidPro data is stored solely in the United States. Our servers are protected by firewalls, and all access to those servers is permitted only through encrypted channels that are FIPS-140-2 compliant, but no encryption is done on data at rest. 

    Contact Information Anonymization


    We understand that some use cases require contact information to be handled sensitively. This in mind, we added an anonymization feature that'll replace each contact's name with a random code and completely remove their address (their phone number, or an ID associated with their Facebook, Telegram or Twitter accounts):

    Note that 'None' is the default value displayed for empty custom contact fields.

    When the anonymization feature is enabled, each new contact profile, whether imported into RapidPro via a spreadsheet or generated when a new contact interacts with one of your channels, is anonymized. No user will be The contact's UUID, groups, language preference and custom fields will still be accessible. By the same token, exported contact and flow information will also be anonymized.

    Note that this feature is permanent once an account has been anonymized.

    If this isn't sufficient, we're interested to learn how we might improve this feature to accommodate a broader range of use cases.

    Contact us to enable this feature. 

    Data Transfer to/from RapidPro


    There are four methods through which data can be transferred to/from RapidPro: 

    1. Contact information is imported to RapidPro (a spreadsheet containing contacts' names, phone numbers, and any other information you wish to include). 

    2. A contact interacts with your RapidPro account via one of multiple possible channels, where the contents of the messages you've sent them and their responses are stored. 

    3. A Webhook is used to fetch information from an external database to be used in a flow or referenced in a message, or post information (stored as flow variables) collected within that workflow to an external system.

    4. RapidPro's API is used to facilitate data transfer from your system to RapidPro and vice versa. An example of this might be creating an API protocol that enables your system to modify contacts, start flows, or send messages.

    17.2 What is RapidPro's Privacy Policy?

    Date Updated: 4 January 2016

    Date Effective: 4 January 2016

    Welcome to RapidPro, the online and mobile service of Trileet, Inc., a United States Company. ("Nyaruka," "RapidPro", "we," "us," or "our"). Our Privacy Policy explains how we collect, use, disclose, and protect information that applies to the Service, and your choices about the collection and use of information.

    Capitalized terms that are not defined in this Privacy Policy have the meaning given to them in our Terms of Service ("Terms").

    What is the purpose of this Privacy Policy?

    As a tool used to collect and store personal information and other data, your privacy and the privacy of your End-users (contacts) is our top priority. This Privacy Policy discloses our personal information gathering and dissemination practices with respect to the Services, and in conjunction with our Terms. Please read this Privacy Policy carefully.

    Information Collected by the Services

    Personal Information

    “Personal Information” is information that identifies you as an individual, which includes, but is not limited to:

    We may combine your Personal Information with information that we receive from and about you, online and offline, including from third parties.

    Log Information


    Log information is any information automatically reported by your browser or mobile device each time you access our service. When you use our service, our servers automatically collect and store this information, which may include the IP address, browser type, referring site, number of clicks and how you interact with links on the service.

    Analytics Information


    RapidPro may directly collect analytics data, or use third-party analytics tools, to help us measure traffic and usage trends for the Services. These tools collect information sent by your browser or mobile device, including the pages you visit and other information that assists us in improving the Servicse. This analytics data may enable RapidPro to relate your use of the Services to personally identifying information that you previously submitted.

    Information Collected with Cookies


    We use cookies to understand and save your preferences for future visits and compile aggregate data about site traffic and site interaction so that we can offer better site experiences and tools in the future. We may contract with third-party service providers to assist us in better understanding our site visitors. These service providers are not permitted to use the information collected on our behalf except to help us conduct and improve our business. You can reset your web browser to refuse all cookies or to indicate when a cookie is being sent. However, some features of the Service may not function properly if the ability to accept cookies is disabled.

    How we use Personal Information

    Any of the information we collect from you may be used in one of the following ways:

    Information Disclosure

    We do not sell, trade, or otherwise transfer to outside parties your personally identifiable information. This does not include trusted third parties who assist us in operating our website, conducting our business, or servicing you, so long as those parties agree to keep this information confidential. We may also release your information when we believe release is appropriate to comply with the law, enforce our site policies, or protect ours or others rights, property, or safety. However, non-personally identifiable Content information may be provided to other parties for marketing, advertising, or other uses.

    Third Party Links

    Occasionally, at our discretion, we may include or offer third party products or services on our website. These third party sites have separate and independent privacy policies. We therefore have no responsibility or liability for the content and activities of these linked sites. Nonetheless, we seek to protect the integrity of our site and welcome any feedback about these sites.

    Security

    To help protect the privacy of data you transmit through the Services, where personally identifiable information is requested, RapidPro uses SSL/TLS to encrypt the information that is sent between your computer and RapidPro's servers. In addition, RapidPro takes steps to protect the user data we collect against unauthorized access. We host with Amazon Web Services, and all RapidPro data is stored solely in the United States. Our servers are protected by firewalls, and all access to those servers is permitted only through encrypted channels that are FIPS-140-2 compliant, but no encryption is done on data at rest. 

    Who has Access to Messages Transmitted via RapidPro?

    You may use your account settings to control other Users' access to information associated with your User account, such as messages and contact information, if you have enabled Account Permissions. Generally, Content transmitted through or stored by the Services is only available to those with whom you choose to share such information.

    Please note that any messages transmitted via channels with which the Services integrate may be accessible to certain third-party organizations, such as mobile networks, SMS gateway services and social media services. These organizations have their own rules, policies, and security measures controlling who has access to messages transmitted through their services.

    The information that is transmitted through or stored on RapidPro is only available to those with whom you choose to share such information.

    The employees and contractors of RapidPro may in certain circumstances access the information on your account if required for customer support or legal purposes.

    Where is Content Stored and Processed?

    Content and information collected through the Services is stored and processed in the United States.

    Correcting or Updating User Information

    You may correct or update information collected about you by logging in to RapidPro and editing your account settings, or by contacting RapidPro at support@app.rapidpro.io. We will use reasonable efforts to update our records. For our records, we may retain original and updated information for reasons such as technical constraints, dispute resolution, troubleshooting and agreement enforcement. 

    If you have any questions about reviewing or modifying your account information, you can contact us directly at support@app.rapidpro.io.

    How long will you keep my User Content?

    Following termination or deactivation of your User account, RapidPro may retain your profile information and Content for a commercially reasonable time for backup, archival, or audit purposes, unless you explicitly request the deletion of all information and Content pertaining to your account.

    Privacy Policy Updates

    RapidPro reserves the right to update this Privacy Policy from time to time. We will provide you additional forms of notice of modifications or updates in the form of in-app updates and email notifications. Your continued use of the Services after any modification to this Privacy Policy will constitute your acceptance of such modification.

    Please visit this page periodically so that you will be apprised of any changes. When we change the policy in a material manner we will update the "Updated" date at the top of this page.

    Persons Under 13 Years of Age

    We do not knowingly collect or maintain personally identifiable information from persons under 13 years old, and no part of the Services is directed to persons under 13. IF YOU ARE UNDER 13 YEARS OF AGE, PLEASE DO NOT USE OR ACCESS OUR SERVICES AT ANY TIME OR IN ANY MANNER. If RapidPro learns that personally identifiable information of persons less than 13 years old has been collected without verifiable parental consent, then RapidPro will take the appropriate steps to delete this information. If you are a parent or guardian and discover that your child under the age of 13 has obtained a RapidPro account, then you may alert RapidPro at the address below and request that we delete that child's personal information from our systems.

    Contact Us

    If you have any questions about this Privacy Policy, or need to reach us for any other reason, you may contact us by e-mail at support@app.rapidpro.io.

    17.3 What are RapidPro's Terms of Service?

    Date Updated: 5 January 2016

    Date Effective: 5 January 2016

    RapidPro is a service provided by Trileet, Inc., a United States company ("RapidPro," "Nyaruka," "we," "us," or "our"). This page explains the terms by which you may use RapidPro's online and/or mobile services (your account), collectively the "Services". The Services allow authorized users to easily build and deploy custom messaging and voice applications.

    This Terms of Services Agreement (the "Terms") represents the agreement between you and RapidPro, and sets forth the terms and conditions under which you may access and use the Services. The Terms apply to all visitors, authorized users, and others who access the Services ("Users"). Your use of the Services indicates that you accept these Terms and to the collection and use of your information as set forth in RapidPro's Privacy Policy. If you do not accept these Terms, do not use the Services.

    PLEASE READ THESE TERMS CAREFULLY TO ENSURE THAT YOU UNDERSTAND EACH PROVISION. THESE TERMS CONTAIN A MANDATORY ARBITRATION OF DISPUTES PROVISION THAT REQUIRES THE USE OF ARBITRATION ON AN INDIVIDUAL BASIS TO RESOLVE DISPUTES, RATHER THAN JURY TRIALS OR CLASS ACTIONS.

    You may use the Services only if you can form a binding contract with RapidPro, and only in compliance with these Terms and all applicable local, state, national, and international laws, rules and regulations. Any use or access to the Services by anyone under 13 is strictly prohibited and in violation of these Terms. The Services is not available to any Users previously removed from the Services by RapidPro.

    It is important for you to periodically review these Terms as well as RapidPro's Privacy Policy, as we may modify them at any time at our sole discretion. You agree that such modifications are effective and binding upon you immediately upon your use of the Services following the Effective date of the modified version.

    References in these Terms to "we", "us" or "our" shall mean Trileet, Inc., Nyaruka and RapidPro; references to "User" shall mean anyone who visits, uses, or otherwise accesses the Services, including you; references to "End-user" shall mean contact, or any member of the public who sends or receives an SMS, phone call, social media or email via RapidPro; and references to "you" and "your" means you, your employees, contacts, agents, and contractors, and any other entity on whose behalf you accept these Terms, all of whom shall also be bound by these Terms. Please note that these Terms applied to you, the User, also apply to your account's contacts ("End-users").

    If you will be using the Services on behalf of an organization, you agree to these Terms on behalf of that organization and you represent that you have the authority to do so. In such case, “you” and “your” will refer to that organization.

    1. Fees and Payments

    1.1. Fees for Services. You agree to pay to RapidPro any fees for each Services you purchase or use (including any overage fees), in accordance with the pricing and payment terms presented to you for that Services. Fees paid by you are non-refundable, except as provided in these Terms or when required by law.

    1.2. Taxes. All information that you provide in connection with a purchase or transaction or other monetary transaction interaction with the Services must be accurate, complete, and current. You agree to pay all charges incurred by users of your credit card, debit card, or other payment method used in connection with a purchase or transaction or other monetary transaction interaction with the Services at the prices in effect when such charges are incurred. You will pay any applicable taxes, if any, relating to any such purchases, transactions or other monetary transaction interactions. All payments through the Services are processed using a third-party payment processor. You acknowledge that RapidPro is not liable for any breaches of credit card or debit card security or privacy.

    1.3. Price Changes. RapidPro may change the fees charged for the Services at any time, provided that the change will become effective only upon your next credit bundle purchase. RapidPro will provide you with reasonable prior written notice of any change in fees before the change becomes effective.

    1.4. Overage Fees. Unless otherwise stated, any overage fees incurred by you will be applied to the next bundle of credits purchased. Overage fees which remain unpaid for 30 days after being billed are considered overdue. Failure to pay overage fees when due may result in the applicable Services being limited, suspended, or terminated (subject to applicable legal requirements), which may result in a loss of your data associated with that Services.

    2. Privacy

    2.1. RapidPro's Privacy Policy applicable to the Services is available on this website, and is incorporated into these Terms. Alternatively, you may access our Privacy Policy here.

    3. Your Content

    3.1 Definition; Ownership. RapidPro permits the uploading, transmission and receipt of information through the Services ("Content"), and the hosting, transmission, sharing, display and/or analysis of such Content. Content includes (but is not limited to) contact information, and all information sent and received through the Services via SMS, Voice, Social Media, and our RapidPro Surveyor mobile application - including all information sent to your RapidPro account from your contacts.

    Users may use their account settings to control other Users' access to their Content upon purchase of 100,000 or more credits ("Account Permissions"). Generally, Content transmitted through the Services is only available to those with whom you choose to share such Content. RapidPro will employ commercially reasonable efforts to prevent unauthorized access to Content. However, RapidPro does not guarantee that your Content will be kept secure from viewing by others through your account, as this is the duty of the User once Account Permissions are enabled.

    RapidPro takes no responsibility and assumes no liability for any Content that you, any other Users or third parties post or send or receive via the Services. While the occurrence of which is highly unlikely as per our state-of-the-art data security practices, you understand and agree that any loss or damage of any kind that occurs as a result of the use of any Content that you send, upload, download, stream, post, transmit, display, or otherwise make available or access through your use of the Services is solely your responsibility. We claim no ownership rights over Content created or collected by you.

    3.2 License Grant to RapidPro. By submitting Content to the Services, you hereby grant to RapidPro a worldwide, non-exclusive, sublicensable, transferable, perpetual, irrevocable, fully paid-up, and royalty-free license to use, host, display, reproduce, modify, transmit, edit, translate and analyze your Content within the Services in any formats and through any applicable channels for the purposes of providing the applicable features and functionality of the Services, improving the way the Services works and looks, and to create new features and functionality, including without limitation the right to use information derived from your Content on an aggregated basis in order to statistically analyze Services usage. This license does not grant RapidPro the right to use your Content for any other commercial purposes.

    3.3 Limited License Grant to other RapidPro Users. By submitting Content to the Services, in cases where you display your Content for other Users to view or when you directly exchange or otherwise provide your Content to other Users as permitted by certain Services functionality and these Terms, you hereby grant to such Users of the Services a non-exclusive license to use, display, and reproduce such Content as necessary for such Users to use the relevant Services functionality or features.

    3.4. Copyright Claims (DMCA Notices). RapidPro responds to notices of alleged copyright infringement in accordance with the U.S. Digital Millennium Copyright Act (DMCA). If you believe that your work has been exploited in a way that constitutes copyright infringement, you may notify RapidPro for claims of copyright infringement.

    3.5. Other IP Claims. RapidPro respects the intellectual property rights of others, and we expect our users to do the same. If you believe a RapidPro user is infringing upon your intellectual property rights, you may report it to customer support at support@app.rapidpro.io. Claims of copyright infringement should follow the DMCA process outlined in these Terms, or any equivalent process available under local law.

    3.6. Required Rights. You shall be solely responsible for your own Content and the consequences of posting or publishing it. In connection with Content, you affirm, covenant, represent and warrant that you own, or have the necessary licenses, rights, consents, and permissions to use and to authorize RapidPro and RapidPro's Users to use the Content uploaded by you as necessary to exercise the licenses granted by you in this Section 3, and otherwise in the manner contemplated by RapidPro and these Terms.

    3.7. Content Representations. You shall be solely responsible for Content that: (i) may create a risk of harm, loss, physical or mental injury, emotional distress, death, disability, disfigurement, or physical or mental illness to you, to any other person, or to any animal; (ii) may create a risk of any other loss or damage to any person or property; and agree not to submit Content that: (iii) may constitute or contribute to a crime or tort; (iv) contains any information or content that we deem to be unlawful, harmful, abusive, racially or ethnically offensive, defamatory, infringing, invasive of personal privacy or publicity rights, harassing, humiliating to other people (publicly or otherwise), libelous, threatening, or otherwise objectionable; (v) contains any information or content that is illegal; (vi) contains any information or content that you do not have a right to make available under any law or under contractual or fiduciary relationships; or (vii) contains any information or content that you know is not correct and current. You agree that any Content that you post does not and will not violate third-party rights of any kind, including without limitation any intellectual property rights, rights of publicity and privacy. You further agree that you have the consent (written or otherwise) of each and every identifiable natural person in the Content to use such person's name or likeness in the manner contemplated by the Services and these Terms, and each such person has released you from any liability that may arise in relation to such use. TextIt reserves the right, but is not obligated, to reject and/or remove any Content that TextIt believes, in its sole discretion, violates these provisions.

    3.8. Content Disclaimer. You understand that when using the Services through an account in which Account Permissions are enabled, you may be exposed to Content from a variety of sources, and that TextIt is not responsible for the accuracy, usefulness, safety, or intellectual property rights of or relating to such Content. You further understand and acknowledge that you may be exposed to Content that is inaccurate, offensive, indecent or objectionable, and you agree to waive, and hereby do waive, any legal or equitable rights or remedies you have or may have against TextIt with respect thereto, and agree to indemnify and hold TextItt, its owners/operators, affiliates, and/or licensors, harmless to the fullest extent allowed by law regarding all matters related to your use of Content. TextIt does not endorse any Content or any opinion, recommendation or advice expressed therein or based upon such Content, and TextIt expressly disclaims any and all liability in connection with Content. If notified by a User or an owner of Content that allegedly does not conform to these Terms, TextIt may investigate the allegation and determine in good faith and in its sole discretion whether to remove the Content, which it reserves the right to do at any time. TextIt does not permit copyright infringing activities on the Services.

    3.9. Content Review. You acknowledge that, in order to ensure compliance with legal obligations, TextIt may be required to review certain content submitted to the Services to determine whether it is illegal or whether it violates these Terms (such as when unlawful content is reported to us). We may also modify, prevent access to, delete, or refuse to display content that we believe violates the law or these Terms. However, TextIt otherwise has no obligation to monitor or review any content submitted to the Services.

    4.0. Third Party Resources. TextIt may publish links in its Services to internet websites maintained by third parties. While TextIt vets third party services as we deem appropriate and integrous, TextIt does not formally represent that it has reviewed such third party websites and is not responsible for them or any content appearing on them. Trademarks displayed in conjunction with the Services are the property of their respective owners.

    4. TextIt IP

    4.1. TextIt IP. Neither these Terms nor your use of the Services grants you ownership in the Services or the content you access through the Services (other than your Content). Except as permitted by TextIt’s Brand and Trademark Use Policy, these Terms do not grant you any right to use TextIt’s trademarks or other brand elements.

    5. Account Management

    5.1. Account Credentials. In order to register as a User of the Services, an email address must be provided to serve as your User identification. You may provide your own email address, or an existing User may grant you access to the Services by providing your email address.

    In order to register as a User, you may also be required to create a password. It is of vital importance that you keep your password completely confidential, except from those with whom you intend to share your account. Anyone with access to your User identification and password will be able to view the confidential information that you are authorized to access and communicate with End-users as if that person were you. Additionally, anyone with access to your email account could reset your password on the Services in order to access your account on the Services as if that person were you.

    You are solely responsible for preventing disclosure of your password, as well as to prevent unauthorized access to your email account, and to notify us immediately if you feel that your security has been compromised. TextIt will not be liable for any losses caused by any unauthorized use of your account.

    5.2. Keep Your Account Credentials Accurate. TextIt occasionally sends notices to the email address registered with your account. You must keep your email address and, where applicable, your contact details and payment details associated with your account current and accurate. Accounts are controlled by the entity whose email address is registered with the account.

    5.3. Remember to Backup. You are responsible for maintaining, protecting, and making backups of your Content. To the extent permitted by applicable law, TextIt will not be liable for any extremely unlikely failure to store, or for loss or corruption of, your Content.

    5.4. Account Inactivity. TextIt may terminate your account and delete any content contained in it if there is no account activity (such as a log-in event or payment) for over 12 months. However, we will attempt to warn you by email or other means before terminating your account to provide you with an opportunity to log in to your account so that it remains active, or to recover Content contained therein.

    6. User Requirements


    6.1. Legal Status. If you are an individual, you may only use the Service if you have the power to form a contract with TextIt. None of the Services are intended for use by individuals less than 13 years old. If you are under 13 years old or do not have the power to form a contract with TextIt, you may not use the Services. We recommend that parents and guardians directly supervise any use of the Services by minors. If you are not an individual, you warrant that you are validly formed and existing under the laws of your jurisdiction of formation and that you have duly authorized your agent to bind you to these Terms.

    6.2. Embargoes. You may only use the Services if you are not barred under any applicable laws from doing so. If you are located in a country embargoed by United States or other applicable law from receiving the Services, or are on the U.S. Department of Commerce’s Denied Persons List or Entity List, or the U.S. Treasury Department’s list of Specially Designated Nationals, you are not permitted to purchase any paid Services from TextIt.

    7. Acceptable Uses


    7.1. Legal Compliance. You must use the Services in compliance with, and only as permitted by, applicable law.

    8. Restrictions to Use of Service

    You agree to not use the Services to:

    8.1. Upload, post, email, transmit or otherwise make available any content that is unlawful, harmful, threatening, abusive, harassing, tortuous, defamatory, vulgar, obscene, libelous, invasive of another's privacy, hateful, or racially, ethnically or otherwise objectionable;

    8.2. Harm minors in any way;

    8.3. Link, upload, post, email, transmit or otherwise make available any content that you do not have a right to make available under any law, or under any contractual or fiduciary relationships (such as inside information, proprietary and confidential information learned or disclosed as part of employment relationships or under nondisclosure agreements, or confidential medical information);

    8.4. Link, upload, post, email, transmit or otherwise make available any content that infringes any patent, trademark, trade secret, copyright or other intellectual property or other proprietary rights of any party without such party's authorization;

    8.5. Link, upload, post, email, transmit or otherwise make available any unsolicited or unauthorized advertising, promotional materials, "junk mail," "spam," "chain letters," "pyramid schemes," or any other form of solicitation;

    8.6. Link, upload, post, email, transmit or otherwise make available any material that contains software viruses or any other computer code, viruses, malware, bots, files or programs designed to interrupt, destroy or limit the functionality of any computer software or hardware or telecommunications equipment;

    8.7. Interfere with or disrupt the Services or servers or networks connected to the Services, or disobey any requirements, procedures, policies or regulations of networks connected to the Services; or

    8.8. Intentionally or unintentionally violate any applicable local, state, national or international law, or any regulations having the force of law.

    9. Changes and Updates


    9.1. Changes to Terms. TextIt may change these Terms at any time for a variety of reasons, such as to reflect changes in applicable law or updates to Services, and to account for new Services or functionality. Any changes will be posted to the location at which those terms appear. TextIt may also provide notification of changes on its blog or via email. Changes will be effective no sooner than the day they are publicly posted. In order for certain changes to become effective, applicable law may require TextIt to obtain your consent to such changes, or to provide you with sufficient advance notice of them. If you do not want to agree to any changes made to the terms for a Services, you should stop using that Services, because by continuing to use the Services you indicate your agreement to be bound by the updated terms.

    9.2. Changes to Services. TextIt constantly changes and improves the Services. TextIt may add or alter functionality from a Services at any time without prior notice. TextIt may also limit, suspend, or discontinue a Services or feature at its discretion. If TextIt discontinues a Services or feature, we will give you reasonable advance notice to provide you with an opportunity to export a copy of your Content from that Services. TextIt may remove content from the Services at any time in our sole discretion, although we will notify you before we do so if it materially impacts you and if practicable under the circumstances.

    10. Disclaimers and Limitations of Liability


    10.1. Disclaimers. While it is in TextIt’s interest to provide you with the best experience possible when using the Services, there are certain things we can not promise concerning them. We try to keep our online Services up, but they may be unavailable from time to time for various reasons. EXCEPT AS EXPRESSLY PROVIDED IN THESE TERMS AND TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE SERVICES ARE PROVIDED “AS IS” AND TEXTIT DOES NOT MAKE WARRANTIES OF ANY KIND, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT OR ANY REGARDING AVAILABILITY, RELIABILITY, OR ACCURACY OF THE SERVICES.

    10.2. Exclusion of Certain Liability. TO THE EXTENT PERMITTED BY APPLICABLE LAW, TEXTIT, ITS AFFILIATES, OFFICERS, EMPLOYEES, AGENTS, SUPPLIERS, AND LICENSORS WILL NOT BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, SPECIAL, INCIDENTAL, PUNITIVE, OR EXEMPLARY DAMAGES WHATSOEVER, INCLUDING DAMAGES FOR LOST PROFITS, LOSS OF USE, LOSS OF DATA, ARISING OUT OF OR IN CONNECTION WITH THE SERVICES AND THESE TERMS, AND WHETHER BASED ON CONTRACT, TORT, STRICT LIABILITY, OR ANY OTHER LEGAL THEORY, EVEN IF TextIt HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES AND EVEN IF A REMEDY FAILS OF ITS ESSENTIAL PURPOSE.

    10.3. Limitation of Liability.TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL TEXTIT, ITS AFFILIATES, AGENTS, DIRECTORS, EMPLOYEES, SUPPLIERS OR LICENSORS BE LIABLE FOR ANY DIRECT, INDIRECT, PUNITIVE, INCIDENTAL, SPECIAL, CONSEQUENTIAL OR EXEMPLARY DAMAGES, INCLUDING WITHOUT LIMITATION DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA OR OTHER INTANGIBLE LOSSES, THAT RESULT FROM THE USE OF, OR INABILITY TO USE, THIS SERVICES. UNDER NO CIRCUMSTANCES WILL TEXTIT BE RESPONSIBLE FOR ANY DAMAGE, LOSS OR INJURY RESULTING FROM HACKING, TAMPERING OR OTHER UNAUTHORIZED ACCESS OR USE OF THE SERVICES OR YOUR ACCOUNT OR THE INFORMATION CONTAINED THEREIN.

    TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, TEXTIT ASSUMES NO LIABILITY OR RESPONSIBILITY FOR ANY (I) ERRORS, MISTAKES, OR INACCURACIES OF CONTENT; (II) PERSONAL INJURY OR PROPERTY DAMAGE, OF ANY NATURE WHATSOEVER, RESULTING FROM YOUR ACCESS TO OR USE OF OUR SERVICES; (III) ANY UNAUTHORIZED ACCESS TO OR USE OF OUR SECURE SERVERS AND/OR ANY AND ALL PERSONAL INFORMATION STORED THEREIN; (IV) ANY INTERRUPTION OR CESSATION OF TRANSMISSION TO OR FROM THE SERVICES; (V) ANY BUGS, VIRUSES, TROJAN HORSES, OR THE LIKE THAT MAY BE TRANSMITTED TO OR THROUGH OUR SERVICES BY ANY THIRD PARTY; (VI) ANY ERRORS OR OMISSIONS IN ANY CONTENT OR FOR ANY LOSS OR DAMAGE INCURRED AS A RESULT OF THE USE OF ANY CONTENT (INCLUDING THIRD PARTY CONTENT) POSTED, EMAILED, TRANSMITTED, OR OTHERWISE MADE AVAILABLE THROUGH THE SERVICES; AND/OR (VII) USER-PROVIDED CONTENT OR THE DEFAMATORY, OFFENSIVE, OR ILLEGAL CONDUCT OF ANY THIRD PARTY. IN NO EVENT SHALL TEXTIT, ITS AFFILIATES, AGENTS, DIRECTORS, EMPLOYEES, SUPPLIERS, OR LICENSORS BE LIABLE TO YOU FOR ANY CLAIMS, PROCEEDINGS, LIABILITIES, OBLIGATIONS, DAMAGES, LOSSES OR COSTS IN AN AMOUNT EXCEEDING THE AMOUNT YOU PAID TO TEXTIT HEREUNDER OR $100.00, WHICHEVER IS GREATER.

    THIS LIMITATION OF LIABILITY SECTION APPLIES WHETHER THE ALLEGED LIABILITY IS BASED ON CONTRACT, TORT, NEGLIGENCE, STRICT LIABILITY, OR ANY OTHER BASIS, EVEN IF TEXTIT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE FOREGOING LIMITATION OF LIABILITY SHALL APPLY TO THE FULLEST EXTENT PERMITTED BY LAW IN THE APPLICABLE JURISDICTION.

    SOME STATES DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES OR THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE LIMITATIONS OR EXCLUSIONS MAY NOT APPLY TO YOU. THIS AGREEMENT GIVES YOU SPECIFIC LEGAL RIGHTS, AND YOU MAY ALSO HAVE OTHER RIGHTS WHICH VARY FROM STATE TO STATE. THE DISCLAIMERS, EXCLUSIONS, AND LIMITATIONS OF LIABILITY UNDER THIS AGREEMENT WILL NOT APPLY TO THE EXTENT PROHIBITED BY APPLICABLE LAW.

    The Services are controlled from facilities in the United States. Those who access or use the Services from other jurisdictions do so at their own volition and are entirely responsible for compliance with all applicable United States and local laws and regulations, including but not limited to export and import regulations. If you are a resident of a country embargoed by the United States, or are a foreign person or entity blocked or denied by the United States government, you assume sole responsibility for all legal repercussions resulting from your use of the Services.

    10.4. Businesses and 501(c) Organizations. If you are a business or 501(c) organization, you will indemnify and hold harmless TextIt and its affiliates, officers, agents, and employees from all liabilities, damages, and costs (including settlement costs and reasonable attorneys’ fees) arising out of a third party claim regarding or in connection with your use of the Services or a breach of these Terms, to the extent that such liabilities, damages and costs were caused by you.

    11. Other Terms

    11.1. Assignment. You may not assign these Terms without TextIt’s prior written consent, which may be withheld at TextIt’s sole discretion. TextIt may assign these Terms at any time without notice to you.

    11.2. Entire Agreement. These Terms constitute the entire agreement between you and TextIt, and they supersede any other prior or contemporaneous agreements, terms and conditions, written or oral concerning its subject matter. Any terms and conditions appearing on a purchase order or similar document issued by you do not apply to the Services, do not override or form a part of these Terms, and are void.

    11.3. Independent Contractors. The relationship between you and TextIt is that of independent contractors, and not legal partners, employees, or agents of each other.

    11.4. Interpretation. The use of the terms “includes”, “including”, “such as”, and similar terms, will be deemed not to limit what else might be included.

    11.5. No Waiver. A party’s failure or delay to enforce a provision under these Terms is not a waiver of its right to do so later.

    11.6. Severability. If any provision of these Terms is determined to be unenforceable by a court of competent jurisdiction, that provision will be severed and the remainder of terms will remain in full effect.

    11.7. Third Party Beneficiaries. There are no third party beneficiaries to these Terms.

    12. Security

    We host with Amazon Web Services, and all TextIt data is stored solely in the United States. Our servers are protected by firewalls, and all access to those servers is permitted only through encrypted channels that are FIPS-140-2 compliant, but no encryption is done on data at rest. While we employ industry-standard security practices, no system can perfectly guard against risks of intentional intrusion or inadvertent disclosure of information. When using the Services, information may be transmitted over mediums that are beyond our control. YOU HEREBY EXPRESSLY ASSUME THE SOLE RISK OF ANY UNAUTHORIZED DISCLOSURES, INTENTIONAL INTRUSION, OR ANY DELAY, FAILURE, INTERRUPTION OR CORRUPTION OF DATA OR OTHER INFORMATION TRANSMITTED IN CONNECTION WITH THE USE OF THIS SERVICES.

    13. Account ID and Password

    In order to register as a User of the Services, an email address must be provided to serve as your User identification. You may provide your own email address, or an existing User may grant you access to the Services by providing your email address.

    In order to register as a User, you may also be required to create a password. It is recommended that you keep your password completely confidential, except to individuals (colleagues) to which you grant access to your account. Anyone with access to your User identification and password will be able to view the confidential information that you are authorized to access and communicate with End-users as if that person were you. Additionally, anyone with access to your email account could reset your password on the Services in order to access your account on the Services as if that person were you.

    You are solely responsible for preventing disclosure of your password, as well as to prevent unauthorized access to your email account, and to notify us immediately if you feel that your security has been compromised. TextIt will not be liable for any losses caused by any unauthorized use of your account.

    14. Discontinuation and Suspension of the Services

    If your access to the Services was granted by another User, you may discontinue use of the Services at any time by sending a message requesting this change to the User(s) that granted your access to the Services. We are not responsible for canceling your use of the Services.

    If your access to the Services was not granted by another User, you may discontinue use of the Services at any time by deleting any and all payment instructions you have previously stored on the Services, deleting any and all projects you have created on the Services, and contacting us at support@app.rapidpro.io to request that your User account be deleted.

    TextIt may periodically schedule system downtime for maintenance and other purposes. Unplanned system outages, while extremely unlikely, may also occur. TextIt shall have no liability whatsoever for (i) the resulting unavailability of the Services, (ii) any resultant delay, misdelivery, or nondelivery of information caused by third-party acts, or (iii) any third-party acts or any other outages of web host providers or the Internet infrastructure and network external to the Services.

    15. Suspension or Termination of Access

    If we believe you have violated these Terms or otherwise abused the use of this Services, we reserve the right, at our sole discretion, to suspend or discontinue your access to and use of the Services.

    16. Communications

    You acknowledge that you are solely responsible for the use of electronic mail, Short Message Services (SMS), phone calls, and social media in connection with the Services. You represent and warrant that you have complied and will continue to comply with all applicable laws, statutes, ordinances, and regulations (including without limitation the CAN-SPAM Act of 2003 and any relevant data protection or privacy laws) in your use of the Services.

    17. Information and Services

    The Services may contain Third-Party Information and Services and involve integrations with or links to Third-Party Information and Services, as well as information and services created by Users for End-users. We do not control any such information and services and we are not responsible for their content or performance, or your use of or access to any such content. We do not operate, control or endorse any information, products or services provided by third parties, including without limitation Third-Party Information and Services. Any use of Third-Party Information and Services is strictly at your own risk including, but not limited to, any risks associated with destructive viruses. You are solely responsible for viewing and abiding by the terms and conditions of use and the privacy statements of the other services.

    WE DO NOT GUARANTEE ANY PRODUCTS OR SERVICES PROMOTED, OFFERED OR PROVIDED BY OR ON BEHALF OF THIRD PARTIES ON OR THROUGH THE SERVICES. WE ARE NOT RESPONSIBLE FOR TRANSACTIONS BETWEEN USERS AND THIRD PARTY PROVIDERS OF PRODUCTS OR SERVICES. WE SHALL NOT BE RESPONSIBLE OR LIABLE FOR ANY LOSS OR DAMAGE OF ANY SORT INCURRED AS THE RESULT OF ANY SUCH DEALINGS.

    18. No Warranty

    THE SERVICES IS PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS. USE OF THE SERVICES IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE SERVICES IS PROVIDED WITHOUT WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, OBTAINED BY YOU FROM TEXTIT OR THROUGH THE SERVICES WILL CREATE ANY WARRANTY NOT EXPRESSLY STATED HEREIN.

    TEXTIT DOES NOT GUARANTEE OR ASSUME RESPONSIBILITY FOR ANY PRODUCT OR SERVICES ADVERTISED OR OFFERED BY A THIRD PARTY THROUGH THE TEXTIT SERVICES OR ANY HYPERLINKED WEBSITE OR SERVICES, AND TEXTIT WILL NOT BE A PARTY TO OR IN ANY WAY MONITOR ANY TRANSACTION BETWEEN YOU AND THIRD-PARTY PROVIDERS OF PRODUCTS OR SERVICES.

    19. Indemnity

    19.1. General. You covenant and agree to indemnify, defend and hold harmless TextIt and its subsidiaries, affiliates, officers, directors, agents, managers, employees, contractors, partners and licensors from and against any and all claims, actions and demands (including all attorneys' fees, costs, debts, expenses, liabilities, damages and judgments arising from or related thereto) made by any third party related to or arising out of: (i) Third-Party Information or Services; (ii) User-created information or services, and content that you link, submit, post, transmit or otherwise make available through the Services or is otherwise submitted through your account; (iii) your use of or access to the Services; (iv) your connection to the Services; (v) your violation of these Terms, or your violation of any law or the rights of another, including without limitation any intellectual property rights or rights of privacy or publicity.

    19.2. Costs Incurred via Mobile Networks or Third-Party Services. In addition without limiting anything contained in this Section 19, TextIt is not responsible and shall not pay any costs relating to obtaining or maintaining telephones, or any credit for sending messages by means of a mobile network or other third-party services (e.g. "Twilio"). You and any user of your services are responsible for paying all of these costs and maintaining your telephones and any accounts with third-party services, and you agree to indemnify TextIt for any costs or fees associated with such services, accounts or telephone lines.

    In addition, TextIt is not responsible for reimbursing users for the use of account credits for mobile telephones or third-party services they connect to TextIt (e.g. "Twilio" or "Twitter") even if their account credit was used accidentally. You shall be responsible for payment of any such credits, and you agree to indemnify TextIt for any costs or fees associated with such accounts, servers or services.

    20. Digital Millennium Copyright Act

    20.1. Notice. If you are a copyright owner or an agent thereof and believe that any content being displayed or transmitted by any User through the Services infringes upon your copyrights, you may submit a notification to us pursuant to the Digital Millennium Copyright Act ("DMCA") by providing our Copyright Agent with the following information in writing (see 17 U.S.C 512(c)(3) for further details):

    20.2. Counter-Notice. If you believe that your content that was removed (or to which access was disabled) is not infringing, or that you have authorization from the copyright owner, the copyright owner's agent, or pursuant to the law to post and use the content, you may send a counter-notice containing the following information to the Copyright Agent:

    20.3. Effect of Counter Notice. If a counter-notice is received by our Copyright Agent, TextIt may send a copy of the counter-notice to the original complaining party informing that person that it may replace the removed content or cease disabling it in 10 business days. Unless the copyright owner files an action seeking a court order, the removed content may be replaced or access to it restored 10 or more business days after receipt of the counter-notice, at TextIt's sole discretion.

    UNDER FEDERAL LAW, IF YOU KNOWINGLY MISREPRESENT THAT ONLINE MATERIAL IS INFRINGING, YOU MAY BE SUBJECT TO CRIMINAL PROSECUTION FOR PERJURY AND CIVIL PENALTIES, INCLUDING MONETARY DAMAGES, COURT COSTS, AND ATTORNEYS' FEES.

    Please note that this procedure is exclusively for notifying TextIt and its affiliates that your copyrighted material has been infringed. The preceding requirements are intended to comply with TextIt's rights and obligations under the DMCA, including 17 U.S.C. section 512(c), but do not constitute legal advice. It may be advisable to contact an attorney regarding your rights and obligations under the DMCA and other applicable laws.

    In accordance with the DMCA and other applicable law, TextIt has adopted a policy of terminating, in appropriate circumstances, Users who are deemed to be repeat infringers. TextIt may also at its sole discretion limit access to the Services and/or terminate the accounts of any Users who infringe any intellectual property rights of others, whether or not there is any repeat infringement.

    21. Miscellaneous

    21.1. Arbitration. For any dispute with TextIt, you agree to first contact us at support@app.rapidpro.io and attempt to resolve the dispute with us informally. In the unlikely event that TextIt has not been able to resolve a dispute it has with you after attempting to do so informally, we each agree to resolve any claim, dispute, or controversy (excluding any TextIt claims for injunctive or other equitable relief) arising out of or in connection with or relating to these Terms, or the breach or alleged breach thereof (collectively, "Claims"), by binding arbitration by the American Arbitration Association ("AAA") under the Commercial Arbitration Rules and Supplementary Procedures for Consumer Related Disputes then in effect for the AAA, except as provided herein.

    21.2. International Use. If you choose to use the Services outside of the United States, you will be solely responsible for any violations of local laws and regulations resulting from such use, including those governing online conduct and Content transmissions.

    21.3. Notifications. TextIt may provide notifications, whether such notifications are required by law or are for marketing or other business related purposes, to you via email notice, written or hard copy notice, or through posting of such notice on our website, as determined by TextIt in our sole discretion. TextIt reserves the right to determine the form and means of providing notifications to our Users.

    If you have any questions concerning these Terms, or if you would like to contact us for any other reason, please email us at support@app.rapidpro.io.

    17.4 Can I use RapidPro for Voice (IVR)?

    Yes! You can build Flows that use IVR (or even mix SMS & Voice interactions). To get started, add a voice Channel (such as Twilio) and select "Phone Call' as your Flow medium in the "Create Flow" input box. 


    17.5 Can I use RapidPro in my country?

    RapidPro can be used in any country in the world. In certain countries, we make it easy to connect directly to carriers, but no matter where you are, you can use a local SIM card and an inexpensive Android phone to deploy your SMS application. Just download our free application on Google Play and your deployment will be live in a minutes.

    Have a look at our deployment guide for more details on the different deployment options.

    17.6 Can I use a dual SIM phone as an Android channel?

    RapidPro does not support switching between SIM cards on a dual SIM phones, as Android does not officially support dual SIM phones. The Nyaruka RapidPro Android application works with one phone number at a time, meaning that you're only able to use one SIM card per phone. If you want to use multiple SIM cards, you'll need to acquire multiple phones and install the Nyaruka RapidPro Android application on each. 

    You may connect multiple Android channels to your account. Some of our users connect an Android channel for each carrier in a country, though enabling bulk sending through Nexmo will allow you to send messages at the same rate across all carriers. 

    17.7 What's the difference between @contact and @step.contact?

    Note: Beginning October 1, 2017, references to @contact inside the "Send a message to someone else" action will be refer to the active contact in the run, not the recipient for the message. To reference the details for the recipient, instead start that contact in a flow and use the normal Send Message action with @contact.

    There are two ways to reference contacts and their fields within a workflow:

    @contact - references the contact receiving the message. In most cases, this is the active contact - the person whose responses are being handled by the workflow. When using the Send a Message to Someone Else action, @contact refers to the contact or group of contacts to which the message is being sent. 

    @step.contact - references the contact who sent the last message handled by the workflow. In most cases, this is also the active contact. When using the Send an SMS Response action@step.contact and @contact are the same contact. When using the Send a Message to Someone Else action, @step.contact refers to the contact who has reached the Send a Message to Someone Else action within the flow, thus triggering it to send. 

    Here's an example: 



    Since the message created by the Send a Message to Someone Else action is being sent to Edward, @contact.first_name will be replaced with Edward's first name. @step.contact.name and @step.contact.tel will be replaced with the name and phone number of the patient that just registered via the workflow containing the Send a Message to Someone Else action.

    For more information about variables, visit the Flow Variable Reference.

    17.8 Does RapidPro have an API?

    Yes! RapidPro has a robust API that would love to integrate with your service.  Have a look here

    Give it a test drive using our API Explorer



    17.9 How does RapidPro decide which Channel sends a message?

    Default Behavior



    If you have multiple channels of the same type connected to your account, the channel that the contact last initiated contact with will be prioritized. Contacts can be locked-in to a relationship with a specific channel (they'll only received messages from this channel) under three conditions:
    1. You have multiple channels of the same type connected to your account.
    2. The contact's address type priority corresponds with the channel type (e.g. phone number) that possess multiple channels (e.g. multiple phone numbers).
    3. The contact initiates contact through an incoming message.

    If the contact has never interacted with a channel linked to your account, RapidPro will prioritize the channel whose number has the largest prefix overlap (starts most similarly). 

    For example, if you have an Android Relayer Channel that is +12505661212 and one that is +2505551212, and you are sending an SMS to or calling +2505661231, RapidPro will use the +2505661212 Channel because it overlaps the most.

    In most cases, RapidPro is able to discern the carrier associated with a contact's phone number and prioritize channels based on carrier, though this depends on carrier behavior.

    Custom Behavior


    You can use the 'Set preferred channel' action to either assign or switch a contact's preferred channel without waiting for a response.