Overview

In this tutorial, we will show you a quick way to receive inbound messages on your SMS-enabled Flowroute number. Flowroute handles an inbound SMS by making an HTTP POST request to the public URL that you have configured in your account. This article covers that process in detail.

Normally, a public URL would require web server and DNS changes which are extra steps in local development. In order to test Flowroute's inbound SMS quickly, we will use ngrok to create a tunnel to your localhost, and run a Python script that will let you receive an SMS on your Flowroute number.

Requirements Steps

Run ngrok

If you haven't downloaded and installed ngrok on your local machine, here's the link again. Open a command shell session and run ngrok on port 8080 to work with our Flask app settings.

ngrok http 8080

Additional ngrok Features

Anyone who can guess your tunnel URL can access your local web server unless you protect it with a password. We will not cover ngrok's auth configuration option which you can enable upon signup. Additionally, if you sign up for a paid ngrok account, you will get access to advanced features such as custom domain and TLS bindings.

Run example Python script

Copy and paste the following Python script into your text editor of choice. Make sure there aren't any extra tabs or spaces to avoid errors.

Example SMS Script in Python

from flask import Flask, request
import json

app = Flask(__name__)
app.debug = True


@app.route('/inboundsms', methods=['POST'])
def inboundsms():
    json_content = request.json
    print json.dumps(json_content)
    return "OK"

if __name__ == '__main__':
    app.run(
        host="0.0.0.0",
        port=int("8080")
    )

Save the above as inbound_sms.py. Next, open another terminal window or tab and run the file. 

python path_to_file/inbound_sms.py
You should now have a Python web server running on local port 8080.

Set SMS Callback field to your ngrok public URL

Note that we have registered our route as /inboundsms. Copy the forwarding URL from your ngrok session and the app route into the SMS Callback field of your Manage account.

Example SMS Callback

http://5eccb41a.ngrok.io/inboundsms

Access web interface

ngrok provides a real-time web UI where you can inspect all of the HTTP traffic running over your tunnels. You can access yours by pasting http://127.0.0.1:4040 into a web browser.

Text your Flowroute phone number

  1. Select a phone number on the Manage your DIDs tab.
  2. Send a test SMS from your mobile phone to the Flowroute number you have selected.
An example inbound SMS with a 200 OK response

Potential Errors

A typical error that you might encounter is a 404 Not Found. This usually occurs when the SMS Callback isn't set up correctly.

Tips

If the inboundsms endpoint is misbehaving, check that your Manage SMS Callback field has been set to the Forwarding URL followed by / and your defined Flask route. Also, you can click the Replay button on your ngrok web interface to replay the incoming request instead of sending another test message.

Additional Resources

Here are some additional reading materials that might be useful for you.