These instructions are from the open-source Code for America project Promptly, to allow a government user to easily send messages to clients or potential clients. It was written in December 2013.

For Users

Schedule a reminder

A reminder in Promptly is a specific text message sent to a group of phone numbers at a specific time in the future. To schedule a reminder:

Sign in and go to the dashboard
Click Schedule a Reminder
Select a text message or Create New Message
Select one or more recipient groups or Add New Group
Choose a send date and optionally change the send time
Click Schedule Reminder to preview the reminder
Click Schedule Reminder confirm

Create groups

Groups in Promptly are just lists of phone numbers with a name and description to help you remember. To create a group:

Sign in and go to the dashboard
Click Groups on the sidebar
Click New Group
Give the group a name and description to help you remember
Enter a list of phone numbers one phone number per line with NO spaces, like this:

Click Create Group

If you want to create a dynamic group that updates periodically from another datasource, either talk to your admin (if you have one) or check out the section below for developers.

Message style guide

Take a look at our best practices for government text messaging.

For Developers

For install/deploy instructions, check out the readme.

This section assumes you have Promptly up and running and have access to the rails console via rails c.

Importing groups

Currently the only way for Promptly to import groups is directly from custom tables within the application database. Yes, we recognize this is super lame. We apologize. Please make something better and send a pull request! So here’s how:

First, do some prep. Suppose you have a table called ‘rent_overdue’ in the application database that gets refreshed every day with people whose rent is overdue:

phone, rent_due_date
5105555555, 1/1/1999
4156666666, 5/27/1800
...

Make sure there’s a phone column with the phone number. All other columns are ignored.

Run the import rake task manually

# The import command is `rake "import_group[TABLE_NAME,GROUP_NAME]"`
# So, to import the 'rent_overdue' table as the 'delinquents' Group, run:

$ rake "import_group[rent_overdue,delinquents]"

Check the console to make sure everything ran smoothly. Then check Promptly web to double-check.

Automate import via cron jobs (Heroku doesn’t support cron jobs, so read this article instead

Edit config/scheduler.rb

# See the whenever docs for details: https://github.com/javan/whenever
every 1.day, :at => '10:00 am' do
    rake "import_group[rent_overdue,delinquents]", :environment => 'production'

    # Feel free to add more...
    rake "import_group[rent_due_soon,pay_now]", :environment => 'production'
end

Log into the Rails console with $ rails c
And update the crontab with $ whenever --update

And now the import task will run automatically. The task itself basically just clears all recipients from the group and adds them again from scratch.

For HSA

CalFresh discontinuation text messages

English

CalFresh (Food Stamps): Your CalFresh benefits may stop at the end of this month. Questions? Call (415) 944-4301.

Spanish

CalFresh (Estampillas de Comida): Sus beneficios de CalFresh podrìan descontinuarse al final de este mes. ¿Preguntas? Llame al (415) 944-4301.

Chinese

糧食券: 你的糧食券福利可能會在本月底停止. 有問題嗎？請致電 (415) 944-4301.

Russian

CalFresh (Food Stamps): В конце месяца выплата вашего пособия CalFresh может быть остановлена. Если у вас есть вопросы, позвоните 415-944-4301.

deleted: этого – “this” (“the” is implied)
deleted: по номеру – “the number”

Vietnamese

CalFresh (Phiếu Thực phẩm): Phúc lợi CalFresh của quý vị có thể sẽ bị ngưng vào cuối tháng này. Nếu quý vị có thắc mắc thì xin gọi về (415) 944-4301.

Tagalog

CalFresh (Food Stamps): Ang inyong mga benepisyo ng CalFresh ay maaaring tumigil sa katapusan ng buwang ito. May mga katanungan ba kayo? Tumawag sa (415) 944-4301.

Privacy and security

Text messages are not a secure means of communication. That’s why clients must explicitly request text messages by filling out the Text and Email Consent Form.

Future Text Message Ideas from HSA Employees

You are approved for ________.
Your new driver license is ready.
You are eligible to enroll in Social Security benefits.
[Street Name] will be closed from [date] to [date].
Maximum benefit allotments have decreased to ___________.
Consider Medi-Cal for your health care needs.
Visit our new lobby.
Apply for WIC here: ___________.

Best Practices for Texting by Government (click here)

CIS data

CIS is a county-specific data extract from the CalWIN data system that 18 CA counties use to manage various public benefit programs. We initially built and deployed Promptly for the San Francisco Human Service Agency to notify CalFresh clients when they were at risk of losing benefits (see here for more info). We used CIS data to import these client groups into Promptly. We’ve published the specific SQL queries here just in case other IT staff within Human Service Agencies want to implement a similar program.

CalWIN

Where do I save text message and/or email consent in CalWIN?

There are two new case special indicators in CalWIN to mark clients who have signed up for text messaging and email communication. To add an indicator to a case, go to the Display Demographic Summary Tab > Collect Individual Demographics Detail, and add those that apply:

Text Messages OK
Email Ok

Where should I enter the client’s cell phone number in CalWIN?

In the Messages field on the Case Summary Details window. The Demographics window will not work.

Do I have to run EDBC?

No. You can just click save.

When do I provide the client with the agreement form?

For now, just during face-to-face intake and RRRs. Not over the phone.

Should I collect information even if the case isn’t immediately approved?

Yes, please collect this info at intake whether or not the case is immediately approved.

Do clients need to provide both text and email consent?

No. Clients can choose to receive either, both, or neither. They should also be informed that HSA is only sending text messages at this time.

FAQ

How to start?

Open Chrome or Firefox preferably rather than Internet Explorer. On an HSA computer in the address bar of your web browser type “promptlytest/” Login with your username and password. If you do not have one, then request it from HSA IT.

What if people text back?

We can read what they wrote and they will receive an automatic reply. If people text back STOP then they will be dropped automatically from the program. You read what people text.

How do clients start receiving these text messages?

Clients have to sign a form in order to opt into this program.

Can we enter all the clients for the coming year so that at the end of the month they will automatically receive messages?

No, not in the current state of Promptly, but yes, we could create this.

Can we contact all existing CalFresh clients receiving messages about signing up for Medi-Cal?

Yes.

Will HSA IT create the groups for us?

Yes, they will set up the queries.

So, how does that work?

If you want to send one text message to a group people, say for a one off reason, then you can ask HSA IT for a particular query. For ongoing, periodic texts, however, then a query needs to be set up that runs every night, updating the system, that allows for new clients’ information to be automatically imported and they will be texted automatically when about to be discontinued.

Are there capacity issues, like can we run a query for 15,000 people or text that many?

No capacity issues, you can query and text as many as you like as long as they’re in CalWIN.

Do we know how many contact the call center?

Yes, you can see when they call and how many. A report can be generated on this., however, it resides with a third-party called “Twilio.” Clients call this number that they receive when texted. The number will not change. They may decide to call this number rather than the call center directly in the future. So getting accurate data on total calls to the call center may require accessing this data.

How much does it cost HSA and clients to send these messages and maintain an account with Twilio?

This depends on several factors, including how many people are texted, how many call and text back, and the monthly charges from Twilio.

Promptly is a “free service,” meaning HSA offers this communication option to clients for free. However, text messages from Promptly are just like normal text messages, meaning clients may have to pay depending on their service provider and text message plan. Typically in the U.S. text messages will not cost more than $0.10.

For HSA, Promptly is not free because it must pay Twilio for three types of costs: 1. Phone numbers cost $1 per month per number. There are currently two phone numbers for Promptly. 2. Outbound/inbound text messages cost $0.03 to $0.04 per message. 3. Incoming calls cost $0.03 per minute (technically $0.01/minute for the incoming leg + $0.02/minute for the outgoing leg via call forwarding)

A thought experiment for a month of Promptly in the future, assuming HSA sends 10,000 messages, 25% of clients text back, and 50% of clients call with an average call time of five minutes:

$2 per month for the phone numbers = $2
+ 10,000 outbound messages * 3/4c = $75
+ (2,500 incoming messages from clients + 2,500 automatic response outbound messages) * 3/4c = $38
+ 5,000 incoming calls * 5 minutes * 3c per minute = $750
= $865 total costs

Someone needs to make sure there is always enough money in our Twilio account to ensure that Promptly can send messages and forward incoming calls.

Check out the Twilio pricing page and this article on Twilio call forwarding for the details.

Can we assign a different number to each community of people who speak a different language?

Yes

Can we embed a link within a text message so people can click it?

Can we do sub-groups, like all the CalWORKS clients or all the CalFresh clients?

No, not now, but we may be able to do this moving forward.

Do we put dashes between the number?

No, just write it out.

What if someone puts 12/1/11 in the past?

It would send it on 12/1/13, but this feature is going to be taken out.

How long does it take to text people?

If you send 100 messages or more then it may take one second to send each one. During tests it takes about a minute or less to actually receive it.

Does Promptly cost clients money?

Sometimes. While Promptly is a free HSA service, it may cost clients a few cents to receive each text message, depending on their service plan.

Does Promptly replace mailed NOAs?

No. Clients will receive all regular mailed NOAs whether or not they choose to receive text messages.

Who, exactly, will get text messages?

For now, we will be text messaging clients who are about to be discontinued from aid. We plan to send emails and other types of reminders in the future.

What languages are available?

English and Spanish right now but we’re working hard to add Chinese, Vietnamese, Tagalog, and Russian. Please collect cell phone numbers from all clients, regardless of their primary language.

What if clients refuse to participate?

No problem! This is an optional service. Please don’t pressure them.

How can clients unsubscribe?

Clients can unsubscribe by replying STOP to any text message. Alternatively, you can unsubscribe a client on their behalf by removing the ‘Text messages OK’ special indicator in CalWIN.

What phone number will text messages come from?

HSA clients will only receive text messages from (415) 944-4301.

What if a client’s phone is disconnected?

The client will stop receiving text messages. If a cell phone is disconnected, just remove the number from the Messages field on the Case Summary Details window and we won’t send anymore messages.