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.
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
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:
5105555555 4156666666 6267777777 ...
- 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.
Take a look at our best practices for government text messaging.
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
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.
CalFresh (Food Stamps): Your CalFresh benefits may stop at the end of this month. Questions? Call (415) 944-4301.
CalFresh (Estampillas de Comida): Sus beneficios de CalFresh podrìan descontinuarse al final de este mes. ¿Preguntas? Llame al (415) 944-4301.
糧食券: 你的糧食券福利可能會在本月底停止. 有問題嗎？請致電 (415) 944-4301.
CalFresh (Food Stamps): В конце месяца выплата вашего пособия CalFresh может быть остановлена. Если у вас есть вопросы, позвоните 415-944-4301.
- deleted: этого – “this” (“the” is implied)
- deleted: по номеру – “the number”
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.
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.
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.
- 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 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.
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
In the Messages field on the Case Summary Details window. The Demographics window will not work.
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.
Yes, please collect this info at intake whether or not the case is immediately approved.
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.
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.
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.
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.
Yes, they will set up the queries.
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.
No capacity issues, you can query and text as many as you like as long as they’re in CalWIN.
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.
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.
No, not now, but we may be able to do this moving forward.
No, just write it out.
It would send it on 12/1/13, but this feature is going to be taken out.
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.
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.
No. Clients will receive all regular mailed NOAs whether or not they choose to receive 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.
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.
No problem! This is an optional service. Please don’t pressure them.
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.
HSA clients will only receive text messages from (415) 944-4301.
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.