Learn about sending MMS with Bandwidth and GIPHY APIs

Are you ready to learn about MMS? This puppy is ready to learn. You should be like this puppy.

Seriously, though, with the help of GIFs provided by the GIPHY API, we will learn a bit about how sending MMS using Bandwidth’s Messaging V2 product works. Then, in a later post, we will learn about receiving MMS.

Note: this is an example using our V2 Messaging product, our new and improved messaging platform. If you are using V1 messaging currently and are interested in V2, please reach out to your primary contact at Bandwidth. We are always happy to explain what you can gain by upgrading to V2. Full V2 documentation is here.

The basics

Here are some simple ground rules about sending MMS:

1. MMS stands for Multimedia Messaging Service. It is a method of sending text messages that contain media files like images, videos, audio, and GIFs, which SMS cannot do.
2. The limit on file size with MMS varies depending on the carrier. We recommend not sending any files larger than 500 kb to avoid issues with these limits.

Got these basics? Let’s move on.

What you need

1. An active Bandwidth account for V2 Messaging and all the proper credentials for that account.
2. Coding skills. We will use NodeJS for our script, but you can interact with Bandwidth’s API with many other programming languages.
3. An account with GIPHY.
4. A desire to find awesome GIFs on the Internet.

Got all four? Are you ready for some code?

Requirements

This sample command line script is built using NodeJS and a few packages from npm. Those packages are as follows:

1. node-bandwidth 3.0.2
2. request 2.88.0

The next step is to ensure you have a local (not toll-free) number purchased on your Bandwidth account and that that number is correctly associated with a location on your account and a Bandwidth application. We don’t need callbacks for this sample script unless we need to diagnose delivery errors, but your Bandwidth phone number needs to be set up correctly with a callback URL for the script to work. For info on how to do this, go here.

You will also need your Bandwidth V2 Messaging user ID, token, secret, and an API key from GIPHY.

Now for some code!

So the process our script goes through looks like this:

1. Set requirements
2. Define the Bandwidth client using credentials
3. Create a GIPHY API URL using our command line arguments
4. Send a request to GIPHY to pull a GIF*
5. Send an MMS!

*Note that we are going to send our GIF as an MP4. Some receiving carriers will display a .gif as a still image on the receiving user’s phone. Since this is a choice of the receiving carrier, Bandwidth does not have control over how the GIF displays on the receiving user’s phone. GIPHY provides GIFs in MP4 format and GIF, and MP4s tend to arrive at receiving users with better image quality without being cut to a single still frame.

So a quick script that will do all of the above steps (once your npm packages are installed) looks like this:

const Bandwidth = require("node-bandwidth");
const request = require("request");

var client = new Bandwidth({
    userId: "{{USER_ID}}",
    apiToken: "{{TOKEN}}",
    apiSecret: "{{SECRET}}"
});

var url = "https://api.giphy.com/v1/gifs/search?api_key=";
url += "{{GIPHY_API_KEY}}";
url += "&q=";
url += process.argv[2];
url += "&limit=1";

request.get({
    url: url,
}, function(err, response, body){
    var gif = JSON.parse(body).data[0].images.downsized_small.mp4;
    client.v2.Message.send({
from: "{{YOUR_BANDWIDTH_NUMBER}}",
to: [process.argv[3]],
text: "Is GIF a hard G or a soft G??",
media: [gif],
applicationId: “{{APPLICATION_ID})”;
    });
});

Note that the media URL must be publicly accessible and is set in an array when defining the API JSON.

Let’s run our script

The next step is to run our script on the command line.

Assuming your script saves in a file named gif.js and you wanted to send a puppy GIF to yourself at +19195551212, this would look like this:

node gif.js puppy +19195551212

Note that you would have to URL encode any spaces in your GIF search string unless you write additional code that does this for you. So searching for Detective Pikachu would look like Detective%20Pikachu.

And that’s it. The MMS containing the MP4 of your GIF is now on its way to the number you specified. If the MMS doesn’t arrive, feel free to console the response log from the API request to detect errors and set up a proper callback server so you can receive any delivery errors.

Stay tuned for a follow-up post about receiving MMS.