Skip to content
Getting started with a Finatra API for a Twilio application
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
project
src/main/g8
.gitignore
README.markdown
build.sbt

README.markdown

Hello Finatra

A Giter8 template for a Hello World Finatra application.

Using this template

Install

Requirements:

In a terminal window type:

sbt new robinske/hello-finatra.g8

You can name your project anything you like, but avoid using numbers or dashes.

image

Running 'Hello World'

Navigate into your directory, in my case:

cd finatra_demo

Then run using SBT:

sbt run

Finatra will start on port 8888:

image

Hooray!

Incorporating Twilio

We can use our Finatra API to respond to incoming text messages using Twilio. Twilio provides APIs for communications, including SMS, Voice, and Authentication.

In this Quickstart, you will learn how to:

  1. Sign up for Twilio and get your first SMS-enabled Twilio phone number
  2. Set up your development environment to send and receive messages
  3. Receive inbound text messages
  4. Reply to incoming messages with an SMS

Sign up for Twilio and get a phone number

If you already have a Twilio account and an SMS-enabled Twilio phone number, you’re all set here! Feel free to jump to the next step.

Before you can respond to an SMS with Scala, you'll need to sign up for a Twilio account or sign into your existing account and purchase an SMS-capable phone number.

If you don't currently own a Twilio phone number with SMS functionality, you'll need to purchase one. After navigating to the Buy a Number page, check the "SMS" box and click "Search."

image

You’ll then see a list of available phone numbers and their capabilities. Find a number that suits your fancy and click "Buy" to add it to your account.

image

Now that you have a Twilio account and a programmable phone number, you can start writing some code!

Allow Twilio to talk to your application

We’re about to build a small Finatra application to receive incoming messages. Before we do that, we need to make sure that Twilio can reach your application.

Most Twilio services use webhooks to communicate with your application. When Twilio receives an SMS, for example, it reaches out to a URL in your application for instructions on how to handle the message.

When you’re working on your Finatra application in your development environment, your app is only reachable by other programs on your computer, so Twilio won’t be able to talk to it. We need to solve this problem by making your application accessible over the internet.

While there are a lot of ways to do this, like deploying your application to Heroku or AWS, you'll probably want a less laborious way to test your Twilio application. For a lightweight way to make your app available on the internet, we recommend a tool called Ngrok. Once started, Ngrok provides a unique URL on the ngrok.io domain which forwards incoming requests to your local development environment.

image

If you don’t already use Ngrok, head over to their download page and grab the appropriate binary for your operating system. Once downloaded, unzip the package.

If you're working on a Mac or Linux, you're all set. If you're on Windows, follow our guide on how to install and configure ngrok on Windows. For more info on ngrok, including some great tips and tricks, check out this in-depth blog post.

Once downloaded, start that Hello World application we made previously:

sbt run

Your local application must be running locally for Ngrok to do its magic.

Then open a new terminal tab or window and start Ngrok with this command:

./ngrok http 8888

You should see output similar to this:

image

Copy your public URL from this output and paste it into your browser. You should see your Finatra application's "Hello, World!" message.

Receive and reply to inbound SMS messages with Finatra

When someone sends an SMS to your Twilio phone number, Twilio makes an HTTP request to your server asking for instructions on what to do next. Once you receive the request, you can tell Twilio to reply with an SMS, kick off a phone call, store details about the SMS in your database, or trigger something else entirely - it’s all up to you!

For this Quickstart, we’ll have our Finatra app reply to incoming SMS messages with a thank you to the sender. Open up Server.scala again and update the code in the HelloController class to look like this code sample:

class HelloController extends Controller {

  post("/sms") { request: Request =>
    val twiml =
      <Response>
        <Message>
          Hi, thanks for sending me a message!
        </Message>
      </Response>

    response.ok
      .contentType("text/xml")
      .body(twiml)
  }

}

When your phone number receives an incoming message, Twilio will send an HTTP request to your server. This code shows how your server should respond to reply with a text message.

Save this file and restart your app with

sbt run

Double-check that Ngrok is still running on your localhost port. Now Twilio will be able to find your application - but first, we need to tell Twilio where to look.

Configure your webhook URL

For Twilio to know where to look, you need to configure your Twilio phone number to call your webhook URL whenever a new message comes in.

  1. Log into Twilio.com and go to the Console's Numbers page.
  2. Click on your SMS-enabled phone number.
  3. Find the Messaging section. The default “CONFIGURE WITH” is what you’ll need: "Webhooks/TwiML".
  4. In the “A MESSAGE COMES IN” section, select "Webhook" and paste in the URL you want to use.

image

Save your changes - you're ready!

Test your application

As long as your localhost and the Ngrok servers are up and running, we’re ready for the fun part - testing our new Finatra application!

Send a text message from your mobile phone to your Twilio phone number. You should see an HTTP request in your Ngrok console. Your Finatra app will process the text message, and you’ll get your response back as an SMS.

Where to next?

Now that you know the basics of receiving and responding to SMS text messages with Scala, you might want to check out these resources.

Credits

Forked from the Scala Center Hello World Giter8 template.

Template license

Written in 2017 by the Scala Center [other author/contributor lines as appropriate]

To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this template to the public domain worldwide. This template is distributed without any warranty. See http://creativecommons.org/publicdomain/zero/1.0/.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.