You never know the true value of an app until it’s finished.

Twilio developer evangelist Matt Makai and I wanted to take advantage of Twilio’s latest feature, an API for sending picture messages. (See our API explainer if you don’t know what that means.) I pitched Cheer Up!, an uplifting image delivery service. It’d harness the Flickr API to deliver pictures of whatever you want on demand.

That all went out the window when we decided to use Flickr tags as the image retrieval system. People use tags for all sorts of reasons, and they don’t always make sense. As a result, the app only delivers the photo you want about 50% of the time.

We could work with that, though. Now we’re introducing Picture Roulette, an MMS application you can easily create for yourself. Type in a query of one or more words. Does the photo Flickr sends back look like your query? You win! If not, you take a drink. It’s a penalty game made possible by Flickr users’ tagging nonconformity.

It’s not what we expected to build, but it turned out to be a lot more fun. And at only two cents per picture message, it’s a very cheap thrill.

Here’s how to get Picture Roulette working on your own phone:

Requirements

You’ll need a Twilio account, complete with a registered phone number and about $5 in funds. For very thorough instructions on signing up for Twilio, see my Twilio tutorial. You’ll need both your AccountSID and secret AuthToken for this project.

See also: My Fish Just Sent Me A Text Message

You’ll also need a Flickr API number. In the Flickr App Garden, choose to create a new app with a non-commercial license. Flickr will instantly deliver to you a key and a secret key. We don’t need the secret key for this project, but paste the key where you’ll remember it.

Finally, you’ll need a free-tier Heroku account. We’ll be using Heroku’s one-click-deploy button on GitHub, which makes it so you won’t actually have to do any hard coding. The button, which launched for GitHub last month, lets you create our GitHub app on your own Heroku account without cloning the repository.

See also: See What The Code Behind An App Does With Just One Click

Instructions

On our Picture Roulette GitHub repository, click on the purple Heroku button on the Readme file. It should immediately launch Heroku.

See also: Developers, Check Your AWS Accounts For Bitcoin Miners

Once on Heroku, the app will prompt you to input your Twilio AccountSID and secret AuthToken followed by your Flickr API key. Heroku can’t launch an app that isn’t fully functional, and the app as it sits on GitHub isn’t fully functional without input from you. That’s because we know better than to put our secret key in a public GitHub repository. Right?

Click “Deploy for Free” and wait for the app to build. Sometimes it can take quite a while. Once all the steps have green circles next to them, click “view it” at the bottom of the screen.

If the app deployed correctly, it shouldn’t look very exciting. As the screenshot indicates, it will simply let you know if the deployment worked. Now, do as it says and copy the browser URL for your Heroku app—i.e., the URL in your browser window right now. No two Heroku apps can have the same name since they’re all stored in the same stack, so it’ll have a funny nature inspired name like “boiling forest” or “blooming spring.”

See also: Heroku 101: A Beginner’s Guide To Hosting Apps In The Cloud

Now, navigate to your Twilio account and go to the Numbers tab. Click on your Twilio number and paste the URL into the Messaging Request URL field. Press save.

Try texting a word to your Twilio number from your phone. Wait about 20 seconds, and Flickr should send you back a photo of that word! Maybe.

How It Works

If you look around the Picture Roulette repository, you’ll notice that no document contains more than 50 lines of code. That’s because this Python application lets the Twilio API and Flickr API do most of the heavy lifting. It also uses Flask, a Python microframework, to hold everything together.

The heart of the program lies in views.py. Here, you can see where Matt imported the Twilio and Flickr APIs and set up three functions:

  • send_image is the function behind the Heroku app deployment. If your app launches correctly, this function makes a message display on the screen when you view it in your web browser.
  • _get_flickr_image is what makes the game stay fresh, even if you play it day after day. This function calls the Flickr API and tells it to browse the 25 first results by their tag. One of those results will randomly be sent to you. So if you keep texting “pumpkin,” over and over, you’ll get a different image every time. As people continue to load new images into Flickr, the 25 first tagged results will change over time.
  • _send_mms_twiml interacts with the Twilio MMS API. “TwiML,” stands for Twilio Markup Language, and is used as a set of instructions to tell Twilio what to do in response to a text to your Twilio number. In this case, the function tells it to return a photo message to the sender.

The bulk of the other files tell the Picture Roulette GitHub repository use the Flask framework to interact with Heroku so it can be easily deployed. You can also read about setting up any GitHub repository to deploy to Heroku in an earlier tutorial.

Here’s what it might look like in action. Maybe:

Let us know if you had fun with Picture Roulette. And if you’ve got suggestions for how we can make it better, you’re welcome to submit a pull request

Screenshots by Lauren Orsini for ReadWrite