For the last century, humanity has maintained that “a picture is worth a thousand words”. While photos may have changed a lot, morphing from paper to pixels, that old adage is truer than ever in the digital age. Whether happy or heartbreaking, the millions of pictures we take every day help us tell our stories like no other medium can.
The team at Twilio has been working very hard to bring the power of pictures to our messaging platform. And today, were are thrilled to announce that Picture Messaging has arrived for all US and Canadian numbers, giving you the power to speak a thousand words in a single message.
With this new messaging capability, your apps can send concert tickets directly to a user’s mobile phone, accept photos to accompany an insurance claim, or just share that incredible animated GIF you saw on Tumblr with your friends. Words are inadequate to describe our excitement to see how you, our wickedly clever developer community, will put this new capability to use.
To help you get started using your new super power, we’ll explore the basic usage of Twilio MMS in a variety of programming languages and web frameworks. Using the chooser below, select the programming language and framework combination that looks most interesting to you. We’ll show you how to get started using that set of tools to send and receive picture messages.
Sound good? Then pick a language below and let’s get started! ↘
☰ Setting Up
1. Setting Up
a. Sign up for a Twilio Account
b. Buy an MMS-enabled phone number
c. Set up our project
2. Sending MMS Messages with the REST API
3. Receiving MMS Messages in Your Application
a. Implement a webhook route that returns TwiML
b. Get a public URL for your app with ngrok
c. Configure your Twilio number
4. Wrapping Up
Node.js | Express
Python | Flask
C# | .NET MVC
PHP
Java | Servlets
Ruby | Sinatra
Setting Up
Before we can start sending and receiving MMS messages, we have a little bit of work to do. We need to sign up for a Twilio account for starters, and then obtain an MMS-enabled phone number to use with our application. Let’s get that taken care of so we can move on to the code.
Sign up for a Twilio account
If you don’t already have one, sign up for a Twilio account now. During the signup process, you’ll be prompted to search for and buy a number. You can go ahead and just take the default number for now.
After you take the default number, you might want to play around with it and send yourself a few text messages, maybe receive a phone call. Once you’re ready to get to the MMS action, click the button to go to your account.
Buy an MMS-enabled phone number
On your account dashboard, you’ll see your account SID and auth token near the top of the screen. These are like your username and password for the Twilio API – you’ll need these values later on to make authenticated requests to the Twilio API.
But for now, we need to either buy or use an existing phone number that can send MMS messages. Click on “Numbers” in the top nav. In your list of phone numbers, there are icons indicating the capabilities of each number. If you already have a number with MMS enabled, then you’re all set!
If you still need a number with MMS, click the “Buy Number” button. In the resulting dialogue, search for a number that has MMS capabilities.
In the resulting list, choose the option to buy one of these MMS-enabled phone numbers. Great! Now that we have an MMS-capable number, we’re ready to write code that sends and receives MMS messages. We’ll start sending our first pictures by using a high level helper library that makes it easier to work with the Twilio API.
Set up our project
Before we begin, you will need to have both Node.js and npm installed. If you haven’t already, you can download a Node.js installer for your platform here, which should also include npm.
In a terminal window, create a new folder called “demo”. This will be the home of our Node.js application. Next, install the Twilio module and our other dependencies from npm.
Now, let’s create the files and directory structures we’ll need to start developing our application.
For this simple application, we’ll just need those two files – “app.js” and “views/index.jade”. We’re using the popular Express web framework for node, along with some supporting modules. Those supporting modules are Jade (a template engine for rendering HTML) and body-parser, which we use to process incoming POST parameters to our web app. And we’ve also installed the Twilio module for node.js, which will help us in doing the Twilio bits of our application.
Before we begin, you will need to have both Python and pip installed. If you haven’t already you can install a Python installer for your platform here. In addition, you will want to install pip to manage your packages.
In a terminal window, create a new folder called “demo.” This will be the home of our Python application. Next, install the Twilio module and Flask with a pip install command.
Finally, to complete setup, let’s create a new file called app.py in our “demo” directory. This is where our web application code will live in just a little while.
To demostrate how to use the messaging APIs, we’ll write a simple servlet application (and one plain old Java class) that will send and receive messages. We’ll assume that you already have Java installed on your system. For this particular tutorial, we will be creating a Dynamic Web Project in Eclipse – you can download the version of Eclipse we’re using from here. We will also be deploying to Apache Tomcat – if you don’t have Tomcat on your system, you can download it from here.
Once you download and launch Eclipse, create a new “Dynamic Web Project”. Call the project “MmsDemo” – take note of this name, as it also functions as your servlet app’s context root.
You may also need to configure a runtime for this application – that’s why we downloaded Tomcat. During project creation, if you have none available, click “New Runtime”. Here, you can configure the Tomcat version you downloaded, and tell Eclipse where you extracted it.
Next, you’ll need to download and install the Twilio helper library for Java. There’s lots of ways to get it, including through the Maven repository, but for this example let’s go ahead and download the jar directly. As of this writing, our helper library is at version 3.4.x – make sure to download the version with all dependencies bundled.
Once you download the jar, you can drag and drop or copy/paste it into our app’s WEB-INF/lib directory, so it will be available on the Java class path.
Before we begin, we assume you have Ruby and Ruby Gems installed. If you’re on a Mac, these should be installed already – if you’re on Windows, you might consider this installer. If you’re on Linux, you probably know what you’re doing ;) – but here’s a solid guide to getting started through apt-get on Ubuntu.
In a terminal window, create a new folder called “demo”. Change into this directory – we’ll put all our application code here. Next, let’s install the Twilio and Sinatra Ruby gems:
Next, let’s create the files and directory structures we will need:
For this application, we will be using the lightweight Ruby web framework Sinatra. Along with Ruby’s ERB templating engine, it should provide all the functionality we need for this application. We’ll use the Twilio Ruby gem to make interacting with the Twilio APIs a bit easier – we’ll see how as the tutorial goes on.
Before we begin, we assume that you have a server installed running PHP. If you’re on a Mac, you might consider MAMP. If you’re on Windows, you might consider XAMPP. If you’re on Linux, you probably know what you’re doing ;) – but here’s a solid guide to getting started on Ubuntu.
In a terminal window, navigate to your document root folder and create a new folder called “demo” – we’ll put all our application code here. Change into your new “demo” directory. Now, let’s install the Twilio PHP library. If you’re a fan of composer you can install “twilio/sdk” but in this case we’ll install it manually.
For this application, we will be using pure PHP without a framework. The only external dependency we’ll use is the Twilio PHP library, which makes interacting with the Twilio APIs a bit easier. You’ll see how to make use of it later on.
To demonstrate how to use the messaging APIs, we’ll write an ASP.NET MVC application that uses the Twilio helper library for .NET.
In Visual Studio, create a new “ASP.NET Web Application”. Call the project “MmsDemo”. Remember this name, as you’ll need it later when we handle incoming MMS messages.
Next, you’ll need to install the Twilio.Mvc helper library for .NET using NuGet. There are a few ways to do this and both of them are covered in our installation guide.
Now that our project is all set up, let’s send an MMS message through our Twilio account!
Sending MMS Messages with the REST API
To send an MMS message, we’ll need to make an authenticated request to the Twilio REST API. You can do this in any programming language or environment that speaks HTTP, but in this example we’ll be using a special language-specific helper library that makes this very easy.
If you’ve used Twilio before to send text messages, you probably know that in the POST parameters you send to Twilio, you include a “Body” parameter that contains the text for the message. With MMS, you can include a text body as well if you want to. The new parameter for MMS is “MediaUrl” – this must be a fully qualified URL to an image that is accessible on the public Internet, and is under 5 MB in size.
There are a few requirements about the type of image you’re trying to send also – you can check those out here in the docs. If your image is something Twilio can handle, we’ll send it along as an MMS message to the phone number of your choosing. Let’s use a Twilio REST client to send our first MMS message!
For this example, we’re going to create a web form where a user can enter a destination number and send an MMS. In your application folder, open “views/index.jade” in your favorite text editor. We’ll use Jade to generate an HTML page with a form that will contain the values we need to send an MMS message:
Now, open “app.js” and add in the following code – take a look through the comments to see what’s happening at each step:
Now, we’re ready to run the app! In your terminal, start the application with “node app.js”. In your browser, visit localhost:3000 to see your running application.
In the form, enter in your mobile phone number, an optional message, and a URL to an image on the Internet. Google image search is definitely your friend here, but if you’re at a loss, may I suggest this animated GIF from Adventure Time?
First, let’s fire up a Python REPL to write some Python code to send a MMS.
Next, let’s import a class to help us interact with the Twilio API, the TwilioRestClient.
Then we’ll define our account credentials to authenticate our client and instantiate a client to use.
Next, we’ll send our first picture:
You can send almost any image you want with your message – in the code above we sent the Twilio logo, but you can also send animated GIFs like the one below.
In your Eclipse project, create a new class – anywhere within the Java Resources’ “src” folder is fine. Call the new class “SendMessage”. Now, open up SendMessage.java and add the following code – check the comments at each step to see what’s going on:
The code above should be good to send yourself an MMS message! To run it, select the SendMessage.java file in the file explorer, right click it, and choose “Run as… Java Application”. You can use any image URL you like for the example, but if you’re at a loss, may I suggest this animated GIF from Adventure Time?
For this example, we’re going to create a web form where a user can enter a number and send an MMS. In your application folder, open “views/index.erb” with your favorite text editor. We’ll be using Ruby’s ERB template engine to generate a simple HTML page with a form that will contain the values we need to send an MMS message:
Now, open app.rb and add the following code – take a look through the comments to see what’s happening at each step:
Now, we’re ready to run the app! In your terminal, start the application with “ruby app.rb”. In your browser, visit localhost:4567 to see your running application.
In the form, enter in your mobile phone number, an optional message, and a URL to an image on the Internet. Google image search is definitely your friend here, but if you’re at a loss, may I suggest this animated GIF from Adventure Time?
For this example, we’re going to create a web form where a user can enter a number and send an MMS. In your application folder, create and open “index.html” with your favorite text editor. We’ll be writing a simple HTML page containing a form with all the values we need to send an MMS message:
Now, create and open “send.php” and add the following code – take a look through the comments to see what’s happening at each step:
Now you’re ready to give your app a spin. If you’re running locally using MAMP or XAMPP, visit localhost:8080/demo to see your running application.
In the form, enter in your mobile phone number, an optional message, and a URL to an image on the public Internet. Google image search is definitely your friend here, but if you’re at a loss, may I suggest this animated GIF from Adventure Time?
For this example, we’re going to create a web form where a user can enter a number and send an MMS. To do this we’ll need to create a view to present our form and a controller to handle the user’s input.
Create a new controller called “MmsController”. Open up “MmsController.cs” and add the following using statements:
Next, create a new View inside of the “Views\Mms” folder called “Index.cshtml”. Replace the contents of this file with the following code:
At this point we have our web form set up and ready to be displayed. The next step is to add code to our controller to handle the user’s form input. Open up “MmsController.cs” again and add the following method – take a look through the comments to see what’s going on at each step:
Now we’re ready to run the app! Press F5 to start the application in your default browser. In the form, enter in your mobile phone number, an optional message, and a URL to an image on the public Internet. Google image search is definitely your friend here, but if you’re at a loss, may I suggest this animated GIF from Adventure Time?
http://i.imgur.com/Act0Q.gif
In a few moments, your handset should buzz with a new message that contains your image! Let that sink in for a second – you now have the ability to programmatically send animated GIFs to your friends and colleagues via MMS (animations work on many, but not all, handsets). Please, use this power responsibly.
So now we know how to send outbound messages, but what about accepting inbound MMS messages? We can definitely do that as well. Let’s write some code to enable that in our web application.
Receiving MMS Messages in Your Application
To let developers know about inbound messages to their phone numbers, Twilio makes use of a callback pattern called webhooks. Whenever an interesting event happens within Twilio, such as an incoming call or text message, Twilio will send an HTTP request to a URL you specify with information about the event.
In the case of an incoming message or call, Twilio needs your web application to tell it how to respond. Should Twilio send a text message back? If it’s a call, should Twilio drop the caller into a conference, or maybe forward the call to another number?
The way your application tells Twilio what to do next is by responding to a webhook request with an XML document containing a set of about a dozen special tags we call TwiML. In the case of MMS, we’ll be responding with the <Message> tag. We’ll see how that works in just a bit, using an XML (TwiML) -generating utility that is available in our Twilio helper library.
When Twilio sends our app a webhook request, that request will contain (by default) POST data about the incoming call. There will be POST parameters for the number of the incoming texter, the body of their message, and other useful data. You can see all the data available in the incoming request here.
In the case of MMS, there will be a couple POST fields of particular interest to you. The first is “NumMedia” which indicates how many images were sent with the message. Then there will be one or many POST fields with the naming convention “MediaUrl[n]“, where “n” is the index of the media object you’re dealing with. For example, an incoming MMS with three images attached would have POST parameters called “MediaUrl0″, “MediaUrl1″, and “MediaUrl2″. You can use these values to work with media that are submitted to your application.
In our example, we’re going to implement a new endpoint that will respond to incoming MMS messages by replying with that animated GIF we saw earlier. The XML we are sending back will look like this:
Let’s see what the code looks like to actually generate this TwiML in response to a POST request.
Implement a webhook route that returns TwiML
Open up “app.js” again in your text editor of choice. Now, let’s add a route that will accept a POST request from Twilio, and return XML (TwiML) as a response. Add the following code under the route definition for “/send”. Follow along with the comments to see what is happening at each step:
Now in the terminal, make sure to restart your Node process so that these changes take effect.
Let’s open up that app.py file in your text editor of choice. Now, we’ll create a Flask application with a route called “/message”. This route will accept a POST request from Twilio, and return XML (TwiML) as a response. Add the following code to app.py. Follow along with the comments to see what is happening at each step.
To handle incoming HTTP requests from Twilio, we’ll now need to create a servlet. In Eclipse, right click on the Java Resources’ “src” directory. Under the “New” menu, choose “Servlet”. In the resulting dialogue, type in “MmsServlet” as the class name and click “Finish”. This should create a new file called “MmsServlet.java”. Replace the contents of this file with the following – read along in the comments to find out what’s happening precisely at each step, but we’re creating a servlet that will respond to a POST request by rendering TwiML.
Now, we need to deploy our servlet to our servlet container Tomcat. In Eclipse, right click on the top-level project. Under the Run As menu, click “run on server”. This should start a local Tomcat server on port 8080. The logic we just included should now be available at localhost:8080/MmsDemo/MmsServlet if you followed the naming conventions we used in this tutorial.
Open up “app.rb” again in your text editor of choice. Now, let’s add a route that will accept a POST request from Twilio, and return XML (TwiML) as a response. Add the following code under the route definition for “/send”. Follow along with the comments to see what is happening at each step:
Back in the terminal, make sure to restart your Ruby process so that these changes take effect.
Create and open “message.php” in your text editor of choice. Add the following code that will respond to Twilio’s incoming POST request with some XML (TwiML). Follow along with the comments to see what’s happening at each step:
Open up “MmsController.cs” again. We’re going to add a controller method that will accept a POST request from Twilio and return XML (TwiML) as a response. Add the following method to “MmsController” under the “Send” method we added previously. Follow along with the comments to see what is happening at each step:
Get a public URL for your app with ngrok
Now that we have an endpoint that can respond to an incoming request from Twilio, we need to get it on the Internet. We could deploy it to the web host or public server of our choice, but in development, it’s usually nice to have Twilio hit the local version of your application that’s currently running. But how can we put our laptop on the Internet?
Enter one of our very favorite tools, ngrok. Ngrok forwards HTTP traffic from a public subdomain to a local port on your computer. To use ngrok, you simply download the binary executable for your system, navigate to the directory where you downloaded it in a Terminal window, and execute the command, passing in the port number you’re running your app on locally.
Using ngrok can be a bit more involved if you’re running on Windows. Check out this tutorial for in-depth information on getting ngrok going on that OS. For more guidance on using and configuring ngrok generally, you might check out this post as well.
For our application, we’re running on port 300050004567808080808888 if you’ve been following the instructions so far. In your terminal, type “./ngrok {your port}” on Mac/*nix systems or just “ngrok {your port}” on Windows. For ASP.NET MVC, you can launch ngrok from the “ngrok Configurator” described in the ngrok on Windows tutorial. This will ensure you are using the correct port. The result should be an interface like this one that contains your local port’s new public URL.
See that http:// URL in terminal output? Copy that bad boy to your clipboard – we’re going to use it to configure our Twilio MMS number to send incoming MMS messages to our application. Head back out to your account page and let’s get that configuration set.
Configure your Twilio number
Go to your account’s phone numbers and click on your MMS number. In the screen that follows, you’ll see two text fields – the Voice and Messaging URLs for this number. This is where you configure the URLs that will receive HTTP requests when your phone number gets an incoming message or call.
In the messaging URL field, paste in your ngrok URL from earlier. Append to this the route that we created for rendering a TwiML response. Your servlet route, if you used the suggested names, is probably /MmsDemo/MmsServlet rather than /message. The number configuration should look something like this:
Note that the route for the ASP.NET MVC application will be “/Mms/Message” if you followed along with the naming conventions in this tutorial.
Save your configuration changes, and then send a (text or picture) message to your Twilio number. In a moment or two, you should receive a reply with the message and image we included in our TwiML response!
Wrapping Up
In this tutorial, we’ve learned the basics of sending and receiving MMS messages with Twilio. With these basic building blocks, you can create entirely new categories of messaging applications. Send boarding passes, promote sale items, send receipts, share ultrasound images, save prom photos – you send or receive any picture that makes up the story you need to tell.
In the weeks ahead, watch the blog for more tutorials on how to put MMS to work. In the meantime, check out the official REST API docs for in-depth information on the messaging APIs. You can also have a look at the documentation for Media resources to see what you can do with user-submitted image content.
If you have any questions or run into problems, don’t hesitate to reach out at help@twilio.com. We’d also love to see what you’re up to and what you’ve built – feel free to hit us up on the Twitters if you’d like to chat. Though words may not be sufficient to tell us what you’ve made – feel free to send us a picture also.
Getting Started with Twilio MMS Messaging