An HTTP based Bulk SMS API for Mobicents

Recently, I have been working on a Bulk SMS Service implemented within Mobicents that allows external systems to communicate with it via HTTP. The service, in fact, is two services in one. The first service is a network-hosted address book that allows users to manage their own contact lists. For this, the service makes use of the Mobicents XDMS which comes with native XCAP resource list  support. The second service is the actual SMS service that receives requests to send SMSes. Each request must specify a list of recipients that can be specified individually or as a group that contains several members. This post describes the version 1.0 of the API that I have created and how it behaves. In a subsequent post, I will be providing details of the actual implementation and how extensions will be factored in for version 1.1.

Basic Structure and Parameters
All requests are HTTP GET requests. The basic structure of the request that is sent to Mobicents is as follows:

http://hostname:port/mobicents?username=foo&password=bar&type=[document|group|contact|sms] &op=[add|edit|del|send] [&parameters]

In the above request format, the hostname and port number are those of the Mobicents instance that is running the service. The “mobicents” subpath maps onto the Mobicents HTTP servlet connector that is associated with the service.
The mandatory parameters are:

• username - The username of the user.
• password - The password of the user.
• type - The type of data that is being managed. Legal values are “document”, “group” and “contact” for managing contact list documents, contact groups and individual contacts respectively, and “sms” for generating functions.
• op - The type of operation that is being attempted. Legal values are “add”, “edit” and “del” for managing contact information, and “send” for sending SMSes.

Contact List Management
A contact list refers to a document that is hosted on a document management server that contains user contact details. An HTTP request from an external system can be made to manage such documents. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=document&op=[add|del]

A contact list document can either be created or deleted. When a new contact list is created, a single contact group named “Ungrouped” is automatically created in the user’s contact list. The add operation is idempotent, meaning multiple executions do not change the state of the document from how it is when it is initially created. The delete operation can be executed on non-empty documents, that is documents that contain contacts in the Ungrouped group or other groups.

Group Management
An HTTP request from an external system can be made to modify a contact group that a user has defined. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=group&op=[add|edit|del] &group=group [&newgroup=newgroup]

An group management request is indicated by assigning the value “group” to the type parameter. Contact groups can be added, edited and deleted. It is assumed that each contact group has a name and consists of zero or more contacts. There is an additional parameter that can be specified when the name of an existing group is being edited:

• newgroup - The new name being allocated to an existing group.

Next, some examples are given of how these requests should be structured for given operations.


To create a new contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=group&op=add&group=Friends

To change the name of the contact group called Friends to Close Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=group&op=edit&group=Friends&newgroup=Close%20Friends

To delete the contact group named Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=group&op=del&group=Friends

Contact Management
An HTTP request from an external system can be made to modify the details pertaining to a given contact. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=contact&op=[add|edit|del]&name=name&number=number [&parameters]

Contacts can be added, edited, deleted and removed from a group or multiple groups. In addition to the general mandatory parameters listed previously, contact management requests must specify a name and a contact number since these parameters identify a contact uniquely. There are other parameters that can be specified depending on the type of operation that is being attempted.

• group - The group name that a contact currently belongs to, is to be inserted into or is to be removed from. 
• newname - The new name to be allocated to an existing contact.
• newnumber - The new contact number to be allocated to an existing contact.

Next, some examples are given of how these requests should be structured for given operations.


To add a new contact named John Doe with mobile number 0786346927, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=add&name=John%20Doenumber=0786346927

In this case a group is not specified, so the contact is allocated to the Ungrouped group in the contact list. To change John Doe’s name to Peter Doe, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=edit&name=John%20Doe&number=0786346927&newname=Peter%Doe

To change John Doe’s mobile number to 0786346920, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=edit&name=John%20Doe&number=0786346927&newnumber=0786346920

To delete John Doe entirely from the contact list, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=del&name=John%20Doe&number=0786346927

To add a new contact named Alice Wonderland with mobile number 0786346928 to a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=add&name=Alice%20Wonderland&number=0786346928&group=Friends

To remove Alice Wonderland from a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=contact&op=del&name=Alice%20Wonderland&number=0786346928&group=Friends


User Profile Management
This document does not define any user profile management methods. It is anticipated that version 1.1 of the API document will define and support them.

SMS Generation
An HTTP request from an external system can be made to send an SMS through Mobicents. The structure of the request must accord with the following:

http://hostname:port/mobicents?username=foo&password=bar&type=sms&op=sendto=nums&group=group&text=text [&report=bool]
The SMS service has the same mandatory parameters defined is Section previously. It also defines the following parameters:

• to - The number or list of numbers to send the SMS to.
• group - The contact group of list of groups to send the SMS to.
• text - The body of the SMS message.
• report - A boolean flag for SMS delivery reports.

When sending an SMS, either the to parameter or the group parameter must be specified, or both. If the SMS is intended for multiple recipients, the contact numbers must be separated by the ’+’ character in the to parameter. Likewise, if the SMS is intended for multiple groups, the group names must be separated by the ’+’ parameter in the group parameter. Only the values “true” and “false” are valid for the report parameter. Assigning the value “false” to the report  parameter is the same as not setting this parameter in the request at all. Next, some examples are given of how these requests should be structured for given operations.

To send an SMS to a user with the mobile number 0786346927, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927&text=This+is+the+text

To send an SMS to the numbers 0786346927, 0786346928 and 0786346929, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927+0786346928+0786346929&text=This+is+the+text

To send an SMS to the numbers 0786346927, 0786346928 and 0786346929 and request a delivery report, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927+0786346928+0786346929&text=This+is+the+text&report=true

To send an SMS to a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send




To send an SMS to the mobile numbers 0786346927, 0786346928 and 0786346929 in addition to a contact group called Friends, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&to=0786346927+0786346928+0786346929&group=Friends&text=This+is+the+text


In such cases, Mobicents is responsible for ensuring that an SMS is not sent more than once to a group contact that is already explicitly listed in the to parameter.

To send an SMS to the groups Friends, Close Friends and Family, the following request is issued:

http://hostname:port/mobicents?username=mos&password=1234$&type=sms&op=send&groups=Friends+Close%20Friends+Family&text=This+is+the+text


Error Conditions
There are a number of operations that can lead to error conditions. They are gracefully handled by Mobicents. Mobicents defines exceptions that are thrown when the processing of a request can lead to an error condition.


Too Few Parameters - This error condition arises when the request that is received is missing one or more of the mandatory parameters that have been defined previously. In response to this, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 432: Missing Mandatory Parameter in the request - Check API manual”. For example, the following request will generate such a response:

http://hostname:port/mobicents?password=bar&type=contact&op=add&name=name&number=number

Parameter missing a value - This error condition arises when the request that is received is missing a value for any parameter that is specified in the request. In response to this, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 433: Malformed URL - Missing Parameter Value - Check API manual”. For example,
the following request will generate such a response:

http://hostname:port/mobicents?username=foo&password=bar&type=&op=add &name=name&number=number&group=Friends

Unknown Parameter - This error condition arises when the request specifies a value that is not part of the pre-defined values for the service. In response to this, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 434: Unknown Parameter in the request - Check API manual”. For example, the following request will generate such a response:

http://hostname:port/mobicents?username=foo&password=bar&type=sms&op=send&group=Friends&text=This+is+the+text&ussd=true


Invalid Request - This error condition arises in a number of different cases where the request is not formatted correctly for the type of operation that is being attempted. A request that violates any of the following rules fits into this category:

• When creating a document, the only legal operations are add, edit and delete. 
• When adding a new group, the group name must be specified.
• When editing a group, both an existing group name and new group name must be specified.
• When deleting a group, the group name must be specified.
• When adding a new contact, both the name and the contact number must be specified.
• When editing a contact’s name, both the existing name and new name must be specified.
• When editing a contact’s number, both the existing number and the new number must be specified.
• When deleting a contact, both the name and the contact number must be specified.

In response to any of these conditions, Mobicents will send an HTTP response back to the requesting system with the following message: “HTTP Error 435: Illegal operation - Check API manual regarding: [error message]”.