Ohana SMS is a Ruby on Rails application that allows people in need who lack access to the internet to find human services via SMS.
By default, Ohana SMS is able to query any Ohana API instance, but it can be modified to work with any API.
- Ruby version 2.5.1
- Rails version 5.2.0
- Testing Frameworks: MiniTest
You'll need a Ruby development environment on your computer, and a Twilio account.
Once your environment is ready to go, install the app:
git clone email@example.com:monfresh/ohana-sms.git && cd ohana-sms bin/setup
- Sign up for a free Twilio account.
- Once logged in to your Twilio account, create a project, then visit your Project Settings page.
- Copy your AuthToken and paste it in
Deploy to Heroku
Sign in, or sign up if you don't already have a Heroku account
Fill in the
App Namefield with your desired name, such as
Scroll down and click
Deploy for Free
Once your app is created, go to your computer's command line and run
figaro heroku:set -e production -a your_app_name, where
your_app_nameis the name you chose in step 3. This will configure your Heroku app with your secret Twilio information from your
Go to Twilio's Messaging Services and create a new service and select
Chat Bot/Interactive 2-Wayas the Use Case.
Inbound Settings, check the
Process Inbound Messagescheckbox and in the
Request URLfield, enter
https://ohana-sms-demo.herokuapp.com/locations/reply, making sure to replace
ohana-sms-demowith your actual Heroku app name. Then select
HTTP GETfrom the dropdown, and click
Save. It should look like this:
- Click on
Configurein the sidebar on the left, and buy a new Twilio number.
Test the app with your phone
Send an SMS to your Twilio number. You should be asked to enter a ZIP code:
Hi! Please enter a 5-digit ZIP code to get started.
94025. You should be offered to choose a category:
Please choose a category by entering its number: #1: Care, #2: Education...
1. You should get up to 5 results if there's a match:
Here are up to 5 locations that match your search. To get more details about a location, enter its number. #1: Rosener House Adult Day Services (Peninsula Volunteers)...
If there isn't a match, you should get:
Sorry, no results found. Please try again with a different ZIP code or category.
1. You should get more details about Rosener House (short description, phone, and address).
You can now send a different result number to see details about another location.
To reset the conversation, send
reset(it's not case-sensitive).
Configure the app to return your own data
If you haven't already deployed an instance of Ohana API with your own data, you'll need to do that first.
Then, all you'll need to do is set the
OHANA_API_ENDPOINT config var on
Heroku to your API's URL:
heroku config:set OHANA_API_ENDPOINT=https://your_ohana_api_url -a your_heroku_app_name
Customizing and translating the SMS messages
Currently, what can be translated are the greetings and instructions. The search results content, such as the Location names, or the short descriptions, are not translated. In order to translate search results, you would need to sign up for Google's paid translation service, but I have not integrated it in this app yet.
To translate the greetings and instructions, copy and paste the contents of
config/locales/en.yml into a new file in
config/locales with a filename
corresponding to the language's two-character code, and with a
extension. Then translate the text from English into your desired language.
config/locales/es.yml as an example. For more details, read the
Rails Internationalization Guide.
Once your translations are in place, create a new number in your Twilio account
that will be used for a particular language. Following the same instructions
as in Step 7 in the Deploy to Heroku section, add
the end of the Request URL. For example, to make your phone number use the
Spanish version of the app, your Request URL would look like this:
Running the tests
Run tests locally with this command:
To see the actual tests, browse through the test directory.
Created by Moncef Belyamani.
Inspired by and built upon the work of Mark Silverberg.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.