monfresh/ohana-sms

A Rails and Twilio app to find human services via SMS

Ohana SMS

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.

Stack Overview

• Ruby version 2.7.3
• Rails version 5.2.5
• Testing Frameworks: MiniTest

Local Installation

Prerequisites

You'll need a Ruby development environment on your computer, and a Twilio account.

Ruby

If you're on a Mac, the easiest way to get up and running is to run my Ruby on Mac script. On Linux, you'll need to install Build tools, Ruby with RVM, and Node.js.

Once your environment is ready to go, install the app:

git clone [email protected]:monfresh/ohana-sms.git && cd ohana-sms
bin/setup

Twilio

1. Sign up for a free Twilio account.
2. Once logged in to your Twilio account, create a project, then visit your Project Settings page.
3. Copy your AuthToken and paste it in config/application.yml next to twilio_auth_token.

Deploy to Heroku

1. Click this button:

2. Sign in, or sign up if you don't already have a Heroku account

3. Fill in the App Name field with your desired name, such as ohana-sms-demo

4. Scroll down and click Deploy for Free

5. 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_name is the name you chose in step 3. This will configure your Heroku app with your secret Twilio information from your application.yml.

6. Go to Twilio's Messaging Services and create a new service and select Chat Bot/Interactive 2-Way as the Use Case.

7. Under Inbound Settings, check the Process Inbound Messages checkbox and in the Request URL field, enter https://ohana-sms-demo.herokuapp.com/locations/reply, making sure to replace ohana-sms-demo with your actual Heroku app name. Then select HTTP GET from the dropdown, and click Save. It should look like this:

8. Click on Numbers under Configure in the sidebar on the left, and buy a new Twilio number.

Test the app with your phone

1. 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.
   

2. Send 94025. You should be offered to choose a category:

   Please choose a category by entering its number: #1: Care,
   #2: Education...
   

3. Send 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.
   

4. Send 1. You should get more details about Rosener House (short description, phone, and address).

5. You can now send a different result number to see details about another location.

6. 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 .yml extension. Then translate the text from English into your desired language. See 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 ?locale=[language_code] to 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:

https://ohana-sms-demo.herokuapp.com/locations/reply?locale=es

Running the tests

Run tests locally with this command:

script/test

To see the actual tests, browse through the test directory.

Credits

Created by Moncef Belyamani.

Inspired by and built upon the work of Mark Silverberg.

Public domain

This project is dedicated to the public domain. As stated in CONTRIBUTING:

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.

ohana-sms's Issues

Having trouble getting started

Hi, I've got an Ohana API system, and have forked and tried to set up ohana-sms to talk to a new twilio account, as described in the read me. I'm not having much luck.
The Ohana-SMS heroku app is always responding to me with HTTP/1.1 403 Forbidden ... "Twilio Request Validation Failed"

It's definitely possible I've done it wrong. But I've tried all the combinations of auth tokens and environments, pushing and using figaro to configure. Any tips? Is there a working instance I can compare against?
thanks!