Plivo SMS gateway API in ColdFusion

In one of my project there was some requirement to send receive SMS using Plivo( http://plivo.com/ ) SMS gateway. Plivo doesn't provides any documentation for integration with ColdFusin but it's not so difficult to do as you will see below. So, I thought to provide the exact implementation in ColdFusion it might save save you time.

Before going to coding part we must have the credential for Plivo SMS gateway. :)

This SMS API integration have 2 parts:

- Send SMS and get Sent/Received SMS details(from,to,message id, time).
- Receive inbound SMS and initiate some ColdFusion logic.

1. Send SMS and get Sent/Received SMS details

You can download the code from below URL directly.  https://gist.github.com/roulupen/153845250fdab07c82bc or you can look for the below code.

	<!---
	Name : PlivoManager.cfc (v1)
	Author : Upendra Roul
	Created : Monday, July 15, 2013
	Last Updated : Monday, July 15, 2013
	History : Got Started!
	--->
	<cfcomponent name="PlivoManager" displayName="PlivoManager" hint="Contains all functions related to Plivo SMS gateway " output="false">
	<cfset this.APISettings = structNew() />
	<cfset this.APISettings['ROOT_URL'] = "https://api.plivo.com/v1/Account/" />
	<cfset this.APISettings['AUTH_ID'] = "" />
	<cfset this.APISettings['AUTH_TOKEN'] = "" />
	<cffunction name="init" description="Constructs the Plivo Manager Object." returnType="PlivoManager" access="public" output="false">
	<cfargument name="rootURL" required="false" type="string" hint="Root URL" />
	<cfargument name="authID" required="false" type="string" hint="Auth ID of Plivo Account" />
	<cfargument name="authToken" required="false" type="string" hint="Auth Token of Plivo Account" />
	<cfscript>
	//Set Root URL
	if( structKeyExists(arguments, "rootURL") AND len(arguments.rootURL) )
	this.APISettings['ROOT_URL'] = arguments.rootURL;
	//Set AuthID for HTTP call validation at plivo server
	if( structKeyExists(arguments, "authID") AND len(arguments.authID) )
	this.APISettings['AUTH_ID'] = arguments.authID;
	//Set AuthToken for HTTP call validation at plivo server
	if( structKeyExists(arguments, "authToken") AND len(arguments.authToken) )
	this.APISettings['AUTH_TOKEN'] = arguments.authToken;
	return this;
	</cfscript>
	</cffunction>
	<cffunction name="sendSMS" description="Sends SMS to different no using Plivo API" returntype="Struct" access="public" output="false">
	<cfargument name="srcPhoneNo" required="true" type="string" hint="The sender phone number which is used as caller ID" />
	<cfargument name="destPhoneNo" required="true" type="string" hint="The phone number(s) to whom message(s) would be sent" />
	<cfargument name="messageBody" required="true" type="string" hint="The message body" />
	<!---
	Send SMS API call can send multiple SMS to different numbers at a time but needs to take care few points.
	- If doesn't support any +,- or space in the number. Ex- +1 123-456-6789 is invalid. 11234566789 is valid format.
	- Multiple no must be separated by a delimeter "<"
	- If in a group of phone no any one no format is wrong then SMS sending feature will fail for all numbers in that group.So take care of these things.
	--->
	<cfscript>
	local.httpResult = structNew();
	local.sendSMSStatus = structNew();
	local.sendSMSStatus.content = structNew();
	local.sendSMSStatus.status = "0";
	local.sendSMSStatus.message = "";
	</cfscript>
	<cftry>
	<!--- Replcaing all '+', '-', ' ' sign from the dest address as this is not supported in the API --->
	<cfset local.destPhoneNo = replace(replace(replace(arguments.destPhoneNo, '+', '', 'all'), '-', '', 'all'), ' ', '', "all") />
	<!--- Validate Phone nos in group --->
	<cfset local.destPhoneNo = validateCellNumberInGroup(local.destPhoneNo) />
	<!--- Replacing any leading or trailing delimters if it is present --->
	<cfset local.destPhoneNo = reReplace(reReplace(local.destPhoneNo, "<+$", ""), "^<+", "") />
	<!--- If after formatting the phone no. Length of the phone no becomes 0 then return message that invalid phone no --->
	<cfif !len(trim(arguments.destPhoneNo))>
	<cfset local.sendSMSStatus.status = 0 />
	<cfset local.sendSMSStatus.message = "Invalid phone no: #arguments.destPhoneNo#" />
	<cfreturn local.sendSMSStatus />
	</cfif>
	<!--- Parameters for HTTP call --->
	<cfset local.requestBody = { 'src' = arguments.srcPhoneNo, 'dst' = local.destPhoneNo, 'text' = arguments.messageBody, 'type' = 'sms' } >
	<!--- API call to send SMS --->
	<cfhttp method="post" url="#this.APISettings['ROOT_URL']##this.APISettings['AUTH_ID']#/Message/" result="local.httpResult">
	<cfhttpparam type="header" name="Authorization" value="Basic #ToBase64("#this.APISettings['AUTH_ID']#:#this.APISettings['AUTH_TOKEN']#")#" />
	<cfhttpparam type="header" name="Content-Type" value="application/json" />
	<cfhttpparam type="body" value="#serializeJSON(local.requestBody)#" />
	</cfhttp>
	<!--- Process the returned result --->
	<cfif structKeyExists(local.httpResult, "Responseheader") AND structKeyExists(local.httpResult.Responseheader, "Status_Code")>
	<cfif ( trim(local.httpResult.Responseheader.Status_Code) EQ '202' ) >
	<cfset local.sendSMSStatus.content = duplicate( deserializeJSON( local.httpResult.Filecontent.toString() ) ) />
	<cfset local.sendSMSStatus.status = "1" />
	<cfelse>
	<cfthrow type="Application" message="#local.httpResult.Statuscode#" detail="Header: #local.httpResult.Header# File Content: #local.httpResult.Filecontent.toString()#" />
	</cfif>
	</cfif>
	<cfcatch>
	<cfscript>
	//Log the error details
	//Set return parameter
	local.sendSMSStatus.status = "0";
	local.sendSMSStatus.message = cfcatch.Message;
	</cfscript>
	</cfcatch>
	</cftry>
	<cfreturn local.sendSMSStatus />
	</cffunction>
	<cffunction name="getSentRecievedSMSs" description="Gets sent and recieved SMSs from the server" returntype="Struct" access="public" output="false">
	<cfargument name="limit" required="false" type="numeric" default="1" hint="No of sent sms wants to get from server" />
	<cfargument name="offset" required="false" type="numeric" default="0" hint="SMS start count" />
	<cfscript>
	local.httpResult = structNew();
	local.recieveSMSs = structNew();
	local.recieveSMSs.content = structNew();
	local.recieveSMSs.status = "0";
	local.recieveSMSs.message = "";
	</cfscript>
	<cftry>
	<!--- API call to recieve multiple SMS --->
	<cfhttp method="get" url="#this.APISettings['ROOT_URL']##this.APISettings['AUTH_ID']#/Message/" result="local.httpResult">
	<cfhttpparam type="header" name="Authorization" value="Basic #ToBase64("#this.APISettings['AUTH_ID']#:#this.APISettings['AUTH_TOKEN']#")#" />
	<cfhttpparam type="header" name="Content-Type" value="application/json" />
	<cfhttpparam type="url" name="limit" value="#arguments.limit#" />
	<cfhttpparam type="url" name="offset" value="#arguments.offset#" />
	</cfhttp>
	<!--- Process the returned result --->
	<cfif structKeyExists(local.httpResult, "Responseheader") AND structKeyExists(local.httpResult.Responseheader, "Status_Code")>
	<cfif ( trim(local.httpResult.Responseheader.Status_Code) EQ '200' ) >
	<cfset local.recieveSMSs.content = duplicate( deserializeJSON( local.httpResult.Filecontent.toString() ) ) />
	<cfset local.recieveSMSs.status = "1" />
	<cfelse>
	<cfthrow type="Application" message="#local.httpResult.Statuscode#" detail="Header: #local.httpResult.Header# File Content: #local.httpResult.Filecontent.toString()#" />
	</cfif>
	</cfif>
	<cfcatch>
	<cfscript>
	//Log the error details
	//Set return parameter
	local.recieveSMSs.status = "0";
	local.recieveSMSs.message = cfcatch.Message;
	</cfscript>
	</cfcatch>
	</cftry>
	<cfreturn local.recieveSMSs />
	</cffunction>
	<cffunction name="getSMSDetails" description="Get a sent or recieved SMS from the server" returntype="Struct" access="public" output="false">
	<cfargument name="SMSID" required="true" type="string" hint="Unquique SMS identifier" />
	<cfscript>
	local.httpResult = structNew();
	local.recieveSMS = structNew();
	local.recieveSMS.content = structNew();
	local.recieveSMS.status = "0";
	local.recieveSMS.message = "";
	</cfscript>
	<cftry>
	<!--- If empty string passed in SMS string then throw error --->
	<cfif NOT len(arguments.SMSID)>
	<cfthrow type="Application" message="SMS ID can't be empty string" />
	</cfif>
	<!--- API call to recieve a SMS --->
	<cfhttp method="get" url="#this.APISettings['ROOT_URL']##this.APISettings['AUTH_ID']#/Message/#trim(arguments.SMSID)#/" result="local.httpResult">
	<cfhttpparam type="header" name="Authorization" value="Basic #ToBase64("#this.APISettings['AUTH_ID']#:#this.APISettings['AUTH_TOKEN']#")#" />
	<cfhttpparam type="header" name="Content-Type" value="application/json" />
	</cfhttp>
	<!--- Process the returned result --->
	<cfif structKeyExists(local.httpResult, "Responseheader") AND structKeyExists(local.httpResult.Responseheader, "Status_Code")>
	<cfif ( trim(local.httpResult.Responseheader.Status_Code) EQ '200' ) >
	<cfset local.recieveSMS.content = duplicate(deserializeJSON( local.httpResult.Filecontent.toString() )) />
	<cfset local.recieveSMS.status = "1" />
	<cfelse>
	<cfthrow type="Application" message="#local.httpResult.Statuscode#" detail="Header: #local.httpResult.Header# File Content: #local.httpResult.Filecontent.toString()#" />
	</cfif>
	</cfif>
	<cfcatch>
	<cfscript>
	//Log the error details
	//Set return parameter
	local.recieveSMS.status = "0";
	local.recieveSMS.message = cfcatch.Message;
	</cfscript>
	</cfcatch>
	</cftry>
	<cfreturn local.recieveSMS />
	</cffunction>
	<cffunction name="validateCellNumberInGroup" description="Takes list of cell phone no and remove and invalid no from the list and return the valid no list" returntype="string" access="public" output="false">
	<cfargument name="strInputNoList" required="true" type="string" hint="Input Cell Phone no list" />
	<cfargument name="delimeter" required="false" type="string" default="<" hint="Delimiter of the cell phone list" />
	<cfset local.returnList = arguments.strInputNoList />
	<cfset local.cellPhone = "" />
	<cftry>
	<!--- Loop over entire list and finds invalid cell phone no and delete that from the return list --->
	<cfloop list="#arguments.strInputNoList#" index="local.cellPhone" delimiters="#arguments.delimeter#">
	<cfif NOT isValid("telephone", local.cellPhone)>
	<cfset local.returnList = listDeleteAt( local.returnList, listFind( local.returnList, local.cellPhone, arguments.delimeter ), arguments.delimeter ) />
	</cfif>
	</cfloop>
	<cfcatch type="Any" >
	<cfscript>
	//Log the error details
	local.returnList = arguments.strInputNoList;
	</cfscript>
	</cfcatch>
	</cftry>
	<cfreturn local.returnList />
	</cffunction>
	</cfcomponent>

view raw PlivoManager.cfc hosted with ❤ by GitHub

2. Receive inbound SMS and initiate some ColdFusion logic

For receiving SMS instantly you need to make the following set up in Plivo server.
Login to Plivo Account - > Numbers

Then you will see the following screen.

So, here you can see the no linked to your Application and click on the "Demo Play" it may be different for you. Then you will see the following screen.

In the above screen you have to set the Message URL and Message method to receive the incoming message to your application

So, here I can set:
Message URL as: http://myplivotesting.com/receiveMessage.cfm
Message Method: POST/GET

So, when one incoming message will come Plivo will make a HTTP call to that particular URL. So, what are the fields we will get?

As shown in the above image you will get the red marked form fields form the Plivo Server and other fields are generated by my application.

So, you can write your logic in receiveMessage.cfm file to receive SMS make perform your business logic.

Hope it will save your time.
For detail API information please visit following URL:  http://plivo.com/docs/api/message/