Flowroute will POST any inbound MMS that you receive on your Flowroute numbers to a webhook that you manage. In this guide, we will use a webhook to handle a POST message triggered by an inbound MMS, save the media file included in the MMS temporarily and upload it to your Amazon S3 bucket, and reply to the MMS with a text message. We will be using ngrok and a Flask-based application to accomplish the following:

  1. Receive an inbound MMS notification from Flowroute at a defined callback URL
  2. Temporarily download the media file by extracting the url from the JSON body
  3. Upload the file to a specified S3 bucket using the notification timestamp and the telephone number of the sender
  4. Delete the temporary file and reply to the MMS sender with an SMS from the Flowroute number receiving the MMS


Need help?

For Flowroute-specific requirements, follow steps 1 (Sign up and retrieve your API credentials) and 2 (Purchase a phone number) of the Send Your First SMS article.

Run example Flask app

Copy and paste the following Python script into your text editor of choice. Please note that this requires the same environment variables as the ones in Send Your First MMS.

import boto
from boto.s3.key import Key
import os
import urllib
import requests
import json
import time
from flask import Flask, request

#S3 bucket info including an optional subdirectory for your file upload
bucket_name = "<your_S3_bucket>"
upload_path = '/<your_upload_path>/'
bucket_region = "<your_S3_region>"

#Flowroute API endpoint and reply SMS to be sent
fr_api_url = "https://api.flowroute.com/v2.1/messages"
reply_message = 'Thanks for the picture!'

app = Flask(__name__)
app.debug = True

@app.route('/inboundmms', methods=['POST'])
def inboundmms():
    bucket = gets3bucket(bucket_name, bucket_region)

    #extract attributes from POSTed JSON of inbound MMS
    json_content = request.json
    reply_to = json_content['data']['attributes']['from']
    reply_from = json_content['data']['attributes']['to']
    media_url = json_content['included'][0]['attributes']['url']

    #add a timestamp to prevent overwriting files
    rcv_time = str(int(time.time()))
    filename = rcv_time + "_" + reply_to

    #temporarily download the media to your local file system
    tmpfile = '/tmp/' + filename
    urllib.urlretrieve(media_url, tmpfile)
    #upload the media to your specified S3 bucket
    uploadtos3(bucket, tmpfile, filename)

    #remove file from local file system

    #send a reply SMS from your Flowroute number
    sendreply(reply_to, reply_from)

    return '0'

#create S3 connection
def gets3bucket(bucket_name, bucket_region):

    AWS_ACCESS_KEY = os.environ['AWS_ACCESS_KEY']
    AWS_SECRET_KEY = os.environ['AWS_SECRET_KEY']

    conn = boto.s3.connect_to_region(bucket_region,
    bucket = conn.get_bucket(bucket_name, validate=False)

    return bucket

#upload file to S3
def uploadtos3(bucket, path, key):

    k = Key(bucket)
    k.key = upload_path + key

    return None

#send a reply SMS using your Flowroute credentials 
def sendreply(reply_to, reply_from):

    FR_ACCESS_KEY = os.environ['FR_ACCESS_KEY']
    FR_SECRET_KEY = os.environ['FR_SECRET_KEY']


    replyheaders = {'Content-Type': 'application/vnd.api+json'}
    replydata = { 'from': reply_from, 'to': reply_to, 'body': reply_message }
    r = requests.post(fr_api_url, auth=auth, json=replydata, headers=replyheaders)
    print r.status_code
    return None

if __name__ == '__main__':


Save the file as receive_mms.py and run the following:

python receive_mms.py

Set up ngrok and establish a secure tunnel

If you don't have ngrok installed, you can download it here. In your shell session, open another tab or window and run ngrok.

ngrok http 8080

Configure your callback URL

Take note of the forwarding URL from your ngrok session and the app route, inboundmms. Log in to your Flowroute Manage account and set your MMS Callback like so: https://<ngrok_forwarding_url>/inboundmms.

Text your Flowroute phone number

  1. Select a phone number on the Manage your DIDs tab.
  2. Send a test MMS from your mobile phone to the Flowroute number you have selected. Please note that Flowroute's maximum attachment file size is 750kB. Check out the Messaging API v2.1 reference page to learn which content types are supported.

Related Articles