SMS API new feature — MMS attachment types
We have added a litany of exciting new features to the RingCentral SMS API. This is the second of a series of articles I am doing to walk through these new features and share some real world examples of how to implement them. In the first article, we covered SMS Consent Management. Next up is a very interesting one: new MMS attachment file types. Typically, there are only a short number of file types that can be added to an SMS message, turning it into a Multimedia Messaging Service (MMS) message. In our latest update, RingCentral has now added a plethora of new file types. You can see the full list here. The list is pretty extensive, so we grouped them into the following categories for easier recognition:
- Image
- Video
- Audio
- V-Card
- Compressed
- Document
A few caveats apply when using these new file types.
- There is a combined file size limit of 1.5 MB per message.
- There is a file count limit of 10 per message.
Other than these two limitations and the file types allowed, the MMS sending process is very similar to that of sending a basic SMS message. There are a few further nuances that are needed and we will cover those within this article.
I have created a small sample app that is being used to demonstrate sending MMS messages. I have done it in PHP and the code is available here on GitHub.
My landing page looks like this.
Here, I am asking for a mobile number with which to send an MMS and the subject or basic text of the message. Additionally, I am providing a mechanism to upload and attach a file to the MMS message. I am only asking for one file here in this demo but remember that an MMS can have as many as ten attachments, provided they are collectively within the 1.5 MB total size limit.
After a few edit checks on the data fields, like a required mobile number and message body, I have this code block.
Get Pbmacintyre’s stories in your inbox
Join Medium for free to get updates from this writer.
$file_with_path = upload_file($target_file);
if ($file_with_path == 0) {
// a file uploading error occured
$print_again = true;
$message = $_SESSION['message'];
} else {
$mms_sent_id = send_mms($to_sms_number, $sms_message_body, $file_with_path ) ;
if ($mms_sent_id > 0) {
$print_again = true;
$message = "SMS Multipart message (MMS) sent successfully (Send id): " . $mms_sent_id ;
// clean out the file
unlink($file_with_path) ;
}
}I call the upload_file function where I take the file name that is provided and check that it is among the list of allowed file types and within a certain file size. Then, I upload that file to a temporary location on my web server and provide that file path to the variable that is expecting this in return.
The upload_file() function looks like this.
function upload_file ($target_file) {
if ($_SERVER['REQUEST_METHOD'] == 'POST') {
// Directory where the file will be uploaded
$target_dir = "uploads/";
// Path to the target file
$file_to_attach = $target_dir . basename($target_file);
// Variable to keep track of upload status
$uploadOk = 1;
// Get file extension
$fileType = strtolower(pathinfo($target_file, PATHINFO_EXTENSION));
// Check file size (limit to 1.5MB)
if ($_FILES["file_to_mms"]["size"] > 1500000) {
$_SESSION['message'] = "Sorry, your file is too large.";
$uploadOk = 0;
}
// Check for allowed file types by extension
$allowedFileTypes = get_allowed_file_types();
if (!in_array($fileType, $allowedFileTypes)) {
$_SESSION['message'] = "Sorry, only specific file types are
allowed. ";
$uploadOk = 0;
}
// Check if $uploadOk is set to 0 by an error
if ($uploadOk == 0) {
$_SESSION['message'] .= "Your file was not uploaded.";
$result = 0 ;
} else {
if (move_uploaded_file($_FILES["file_to_mms"]["tmp_name"],
$target_file)) {
$filename = htmlspecialchars(
basename($_FILES["file_to_mms"]["name"])) ;
$result = $target_file ;
} else {
$_SESSION['message'] = "Sorry, there was an
error uploading your file.";
$result = 0 ;
}
}
}
return $result ;
}Part way through the function I get the $fileType, then I check the file size, and then I test the file extension against the allowed file types with the get_allowed_file_types() function that returns an array of allowed file extensions. If you look at the get_allowed_file_types() function you will see that I am merely returning a collection of arrays that are merged into one. You can also see what type of file extension is permitted within each category.
function get_allowed_file_types() {
$allowed_image_file_types = array("jpg", "png", "jpeg", "pdf", "bmp", "gif", "tiff", "tif", "svg", "webp", );
$allowed_video_file_types = array("3gp", "mp4", "m4v", "mpeg", "mpg", "avi", "flv", "wmv", "mov", "qt", "webm", "ogg", );
$allowed_audio_file_types = array( "mp3", "m4a", "oga", "wav",
"arm","3gp", );
$allowed_misc_file_types = array( "vcf", "vcard", "zip", "gzip", "rtf", "pdf", "html", "txt", "csv", "ics", );
return array_unique(array_merge($allowed_image_file_types,
$allowed_video_file_types, $allowed_audio_file_types,
$allowed_misc_file_types));
}You can manipulate this function to return only the image file types, for example, if you only wanted to allow those file types to be permitted within your code.
As I move through the various validity tests, I set a variable called $uploadok to 0 if there are any failures and I place a message explaining the error into the $_SESSION for later display. If all tests pass, then I return the filename with its full server path to the calling code.
Getting back to the calling code, if the upload_file() function returns without error we will have the uploaded file name and path in hand. We then call the send_mms() function passing it the mobile number, message body, and the uploaded file information. The function then actually attaches the file to a text message and sends it out as MMS. The code for the send_mms() function looks like the following:
function send_mms ($to_sms_number, $sms_message_body, $file_with_path) {
// Include Libraries
require('includes/vendor/autoload.php');
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
$fromNumber = $_ENV['RC_MOBILE_SENDING_NUMBER'];
$controller = ringcentral_sdk();
$platform = $controller['platform'];
$sdk = $controller['SDK'];
$bodyParams = array(
'from' => array( 'phoneNumber' => $fromNumber ),
'to' => array( array('phoneNumber' => $to_sms_number ) ),
'text' => $sms_message_body,
);
$endpoint = "/restapi/v1.0/account/~/extension/~/mms";
try {
$request = $sdk->createMultipartBuilder()
->setBody($bodyParams)
->add(fopen($file_with_path, 'r'))
->request($endpoint);
$resp = $platform->sendRequest($request);
$message_id = $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;
}
return $message_id;
}After we collect our environment information from the .env file, we establish a connection with the SDK and set some parameters that we will be sending to the API. The $endpoint variable is then set. Note the suffix of the endpoint is “mms” not “sms”. With all the settings ready, we then use the try / catch construct to actually send out the MMS message.
It should also be noted here that we are using a special method of the SDK called createMultipartBuilder(). We then pass a little more information to the method with the setBody, add, and request statements. This information is all loaded into a $request variable and then sent to the API platform with the sendRequest method. The last part of the process is that we collect the message id from the response for “proof” that the MMS message was actually sent out. If there are failures then the information can be captured in the catch section of the try / catch construct.
Returning to the calling code, if all goes well, we build a “success” message containing the MMS identifier and then using the unlink PHP function we delete the file that we uploaded to the web server to clean up after our work. Lastly, we redisplay the form with the success message on it.
A successful message would look like this. [1] is the mobile number that is receiving the MMS message, [2] is the body of the message, and [3] is the attached file, an image in this case.
The screen on the web form will look like this when successful, showing the message id of the sent message.
That is all there is to sending out an MMS message type with the RingCentral SMS API. Keep in mind the changed endpoint destination and the createMultipartBuilder() items that may be slight stumbling blocks. The API reference for this aspect of the SMS/MMS API can be found here.
The addition of more file types that can be added to an MMS message is quite valuable and the fact that you can add up to 10 different files is also a great value add. I hope that you can take my sample application and extend it to your own uses within your own business needs.
