Flowroute is excited to announce the launch of Messaging API v2.1 (MMS) that will let you send multimedia files from your Flowroute long code or toll-free number. This quickstart is meant to help you accomplish the following:
- Programmatically upload a local media file to a previously configured Amazon S3 bucket
- Generate a unique S3 URL for your media
- Send the S3 file from your Flowroute number via the MMS API.
Requirements
Need help?
For Flowroute-specific requirements, follow steps 1 (Sign up and retrieve your API credentials) and 2 (Purchase a phone number).
Set Up Your Amazon S3 Bucket
To get started with Amazon S3, follow Getting Started with Amazon Simple Storage Service. Make sure that your S3 bucket is publicly accessible.
Set Your Environment Variables
For this application, you will need four environment variables:
Start a shell session and export the following environment variables:
export AWS_ACCESS_KEY="<your_AWS_access_key>"
export AWS_SECRET_KEY="<your_AWS_secret_key>"
export FR_ACCESS_KEY="<your_Flowroute_access_key>"
export FR_SECRET_KEY="<your_Flowroute_secrety_key>"
Environment Variables
There are various ways to set your environment variables on startup for reuse in later sessions without having to type them in again. For instance, you can export them in your bashrc file. Please consult your administrator, OS documentation, or Digital Ocean's How To Read and Set Environmental and Shell Variables on a Linux VPS.
Send your first MMS
Create your Python script
First, open up your preferred text editor and import all the libraries that you will be using:
import boto
import os
import uuid
import requests
import json
from boto.s3.key import Key
Python Libraries
If you do not have any of the above libraries (e.g., Import Error: No module named boto), run the following:
pip install <library_name>
Next, assign the following S3-specific variables:
- S3 bucket name
- S3 bucket region
- Local media file path (of the file that you will be sending)
Amazon S3 Regions
Please refer to the S3 Regions list in the AWS Regions and Endpoints reference page for up-to-date information on your specific S3 region.
bucket_name = "<your_bucket_name>"
bucket_region = "<your_bucket_region>"
filepath = "/path-to-file/example-file.png"
Define your MMS information.
from_number = "<your_flowroute_number>"
to_number = "<your_mobile_number>"
msg_body = "sample message"
Import your previously set AWS and Flowroute environment variables into Python variables.
AWS_ACCESS_KEY = os.environ['AWS_ACCESS_KEY']
AWS_SECRET_KEY = os.environ['AWS_SECRET_KEY']
FR_ACCESS_KEY = os.environ['FR_ACCESS_KEY']
FR_SECRET_KEY= os.environ['FR_SECRET_KEY']
Once those are set, declare your S3 connection.
conn = boto.s3.connect_to_region(bucket_region,
aws_access_key_id=AWS_ACCESS_KEY,
aws_secret_access_key=AWS_SECRET_KEY
)
Then, create an object called bucket using the previous connection object. Also, make sure to set validate to False as you will be dealing with objects within the S3 bucket instead of the bucket itself.
bucket = conn.get_bucket(bucket_name, validate=False)
Next, use the Python uuid library to create a random string for use as a filename within S3. This is just a simple way to generate a random string.
uid = uuid.uuid4()
hex32 = uid.hex
Now extract the file extension from the file to be uploaded and recreate a filename using the random string.
filename = filepath.split('/')[-1]
fileext = filename.split('.')[-1]
upload_fn = hex32 + "." + fileext
Next, upload the file to your S3 bucket using the filename that was just generated. Note that you will also be setting the policy to public-read for the uploaded file.
k = Key(bucket)
k.key = upload_fn
k.set_contents_from_filename(filepath, policy='public-read')
Your uploaded file will now be publicly accessible on S3. Now we will derive the URL to pass to the Flowroute Messaging API.
s3_url = "https://s3-" + bucket_region + ".amazonaws.com/" + bucket_name + "/" + upload_fn
Lastly, construct your JSON POST to the Flowroute API using the S3 media URL, the MMS information, and the Flowroute environment variables you have previously set.
mmsdata = {"from": from_number, "to": to_number, "body": msg_body, "media_urls":[s3_url]}
fr_auth = (FR_ACCESS_KEY, FR_SECRET_KEY)
base = "https://api.flowroute.com/v2.1/messages"
headers = {"Content-Type": "application/vnd.api+json"}
r = requests.post(base, auth=fr_auth, json=mmsdata, headers=headers)
print r.status_code
Save the file as send_mms.py and run the following:
python send_mms.py
Voila! You have just uploaded your specified local file to your newly created S3 bucket, and sent that file in an MMS using your Flowroute number.
Interested in just getting this up?
Here's the code:
send_mms.py
#import libraries
import boto
import os
import uuid
import requests
import json
from boto.s3.key import Key
#S3 bucket and media file info
bucket_name = "<your_s3_bucket>"
bucket_region = "<your_s3_region>"
filepath = "/Users/username/<file_path>/<filename>.png"
#Flowroute MMS info
fromnum = "<your_flowroute_number>"
tonum = "<your_mobile_number>"
msg_body = "sample message"
#Import environment variables
AWS_ACCESS_KEY = os.environ['AWS_ACCESS_KEY']
AWS_SECRET_KEY = os.environ['AWS_SECRET_KEY']
FR_ACCESS_KEY = os.environ['FR_ACCESS_KEY']
FR_SECRET_KEY = os.environ['FR_SECRET_KEY']
#Declare S3 connection to bucket
conn = boto.s3.connect_to_region(bucket_region,
aws_access_key_id=AWS_ACCESS_KEY,
aws_secret_access_key=AWS_SECRET_KEY
)
bucket = conn.get_bucket(bucket_name, validate=False)
#Generate random string
uid = uuid.uuid4()
hex32 = uid.hex
#Extract media file extension and recreate filename
filename = filepath.split('/')[-1]
fileext = filename.split('.')[-1]
upload_fn = hex32 + "." + fileext
#Upload file to S3 bucket
k = Key(bucket)
k.key = upload_fn
k.set_contents_from_filename(filepath, policy='public-read')
s3_url = "https://s3-" + bucket_region + ".amazonaws.com/" + bucket_name + "/" + upload_fn
#Send MMS
mmsdata = {"from": fromnum, "to": tonum, "body": msg_body, "media_urls":[s3_url], "is_mms": "true"}
fr_auth = (FR_ACCESS_KEY, FR_SECRET_KEY)
base = "https://api.flowroute.com/v2.1/messages"
headers = {"Content-Type": "application/vnd.api+json"}
r = requests.post(base, auth=fr_auth, json=mmsdata, headers=headers)