“Whoever controls the media, controls the mind”
Jim Morrison
In my recent article, Building Communications Applications With Avaya OneCloud CPaaS, I presented three different ways of how to write an outbound SMS text campaign application. I used an Excel spreadsheet as a “database” and the Avaya CPaaS Send SMS API to send text messages. Almost immediately, I was asked to extend my solution to send images along with the text. This article is my programmatic response.
SMS (Short Message Service) is the text message service of most telephone, Internet, and mobile device systems and MMS (Multimedia Messaging Service) enables the sending of multimedia content on those same networks. To enhance my campaign application to support images, I need to replace the SMS API call with its MMS equivalent.
As with the SMS API, I need to pass To, From, and Message Body as POST parameters. I also need to pass the URL of the image I wish to send. Although hosting the image prior to sending it might seem cumbersome, both Twilio and Telynx (two major SMS/MMS providers) implement their APIs in the same way. For this proof-of-concept application, I hosted my images on Post Images.
To support passing the image URL to my application, I added it as a fourth column in my campaign spreadsheet. It now looks like this:
I left the message the same as my SMS-only example, but it can be changed to anything you want it to be.
The results of executing the application with the above data looks like this on Caroline’s iPhone:
At this point, rewriting the SMS version of the application is straightforward. I simply took a look at the MMS API documentation and made the appropriate changes.
Note. I chose to write this application using REST. Refer back to my SMS example to see how it could be written using the CPaaS node.js helper library.
/*
This program reads in a list of names, text numbers, messages, and image URLs from an Excel file. It then loops through the list to:
- Send campaign message and image to text number.
- After sending message and image, pause for one second. This avoids hitting CPaaS MMS rate limit
*/
const xlsx = require('node-xlsx'); // npm install node-xlsx
const request = require('request-promise');
// Set the following to match your environment
const CPAAS_URL = "https://api-us.cpaas.avayacloud.com/v2/Accounts/";
const CPAAS_USER = "CPaaS Account SID";
const CPAAS_TOKEN = "CPaaS Auth Token";
const CPAAS_FROM = "CPaaS MMS capable telephone number in E.164 format";
const EXCEL_FILE = "Excel File name";
const CPAAS_SEND_MMS = "/MMS/Messages.json"
// Parse the Excel file
const workSheetsFromFile = xlsx.parse(EXCEL_FILE);
/*
Excel file must be in form of:
Name | 10-digit Number | Message | Image URL
Name | 10-digit Number | Message | Image URL
Name | 10-digit Number | Message | Image URL
.
.
.
xlsx.parse will create a JSON object that looks like this:
[ { name: 'Sheet1', data: [ [name, number, message, URL], [name, number, message, URL], [name, number, message, URL] ] } ]
*/
sendTextMessages(workSheetsFromFile[0].data);
async function sendTextMessages(data) {
const auth = "Basic " + Buffer.from(`${CPAAS_USER }:${CPAAS_TOKEN}`, "utf-8").toString("base64");
for (let i in data) {
toName = data[i][0];
toNumber = `+1${data[i][1].toString()}`; // +1 for E.164 format
campaignMessage = data[i][2];
message = `Hello, ${toName}. ${campaignMessage}`;
image = data[i][3];
options = {
url: `${CPAAS_URL}${CPAAS_USER}${CPAAS_SEND_MMS}`,
body: `From=${CPAAS_FROM}&To=${toNumber}&Body=${message}&MediaUrl=${image}`,
headers: {'Content-Type' : 'text/plain', 'Accept' : 'application/json', 'Authorization' :auth},
method: 'POST'
}
var response = await request.post(options, function(e , r , body) {
});
// To avoid hitting CPaaS rate limit, pause for one second between new messages
await new Promise(resolve => setTimeout(resolve, 1000));
}
}
For all my Python programming friends, here is the same application written using the Avaya CPaaS Python Helper Library.
from zang import ZangException, Configuration, ConnectorFactory
import openpyxl
import time
# Set the following to match your environment
CPAAS_USER = "CPAAS Account SID"
CPAAS_TOKEN = "CPaaS Auth Token"
EXCEL_FILE = "Excel File"
CPaaS_Phone = "CPaaS Telephone Number in E.164 Format"
CPAAS_URL = "https://api-us.cpaas.avayacloud.com/v2"
configuration = Configuration(CPAAS_USER, CPAAS_TOKEN, url = CPAAS_URL)
mmsMessagesConnector = ConnectorFactory(configuration).mmsMessagesConnector
# Load spreadsheet and obtain active sheet
wb = openpyxl.load_workbook(EXCEL_FILE)
sheet_obj = wb.active
# Obtain the number of rows in the spreadsheet
m_row = sheet_obj.max_row
# Loop through the spreadsheet
for i in range(1, m_row + 1):
# Retrieve cells for row i
name_cell = sheet_obj.cell(row = i, column = 1)
phone_cell = sheet_obj.cell(row = i, column = 2)
message_cell = sheet_obj.cell(row = i, column = 3)
image_cell = sheet_obj.cell(row = i, column = 4)
# Retrieve the values of each cell
name = name_cell.value
number = "+1" + str(phone_cell.value) # +1 for E.164 format
message = 'Hello, ' + name + '. ' + message_cell.value
image = image_cell.value
# Send sms message
try:
mmsMessage = mmsMessagesConnector.sendMmsMessage(
to = number,
body = message,
from_ = CPaaS_Phone,
mediaUrl = image)
except ZangException as ze:
print(ze)
# To avoid hitting CPaaS rate limit, pause for one second between new messages
time.sleep(1)
Mischief Managed
I don’t know much about the technical mechanics of how images are sent to a mobile device, but with Avaya CPaaS APIs, I don’t need to. A basic understanding of webservices programming is all that’s required to create powerful, communications-infused applications.
In order to make this easy to digest, I presented a very simple application. However, there is no reason to stop there. Sending multimedia text messages is useful in many different use cases. For fun, I wrote a “dog bot” application that allows people to request images of different dog breeds. Ask for a beagle and you get a beagle. It’s not difficult to envision applications of far more commercial value.
As always, feel free to reach out to me with any questions you might have.
Tao, Zen, and Tomorrow 