DevStack

Learning About Sending MMS with Bandwidth and GIPHY APIs

Samantha Capps
Samantha Capps
Share

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 some GIFs provided by the GIPHY API, in this blog post we are going to learn a bit about how sending MMS using Bandwidth’s Messaging V2 product works. In a later post, we will learn about receiving MMS.

Note that 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 carrier. We generally recommend not sending any files larger than 1.5 MB to avoid issues with these limits.
  3. Currently at Bandwidth, as is standard in our industry, you cannot send or receive MMS with toll- free numbers.

Got these basics? Let’s move on.

What You Need

  1. A Bandwidth account enabled for V2 Messaging and all the proper credentials for that account.
  2. Coding skills. Here we are going to be using 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? You ready for some code?

Requirements

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

  1. node-bandwidth 3.0.2
  2. request 2.88.0

The next step is to make sure you have a local (not toll- free) number purchased on your Bandwidth account and that that number is properly 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 properly with a callback URL in order 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, and secret, as well as an API key from GIPHY.

Now for Some Code!

So the process our script goes through looks like this:

  1. Set requirements
  2. Define 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 actually 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 is displayed on the receiving user’s phone. GIPHY provides GIFs in MP4 format as well as GIF, and MP4s tend to arrive at receiving user with better image quality and 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

Next step is to run our script in the command line.

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

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 log the response from the API request to detect errors there and to set up a proper callback server so you can receive any delivery errors.

Stay tuned for a follow up post about receiving MMS.