Sending MMS

Last updated: 2024-01-31Contributors
Edit this page

One can send multimedia content via SMS as well. To send multimedia messages, the requirement is the same as for sending a text message, and the phone number must have the MMS feature enabled.

RingCentral platform supported MMS content types

Category MIME File Extension
Image image/jpeg .jpeg/.jpg
image/png .png
image/bmp .bmp
image/gif .gif
image/tiff .tiff/.tif
image/svg+xml .svg
Video video/3gpp .3gp
video/mp4 .mp4
video/mpeg .mpeg
video/msvideo .avi
Audio audio/mpeg .mp3
V-Card text/vcard .vcf/.vcard
Compressed file application/zip .zip
application/gzip .gzip
Document application/rtf .rtf

Attachment Limitations

  • There is a combined limit of 1.5MB for all attachments per message.
  • There is a limit of 10 attachments per message.

There is an alias /mms endpoint for sending MMS messages, but you can also call the /sms endpoint to send MMS messages. The API takes mixed contents, a JSON object which specifies the "from" and "to" phone numbers as well as the text content. And attachments which includes multimedia files. Therefore, you must use multipart form-data, and set the content-type header to multipart/mixed.

Creating Attachments

When creating a multipart message, it is important to remember that the root part, or first part of the request is always the request body or payload. Subsequently you attach media files to the request. In the following example we will send an image named test.jpg along with the text message, "Hello world"

Running the code

  • If you have tried the SMS quick start, you can just copy all the functions below and add them to the quick start project then call the read_extension_phone_number_detect_mms_feature() function. Otherwise, edit the variables in ALL CAPS with your app and user credentials before running the code.
  • If you run on your production account, remember to use app credentials for production and change the RingCentral server URL to "https://platform.ringcentral.com"
const RC = require('@ringcentral/sdk').SDK

// Instantiate the SDK and get the platform instance
var rcsdk = new RC({
    server: "https://platform.devtest.ringcentral.com",
    clientId: "SANDBOX-APP-CLIENTID",
    clientSecret: "SANDBOX-APP-CLIENTSECRET"
});
var platform = rcsdk.platform();

/* Authenticate a user using a personal JWT token */
platform.login({ jwt: "SANDBOX-JWT" })

// For the purpose of testing the code, we put the recipient number in the variable.
// Feel free to set the recipient number directly.
var RECIPIENT = "RECIPIENT-PHONE-NUMBER"

platform.on(platform.events.loginSuccess, function(e){
    read_extension_phone_number_detect_sms_feature()
});

platform.on(platform.events.loginError, function(e){
    console.log("Unable to authenticate to platform. Check credentials.", e.message)
    process.exit(1)
});

/*
  Read phone number(s) that belongs to the authenticated user and detect if a phone number
  has the MMS capability
*/
async function read_extension_phone_number_detect_mms_feature(){
  try {
      let endpoint = "/restapi/v1.0/account/~/extension/~/phone-number"
      var resp = await platform.get(endpoint)
      var jsonObj = await resp.json()
      for (var record of jsonObj.records){
          for (feature of record.features){
              if (feature == "MmsSender"){
                // If a user has multiple phone numbers, check and decide which number
                // to be used for sending MMS message.
                return await send_mms(record.phoneNumber)
              }
          }
      }
      if (jsonObj.records.length == 0)
        console.log("This user does not own a phone number!")
      else
        console.log("None of this user's phone number(s) has MMS capability!")
  } catch(e) {
      console.log(e.message)
  }
}

/*
 Send a multi-media message from a user own phone number to a recipient number
*/
async function send_mms(fromNumber){
    var FormData = require('form-data');
    formData = new FormData();
    var bodyParams = {
        from: { phoneNumber: fromNumber },
        to: [{ phoneNumber: RECIPIENT }],
        // To send group messaging, add more (max 10 recipients) 'phoneNumber' object. E.g.
        /*
        to: [
           { phoneNumber: "Recipient1-Phone-Number" },
           { phoneNumber: "Recipient2-Phone-Number" }
         ],
        */
        text: 'Hello World'
    }
    // Attach the bodyParams to multipart form data
    formData.append('json', new Buffer.from(JSON.stringify(bodyParams)), {
        contentType: 'application/json'
    });
    // Attach a media file to multipart form data
    formData.append('attachment', require('fs').createReadStream('test.jpg'));
    try {
      let endpoint = "/restapi/v1.0/account/~/extension/~/mms"
      var resp = await platform.post(endpoint, formData)
      var jsonObj = await resp.json()
      console.log("MMS sent. Message id: " + jsonObj.id)
      check_mms_message_status(jsonObj.id)
    } catch (e){
      console.log(e.message)
    }
}

/*
 Check the sending message status until it's out of the queued status
*/
async function check_mms_message_status(messageId){
  try {
      let endpoint = `/restapi/v1.0/account/~/extension/~/message-store/${messageId}`
      let resp = await platform.get(endpoint);
      let jsonObj = await resp.json()
      console.log("Message status: ", jsonObj.messageStatus)
      if (jsonObj.messageStatus == "Queued"){
        await sleep (5000);
        check_mms_message_status(jsonObj.id);
      }
  } catch (e) {
    console.log(e.message)
  }
}

const sleep = async (ms) => {
  await new Promise(r => setTimeout(r, ms));
}
import time
from ringcentral import SDK

# Read phone number(s) that belongs to the authenticated user and detect if a phone number
# has the MMS capability
def read_extension_phone_number_detect_mms_feature():
    try:
        endpoint = "/restapi/v1.0/account/~/extension/~/phone-number"
        resp = platform.get(endpoint)
        jsonObj = resp.json()
        for record in jsonObj.records:
            for feature in record.features:
                if feature == "MmsSender":
                    # If a user has multiple phone numbers, check and decide which number
                    # to be used for sending MMS message.
                    return send_mms(record.phoneNumber)

        if jsonObj.records.count == 0:
            print ("This user does not own a phone number!")
        else:
            print ("None of this user's phone number(s) has the MMS capability!")
    except Exception as e:
        print (e)


# Send a multi-media message from a user own phone number to a recipient number
def send_mms(fromNumber):
    try:
        builder = rcsdk.create_multipart_builder()
        builder.set_body({
            'from' : { 'phoneNumber': fromNumber },
            'to'   : [ {'phoneNumber': RECIPIENT} ],
            # To send group messaging, add more (max 10 recipients) 'phoneNumber' object. E.g.
            #
            # 'to': [
            #       { 'phoneNumber': "Recipient1-Phone-Number" },
            #       { 'phoneNumber': "Recipient2-Phone-Number" }
            #     ],
            'text' : 'Hello world'
        })

        with open('test.jpg', "rb") as f:
            content = f.read()
            attachment = ('test.jpg', content)
            builder.add(attachment)
            request = builder.request('/restapi/v1.0/account/~/extension/~/sms')
        resp = platform.send_request(request)
        jsonObj = resp.json()
        print ("MMS sent. Message id: " + str(jsonObj.id))
        check_mms_message_status(jsonObj.id)
    except Exception as e:
        print (e)


# Check the sending message status until it's no longer in the queued status
def check_mms_message_status(messageId):
    try:
        endpoint = "/restapi/v1.0/account/~/extension/~/message-store/" + str(messageId)
        resp = platform.get(endpoint)
        jsonObj = resp.json()
        print ("Message status: " + jsonObj.messageStatus)
        if jsonObj.messageStatus == "Queued":
            time.sleep(5)
            check_mms_message_status(jsonObj.id)
    except Exception as e:
        print (e.message)

# Authenticate a user using a personal JWT token
def login():
    try:
      platform.login( jwt= "SANDBOX_JWT" )
      read_extension_phone_number_detect_mms_feature()
    except Exception as e:
      print ("Unable to authenticate to platform. Check credentials." + str(e))

# Instantiate the SDK and get the platform instance
rcsdk = SDK("SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com")
platform = rcsdk.platform()

login()

# For the purpose of testing the code, we put the recipient number in the variable.
# Feel free to set the recipient number directly.
RECIPIENT = "RECIPIENT-PHONE-NUMBER"
####################################
<?php
require('vendor/autoload.php');

// Instantiate the SDK and get the platform instance
$rcsdk = new RingCentral\SDK\SDK( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com" );
$platform = $rcsdk->platform();

/* Authenticate a user using a personal JWT token */
try {
  $platform->login(["jwt" => "SANDBOX-JWT"]);
}catch (\RingCentral\SDK\Http\ApiException $e) {
  // Getting error messages using PHP native interface
  print 'Expected HTTP Error: ' . $e;
  exit ("Error message: " . $e->apiResponse->response()->error() . PHP_EOL;
}

// For the purpose of testing the code, we put the recipient number in the variable.
// Feel free to set the recipient number directly.
$RECIPIENT = "RECIPIENT-PHONE-NUMBER";

read_extension_phone_number_detect_mms_feature();

/*
  Read phone number(s) that belongs to the authenticated user and detect if a phone number
  has the MMS capability
*/
function read_extension_phone_number_detect_mms_feature(){
  global $platform;
  $endpoint = "/restapi/v1.0/account/~/extension/~/phone-number";
  $resp = $platform->get($endpoint);
  $jsonObj = $resp->json();
  foreach ($resp->json()->records as $record){
    if ($record->usageType == "DirectNumber"){
      foreach ($record->features as $feature){
        if ($feature == "MmsSender"){
          // If a user has multiple phone numbers, check and decide which number
          // to be used for sending MMS message.
          return send_mms($record->phoneNumber);
        }
      }
    }
  }
  if (count($jsonObj->records) == 0)
    exit("This user does not own a phone number!");
  else
    exit("None of this user's phone number(s) has the MMS capability!");
}

/*
 Send a multi-media message from a user own phone number to a recipient number
*/
function send_mms($fromNumber){
  global $platform, $rcsdk, $RECIPIENT;
  try {
    $bodyParams = array(
      'from' => array( 'phoneNumber' => $fromNumber ),
      'to'   => array( array('phoneNumber' => $RECIPIENT ) ),
      // To send group messaging, add more (max 10 recipients) 'phoneNumber' object. E.g.
      /*
      'to' => array(
         array('phoneNumber' => "Recipient1-Phone-Number"),
         array('phoneNumber' => "Recipient2-Phone-Number")
      ),
      */
      'text' => 'Hello World'
    );

    $endpoint = "/restapi/v1.0/account/~/extension/~/mms";
    $request = $rcsdk->createMultipartBuilder()
        // Add the bodyParams to multipart request
        ->setBody( $bodyParams )
        // Attach a media file to multipart request
        ->add(fopen(__DIR__.'/test.jpg', 'r'))
        ->request($endpoint);

    $resp = $platform->sendRequest($request);
    print_r ("MMS sent. Message id: " . $resp->json()->id . PHP_EOL);
    check_mms_message_status($resp->json()->id);
  }catch (\RingCentral\SDK\Http\ApiException $e) {
    // Getting error messages using PHP native interface
    print 'Expected HTTP Error: ' . $e;
    print '  Message: ' . $e->apiResponse->response()->error() . PHP_EOL;
  }
}

/*
 Check the sending message status until it's out of the queued status
*/
function check_mms_message_status($messageId){
  global $platform;
  try {
      $endpoint = "/restapi/v1.0/account/~/extension/~/message-store/".$messageId;
      $resp = $platform->get($endpoint);
      $jsonObj = $resp->json();
      print("Message status: " . $jsonObj->messageStatus . PHP_EOL);
      if ($jsonObj->messageStatus == "Queued"){
        sleep(5);
        check_mms_message_status($jsonObj->id);
      }
  } catch (\RingCentral\SDK\Http\ApiException $e) {
    exit("Message: " . $e->message . PHP_EOL);
  }
}
?>
require 'ringcentral'

# Read phone number(s) that belongs to the authenticated user and detect if a phone number
# has the MMS capability
def read_extension_phone_number_detect_mms_feature()
  begin
    endpoint = "/restapi/v1.0/account/~/extension/~/phone-number"
    resp = $platform.get(endpoint)
    for record in resp.body['records'] do
      for feature in record['features'] do
        if feature == "MmsSender"
          # If a user has multiple phone numbers, check and decide which number
          # to be used for sending MMS message.
          return send_mms(record['phoneNumber'])
        end
      end
    end
    if resp.body['records'].length == 0
      puts ("This user does not own a phone number!")
    else
      puts("None of this user's phone number(s) has the MMS capability!")
    end
  rescue StandardError => e
    puts (e)
  end
end

# Send a multi-media message from a user own phone number to a recipient number
def send_mms(fromNumber)
  begin
    bodyParams = {
          from: { phoneNumber: fromNumber },
          to: [{ phoneNumber: RECIPIENT }],
          # To send group messaging, add more (max 10 recipients) 'phoneNumber' object. E.g.
          #
          #to: [
          #       { phoneNumber: "Recipient1-Phone-Number" },
          #       { phoneNumber: "Recipient2-Phone-Number" }
          #     ],
          text: 'Hello World'
      }
    files = [
              ['test.jpg', 'image/jpeg']
            ]

    endpoint =  "/restapi/v1.0/account/~/extension/~/sms"
    resp = $platform.post(endpoint, payload: bodyParams, files: files)
    puts ("MMS sent. Message id: " + resp.body['id'].to_s)
    check_mms_message_status(resp.body['id'])
  rescue StandardError => e
    puts (e)
  end
end

# Check the sending message status until it's out of the queued status
def check_mms_message_status(messageId)
  begin
    endpoint = "/restapi/v1.0/account/~/extension/~/message-store/" + messageId.to_s
    resp = $platform.get(endpoint)
    puts ("Message status: " + resp.body['messageStatus'])
    if (resp.body['messageStatus'] == "Queued")
      sleep(5)
      check_mms_message_status(resp.body['id'])
    end
  rescue StandardError => e
    puts (e)
  end
end

# Authenticate a user using a personal JWT token
def login()
  begin
    $platform.authorize( jwt: "SANDBOX_JWT" )
    read_extension_phone_number_detect_mms_feature()
  rescue StandardError => e
    puts ("Unable to authenticate to platform. Check credentials." + e.to_s)
  end
end

# Instantiate the SDK and get the platform instance
$platform = RingCentral.new( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com" )

login()

# For the purpose of testing the code, we put the recipient number in the variable.
# Feel free to set the recipient number directly.
RECIPIENT = "RECIPIENT-PHONE-NUMBER"
####################################
using System;
using System.Threading.Tasks;
using RingCentral;

namespace Send_MMS
{
    class Program
    {
        static RestClient restClient;
        static string RECIPIENT = "RECIPIENT-PHONE-NUMBER";
        static async Task Main(string[] args)
        {
          try
          {
            // Instantiate the SDK
            restClient = new RestClient( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com");
            // Authenticate a user using a personal JWT token
            await restClient.Authorize("SANDBOX_JWT");

            await read_extension_phone_number_detect_mms_feature();
          }
          catch (Exception ex)
          {
            Console.WriteLine(ex.Message);
          }
        }

        /*
          Read phone number(s) that belongs to this user and detect if a phone number
          has the MMS capability
        */
        static private async Task read_extension_phone_number_detect_mms_feature()
        {
            try
            {
                var resp = await restClient.Restapi().Account().Extension().PhoneNumber().Get();
                foreach (var record in resp.records)
                {
                    foreach (var feature in record.features)
                    {
                        if (feature == "MmsSender")
                        {
                            // If a user has multiple phone numbers, check and decide which number
                            // to be used for sending MMS message.
                            await send_mms(record.phoneNumber);
                            return;
                        }
                    }
                }
                if (resp.records.Length == 0)
                {
                    Console.WriteLine("This user does not own a phone number!");
                }
                else
                {
                    Console.WriteLine("None of this user's phone number(s) has the MMS capability!");
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
        /*
         Send a multi-media message from a user own phone number to a recipient number
        */
        static private async Task send_mms(string fromNumber)
        {
            try
            {
                var bodyParams = new CreateMMSMessage();
                bodyParams.from = new MessageStoreCallerInfoRequest
                {
                    phoneNumber = fromNumber
                };
                bodyParams.to = new MessageStoreCallerInfoRequest[] {
                    new MessageStoreCallerInfoRequest { phoneNumber = RECIPIENT }
                };
                // To send group messaging, add more (max 10 recipients) 'phoneNumber' object. E.g.
                /*
                requestBody.to = new MessageStoreCallerInfoRequest[] {
                  new MessageStoreCallerInfoRequest { phoneNumber = "Recipient_1_Number" },
                  new MessageStoreCallerInfoRequest { phoneNumber = "Recipient_2_Number" }
                };
                */
                bodyParams.text = "Hello World!";

                var attachment = new Attachment { filename = "test.jpg", contentType = "image/jpeg", content = System.IO.File.ReadAllBytes("test.jpg") };
                var attachments = new Attachment[] { attachment };
                bodyParams.attachments = attachments;

                var resp = await restClient.Restapi().Account().Extension().Mms().Post(bodyParams);
                Console.WriteLine("MMS sent. Message id: " + resp.id.ToString());
                await check_mms_message_status(resp.id.ToString());
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
        /*
         Check the sending message status until it's no longer in the queued status
        */
        static private async Task check_mms_message_status(string messageId)
        {
            try
            {
                var resp = await restClient.Restapi().Account().Extension().MessageStore(messageId).Get();
                Console.WriteLine("Message status: " + resp.messageStatus);
                if (resp.messageStatus == "Queued")
                {
                    Thread.Sleep(2000);
                    await check_mms_message_status(resp.id.ToString());
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
            }
        }
    }
}
package Send_MMS;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;

import com.ringcentral.*;
import com.ringcentral.definitions.*;

public class Send_MMS {
    static String RECIPIENT = "RECIPIENT-PHONE-NUMBER";
    static RestClient restClient;

    public static void main(String[] args) {
      // Instantiate the SDK
      restClient = new RestClient( "SANDBOX-APP-CLIENTID", "SANDBOX-APP-CLIENTSECRET", "https://platform.devtest.ringcentral.com");
      var obj = new Send_MMS();
      try {
        // Authenticate a user using a personal JWT token
        restClient.authorize( "SANDBOX_JWT" );
        obj.read_extension_phone_number_detect_mms_feature();
      } catch (RestException | IOException e) {
        e.printStackTrace();
      }
    }
    /*
    Read phone number(s) that belongs to the authenticated user and detect if a phone number
    has the MMS capability
    */
    public void read_extension_phone_number_detect_mms_feature() throws IOException{
      try {
        var resp =  restClient.restapi().account().extension().phoneNumber().get();
        for (var record : resp.records) {
          if (record.usageType.equalsIgnoreCase("DirectNumber")) {
            for(var feature : record.features) {
              if (feature.equalsIgnoreCase("MmsSender")) {
                // If a user has multiple phone numbers, check and decide which number
                // to be used for sending MMS message.
                send_mms(record.phoneNumber);
                return;
              }
            }
          }
        }
        if (resp.records.length == 0) {
          System.out.println("This user does not own a phone number!");
        } else {
          System.out.println("None of this user's phone number(s) has the MMS capability!");
        }
      }catch(RestException e) {
        System.out.println(e.getMessage());
      }
    }
    /*
    Send a multi-media message from a user own phone number to a recipient number
    */
    public void send_mms(String fromNumber) throws RestException, IOException{
      try {
        CreateMMSMessage bodyParams = new CreateMMSMessage();
        bodyParams.from = new MessageStoreCallerInfoRequest().phoneNumber(fromNumber);

        bodyParams.to = new MessageStoreCallerInfoRequest[]{
          new MessageStoreCallerInfoRequest().phoneNumber(RECIPIENT)
        };
        // To send group messaging, add more (max 10 recipients) 'phoneNumber' object. E.g.
        /*
        requestBody.to = new MessageStoreCallerInfoRequest[] {
          new MessageStoreCallerInfoRequest().phoneNumber("12092520012"),
          new MessageStoreCallerInfoRequest().phoneNumber("16505130930")
        };
        */

        Attachment attachment = new Attachment()
            .filename("test.jpg")
            .content(Files.readAllBytes(Paths.get("./src/test/resources/test.jpg")));
        Attachment[] attachments = new Attachment[] { attachment };
        bodyParams.attachments = attachments;

        var response = restClient.restapi().account().extension().mms().post(bodyParams);
        System.out.println("MMS sent. Message id: " + response.id.toString());
        check_mms_message_status(response.id.toString());
      } catch(RestException e) {
        System.out.println(e.getMessage());
      }
    }
    /*
    Check the sending message status until it's no longer in the queued status
    */
    private void check_mms_message_status(String messageId) throws IOException {
      try {
        var resp = restClient.restapi().account().extension().messageStore(messageId).get();
        System.out.println("Message status: " + resp.messageStatus);
        if (resp.messageStatus.equals("Queued")) {
          try {
            Thread.sleep(5000);
            check_mms_message_status(resp.id.toString());
          } catch (InterruptedException e) {
            e.printStackTrace();
            System.out.println(e);
          }
        }
      } catch (RestException e) {
        System.out.println(e.getMessage());
      }
    }
}

Rate this page: