This week I used a gem to integrate with the Twilio API for SMS text messages, and it was really easy to implement. Once I knew what to do, it only took a few minutes to get it up and running. This would be a great API for a first-timer, so if you've wanted to use an API but wasn't sure which one to pick or how to do it, read on!
1. Create Account & Obtain Phone Number
Visit Twilio's site and create a trial account. Follow the instructions to verify your account. Twilio will present you with several phone numbers to choose from, pick a number you like and click "Get Started."
2. Get your Key & Auth Token
Once you have a Twilio phone number, click on Go To Your Account where you'll see your account dashboard. Right in the middle of the page, you should see your Account SID and Auth Token. The Auth Token might be hidden, if you click on the lock icon, it will display. Keep this page open, you're going to come back to these in a few minutes.
3. Add Gem
Add Twilio's Ruby gem to your gemfile, and run bundler to install.
4. Write Your Test
Here is a screen shot of what my model test for sending a text looks like, but of course yours will look different because it will be specific to your code and the way your project is configured. I've mainly included it here because I've found most tutorials completely ignore testing, and if nothing else I wanted to reinforce that you should be testing first. I'm using VCR so I don't hit the Twilio API each time I run my tests, and Factory Girl to build my patient objects. Run your test, and follow the failures to guide the implementation. Below is the code I had to write to get this gem to work in my project.
Decide what action you want to trigger the text message. In my project, it was when a new patient was created and saved to the database. My create action is doing some other things, but you can see that on line 31, I'm just calling a method I defined over in the model. Very simple!
Finally, here are the guts that really make this thing work. I'm going to show you my code, but check out the Twilio documentation as well. The client_number is the number you want to send your text messages to. During development, I hard coded my own phone number, but I've added a comment with some code I would use if I was, for example, sending a text to a patient when they were created. The twilio_phone_number is the number they gave me, the number your text messages will be sent from.
The next step is to add the SID and Auth Token. You can hardcode these as well, and if you want to try that first just to get things working, go for it. Hardcoding them is ultimately a security issue, as someone could get a hold of them (especially if you're pushing your code to a public repo on Github). To keep them private, create a file named ".env" in the root of your project's directory and add them there. Add .env to your .gitignore file, that way this other file won't get pushed up to Github - which would totally defeat the purpose of saving them to a hidden file.
With the SID and Token stored safely in variables tucked away, we just have to point to them with the environment variables in our model.
7. Try it out!
With all this code in place, make sure your test is passing and that texts are going out. Hopefully things will go smoothly as they did for me, if not, please leave a question and I'll try to help you out.
This is my first tutorial, I hope you found it useful. Please let me know if I missed any steps or didn't explain anything clearly. Shout out to Erin for helping me get my project set up with Twilio!