API Spotlight: MMS API

Creating a pun app and sending plain old SMS messages is fun — but let’s be honest, how cool would it be if we could send images? Or even better — videos???

Give it a Try! Text “grumpy” or “grumpyvideo” to (507) 208–7802

While we can easily create a text-based keyword that does just that, there are a couple things that change. So whether you want to have an awesome video that you want your friends or customers to text in for (be sure to check out the Pun App SMS example) or you want to wish all of your team members a wonderful holiday vacation away from the office — the basics of sending an MMS stay the same.

So without further ado, here we go!!!

Step 1: Setup your RingCentral App

In the RingCentral Developer Console, click on “Create App.” Give your app a name (such as “MMS the World”), a description, and click next.

On the next screen, set your app to “Private” and select “Server-only (No UI)” for a platform type (this is required for the auth flow we will be using).

Finally, for permissions needed, select Edit Messages, SMS (you’ll use the same endpoint for both SMS and MMS), and Webhook Subscriptions:

Step 2: Start our Script with the RingCentral SDK

To make sending MMS messages even easier, we’ll be using the RingCentral PHP SDK. Of course, you don’t need to do this — but in the case of MMS where we’ll be sending multi-part requests, it certainly makes it a little bit easier.

To get started, you can easily install the PHP SDK and its dependencies using Composer. If you don’t have Composer — it’s pretty quick and easy to install too! You can find the SDK and instructions for installing it here.

Now, include it using the standard Composer autoloader:

// Include Libraries
require('vendor/autoload.php');

Once the SDK has been added to your script, we will need to setup the RingCentral SDK client. To do this we will instantiate the class, defining our client ID, client secret, and environment (in this case the Sandbox):

// Setup Client
$sdk = new RingCentral\SDK\SDK(CLIENT_ID, CLIENT_SECRET, RingCentral\SDK\SDK::SERVER_SANDBOX);

Then we’ll check to see if we have an access token, and if not, request one via the password flow:

// Login via API
if (!$sdk->platform()->loggedIn()) {
 $sdk->platform()->login(username, extension, password);
}

If you receive an unauthorized grant type error, make sure you setup your app as Server-only (No UI). If you selected Server/ Web by accident, you will not have access to the necessary auth flow to login using your username, extension (optional), and password.

Step 3: Build our MMS Message

Now the fun part — we need to setup and build our MMS message. This message will contain several different parts — the phone number to send the message to, the RingCentral number we’re sending it from, the text that accompanies the message, and finally the media or attachment we’re sending.

We will do this by telling the SDK that we want to create a Multipart message and then use the multipart builder:

$request = $sdk->createMultipartBuilder()
  ->setBody(array(
   'to'         => array(
    array('phoneNumber' => 'number_to'),
   ),
   'from' => array('phoneNumber' => 'number_from'),
   'text' => 'Have a Grumpy Holiday!!!',
  ))
  ->add(fopen('holidaytechgrumpy-cat.jpg', 'r'))
  ->request('/account/~/extension/~/sms');

A couple important things to note, the first is that the path to our image (holidaytechgrumpy-cat.jpg) is relative to our script. The second is it has to have read privileges assigned to it in order to be opened by the script.

Step 4: Send the Message

Now comes the hardest part — actually sending the message. To do this, we simply use the SDK’s platform method chained with the sendRequest method, passing along the $request object we just created, like so:

$response = $sdk->platform()->sendRequest($request);

Congratulations — you’ve just sent an MMS Message using your RingCentral number!

Give it a Try! Text “grumpy” to (507) 208–7802

Going Further: Sending Audio or Video

But what if you wanted to send a video or audio instead? The steps are exactly the same, except you would simply include the video file or the audio file in place of the image. For example, if you wanted to send a .mp4 you would use the following snippet:

$request = $sdk->createMultipartBuilder()
  ->setBody(array(
   'to'         => array(
    array('phoneNumber' => 'number_to'),
   ),
   'from' => array('phoneNumber' => 'number_from'),
   'text' => 'Have a Grumpy Holiday!!!',
  ))
  ->add(fopen('grumpycat.mp4', 'r'))
  ->request('/account/~/extension/~/sms');
$response = $sdk->platform()->sendRequest($request);

More Grumpy Cat memes?! Text “grumpyvideo” to (507) 208–7802

With that, hopefully you’re not in a “grumpy” mood — but ready to create some awesome MMS messages to send to your team members, customers, or even family and friends — all using the RingCentral number you already have. And remember, you can easily set up a text for video system yourself following the steps in our SMS Pun App example.