Mobitel Business Solutions Company Confidential 1/22
MBS - mSMS Premier - API Doc - 20190329
mSMS Premier
API Document
Mobitel Business Solutions Company Confidential 2/22
MBS - mSMS Premier- API Do c - 20190329
Contents
Introduction ............................................................................................................................... 3
System and Access Credentials ................................................................................................... 3
Constrains and Restrictions ......................................................................................................... 3
Objects ....................................................................................................................................... 3
Web Methods .............................................................................................................................. 4
5.1 Web Method: SendBulk ....................................................................................................... 4
5.2 Web method: ViewBulkStatus ............................................................................................. 6
5.3 Web method: PauseCampaign .............................................................................................. 7
5.4 Web method: StopCampaign ................................................................................................ 8
5.5 Web method: RescheduleCampaign ................................................................................... 10
5.6 Web method: SendTestMessage ......................................................................................... 11
5.7 Web method: ViewStatistics .............................................................................................. 12
5.8 Web method: ViewInstantSMSStatus ................................................................................. 13
5.9 Web method: SendInstantSMS .......................................................................................... 14
5.10 Web method: ViewInstantCampaign_Status ...................................................................... 15
5.11 Web method: AddOptedNumbers ...................................................................................... 16
5.12 Web method: ViewOptedNumbers .................................................................................... 17
5.13 Web method: SendBulkWithTax ........................................................................................ 18
5.14 Web method: SendInstantSMSWithTax ............................................................................. 20
Response Codes ........................................................................................................................ 21
Mobitel Business Solutions Company Confidential 3/22
MBS - mSMS Premier - API Doc - 20190329
Introduction
Short Messaging Service (SMS) has gained tremendous popularity and widespread use. Many organizations use SMS for simple messaging, communication, CRM, e-commerce and transaction based applications. SMS is now one of the most ubiquitous and successful forms of communication.
SMS, also known as corporate SMS or business SMS, is the usage of text messaging in business applications such as mobile check-in, time-critical notifications, banking and commerce, etc.
The capability of providing 2-way SMS is also key for the success of SMS service in Enterprise environments. With the ability to send and receive SMS companies can guarantee full dialogue with customers, employees and other stakeholders.
System and Access Credentials
URL
https://msmsent.mobitel.lk/BulkSMS_v2/SendBulk?wsdl
Username
Password
Constrains and Restrictions
• Prior approval should be obtained from the service provider before using the send id.
• Number list containing more than 100000 numbers may take considerable time to give the submit response.
Objects
• Web Service Name: SendBulkSMS
• WSDL:
https://msmsent.mobitel.lk/BulkSMS_v2/SendBulk?wsdl
Mobitel Business Solutions Company Confidential 4/22
MBS - mSMS Premier- API Do c - 20190329
Web Methods
5.1 Web Method: SendBulk
SendBulk (SMS bulkSMS)
Please consider that, in this method tax calculation is disabled.
Type Parameters Description
SMS object
bulkSMS
Object of SMS class
SMS object contains following variables
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
account_no
Account number
String
send_id
Sender id
String
language
1 (English)
2 (Other)
String
campaign_owner
Campaign owner
String
campaign_owner_mobile
Campaign owner mobile number
String
sms_content
Message to be sent (should be a plain text less than 1520 character length)
String
bulk_start_date
Campaign start date.
(Format is yyyy-MM-dd hh:mm:ss)
String
bulk_end_date
Campaign validity ending date (Should be within 48 hours from the start date in yyyy-MM-dd hh:mm:ss format)
String
campaign_name
Campaign name
List<String>
number_list
List of numbers
String
add_block_notification
1 (Add block notification)
This is an optional parameter
Return type: method returns a string containing one of the following
Status Response
camp_key
Generated campaign key is returned if successfully inserted: If the Bulk message sending entry is successfully added
Mobitel Business Solutions Company Confidential 5/22
MBS - mSMS Premier - API Doc - 20190329
201
Error : Exception :if an exception occurred inside the web method
208
Invalid sms content: If the “sms_content” is not valid
209
Invalid send_id: If the “send_id” is not valid
210
Invalid user: If the “username” ,”password” values are not valid
214
Text file generation error
215
Number list error
218
Account number error
220
Validation Error: SMS is empty
221
Invalid SMS content
222
Invalid language
223
SMS contains null value
224
Invalid start date: Current time is after “bulk_start_date”
225
Invalid start date: If the “bulk_start_date” is not valid
226
Invalid end date :If the “bulk_end_date” is not valid
227
Invalid end date: “bulk_end_date” is not within 48 hours from “bulk_start_date”
228
Invalid dates : “bulk_end_date” is before “bulk_start_date” or both dates are same
Testing
Mobitel Business Solutions Company Confidential 6/22
MBS - mSMS Premier- API Do c - 20190329
Service can be tested through SoapUI. And please set the header when testing. Token and
Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.2 Web method: ViewBulkStatus
ViewBulkStatus (String username, String password, String from_date, String to_date)
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
from_date
Start date of added date
String
To_date
End date of added date
Return type: method returns a string containing one of the following
Status Response
210
Invalid user: If the “username” ,”password” values are not valid
201
Error : If an exception occurred inside the web method
225
Invalid start date: If the “bulk_start_date” is not valid
226
Invalid end date :If the “bulk_end_date” is not valid
228
Invalid dates : “bulk_end_date” is before “bulk_start_date” or both dates are same
If the user is valid, a json string containing the following details of the campaigns of that specific user of given date range will be returned.
• camp_key (Campaign key)
Mobitel Business Solutions Company Confidential 7/22
MBS - mSMS Premier - API Doc - 20190329
• added_datetime (Campaign added date)
• sheduled_datetime (Campaign Scheduled date)
• end_datetime (Campaign end date)
• cam_owner (Campaign owner)
• appr_id (Approved id)
• camp_Name (Campaign name)
• msg (Message content)
• sender (sender id)
• num_of_rec (Number of records in the number list)
• ttl_segments (Number of segments in the message)
• ttl_count
• del_count
• queue_count
• expire_count
• unpros_count
• current_status (Current status of the campaign)
5.3 Web method: PauseCampaign
PauseCampaign (String username, String password, String camp_key, String restart_date)
This method is only for bulk SMS campaign.
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
camp_key
Key of the campaign
String
restart_date
When to start the campaign after the pause (restart date should be a date before the “bulk end date” of that campaign in yyyy-MM-dd hh:mm:ss format)
Return type: method returns a string containing one of the following
Status Response
Mobitel Business Solutions Company Confidential 8/22
MBS - mSMS Premier- API Do c - 20190329
102
Successfully paused : If the campaign is successfully paused
201
Error : Exception :if an exception occurred inside the web method
202
campaign does not exist: Campaign id does not exist
203
not authorized to pause the campaign: User is not authorized to pause the campaign
210
Invalid user :If the “username” ,”password” values are not valid
212
Invalid restart date: Invalid “restart_date”
312
Invalid campaign status: Campaign cannot be paused because the campaign processing has not yet started.
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.4 Web method: StopCampaign
StopCampaign (String username, String password, String camp_key)
This method is only for bulk SMS campaign.
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
camp_key
Key of the campaign
Return type: method returns a string containing one of the following
Mobitel Business Solutions Company Confidential 9/22
MBS - mSMS Premier - API Doc - 20190329
Status Response
101
Successfully stopped :If the campaign is successfully stopped
201
Error : Exception :if an exception occurred inside the web method
202
campaign does not exist: Campaign id does not exist
204
not authorized to stop the campaign: User is not authorized to stop the campaign
210
Invalid user :If the “username” ,”password” values are not valid
211
Invalid campaign status: Campaign cannot be stopped because of invalid campaign status.
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
Mobitel Business Solutions Company Confidential 10/22
MBS - mSMS Premier - API Doc - 20190329
5.5 Web method: RescheduleCampaign
RescheduleCampaign (String username, String password, String camp_key, String reschedule_from_date, String reschedule_to_date)
This method is only for bulk SMS campaign.
Return type : method returns a string containing one of the following
Status Response
101
Successfully rescheduled : If the campaign is successfully rescheduled
201
Error : Exception :if an exception occurred inside the web method
202
campaign does not exist: Campaign id does not exist
205
not authorized to reschedule the campaign: User is not authorized to reschedule the campaign
210
Invalid user :If the “username” ,”password” values are not valid
211
Invalid campaign status: Campaign cannot be rescheduled because the campaign processing has started.
Mobitel Business Solutions Company Confidential 11/22
MBS - mSMS Premier - API Doc - 20190329
224
Invalid reschedule start date: Current time is after “reschedule_from_date”
225
Invalid reschedule start date: If the “reschedule_from_date” is not valid
226
Invalid reschedule end date :If the “reschedule_to_date” is not valid
227
Invalid reschedule end date: “reschedule_to_date” is not within 48 hours from “reschedule_from_date”
228
Invalid dates : “reschedule_to_date” is before “reschedule_from_date” or both dates are same
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.6 Web method: SendTestMessage
SendTestMsg (String username, String password, String camp_key, String mobile_number)
Return type : method returns a string containing one of the following
Status Response
101
Message successfully submitted: If the test message request is successfully submitted.
Mobitel Business Solutions Company Confidential 12/22
MBS - mSMS Premier - API Doc - 20190329
201
Error : Exception :if an exception occurred inside the web method
202
campaign does not exist: Campaign id does not exist
206
not authorized to send test Messages: User is not authorized to request a test message
210
Invalid user :If the “username” ,”password” values are not valid
217
Incorrect mobile number
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.7 Web method: ViewStatistics
ViewStatistics (String username, String password, String camp_key)
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
camp_key
Key of the campaign
Return type: method returns a string containing one of the following
Status Response
201
Error : Exception :if an exception occurred inside the web method
202
campaign does not exist :Campaign id does not exist
210
Invalid user :If the “username” ,”password” values are not valid
Mobitel Business Solutions Company Confidential 13/22
MBS - mSMS Premier - API Doc - 20190329
216
not authorized to view campaign details
If the user is valid and the campaign exists a json string containing the following details of the campaigns will be returned.
• camp_key (campaign key)
• processed (Number of processed numbers)
• num_errors (Number of errors)
• dupl_num (Number of duplicate numbers)
• pstatus (Processing status: “0” until all the numbers in the list are processed; “1” after all the numbers are processed)
• m2m (Number of Mobitel numbers)
• m2o (Number of non Mobitel umbers)
• idd (Number of IDD numbers)
5.8 Web method: ViewInstantSMSStatus
ViewInstantSMS_Status (String username, String password, String from_date, String to_date)
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
from_date
Start date of added date
String
to_date
End date of added date
Return type: method returns a string containing one of the following
Status Response
210
Invalid user:If the “username” ,”password” values are not valid
201
Error : Exception :if an exception occurred inside the web method
Mobitel Business Solutions Company Confidential 14/22
MBS - mSMS Premier - API Doc - 20190329
If the user is valid, a json string containing the following details of the campaigns of that specific user will be returned.
• Camp_key (Campaign key)
• added_datetime (Campaign added time)/
• sheduled_datetime (Campaign scheduled date)
• cam_owner (Campaign owner)
• sender (sender id)
• msg (Message content)
• val_datetime (Campaign validity ending date)
• current_status
• all_msgs (Number of all messages)
• num_error_count (Number of error messages)
current_status can be defined as follows
• Not Start : Not started to process
• Start : Started to process
• Complete : Completely loaded to smsc queues and sent complete
• Scheduled : Completely loaded to smsc queues but not send yet
• System Error : Tried but come up with error, need to recheck
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.9 Web method: SendInstantSMS
SendInstantSMS (SMS instantSMS)
Please consider that, in this method tax calculation is disabled.
Type Parameters Description
SMS object
bulkSMS
Object of SMS class
Mobitel Business Solutions Company Confidential 15/22
MBS - mSMS Premier - API Doc - 20190329
SMS object contains following variables
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
account_no
Account number
String
send_id
Sender id
String
language
1 (English)
2 (Other)
String
campaign_owner
Campaign owner
String
campaign_owner_mobile
Campaign owner mobile number
String
sms_content
Message to be sent (should be a plain text less than 1520 character length)
String
bulk_start_date
Campaign start date.
(Format is yyyy-MM-dd hh:mm:ss)
String
bulk_end_date
Campaign validity ending date (Should be within 48 hours from the start date in yyyy-MM-dd hh:mm:ss format)
String
campaign_name
Campaign name
List<String>
number_list
List of numbers
String
add_block_notification
1 (Add block notification)
This is an optional parameter
Return Types: same as the sendBulk method
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.10 Web method: ViewInstantCampaign_Status
ViewInstantCampaign_Status (String username, String password, String camp_key)
Type Parameters Description
Mobitel Business Solutions Company Confidential 16/22
MBS - mSMS Premier - API Doc - 20190329
String
username
User name of the account
String
password
Password of the account
String
camp_key
Key of the campaign
Return type: method returns a string containing one of the following
Status Response
201
Error : Exception :if an exception occurred inside the web method
202
campaign does not exist :Campaign id does not exist
210
Invalid user :If the “username” ,”password” values are not valid
216
not authorized to view campaign details
If the user is valid and the campaign exists a json string containing the following details of the campaigns will be returned.
Number of Delivered messages
Number of Queued messages
Number of Expired messages
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.11 Web method: AddOptedNumbers
addOptedNumbers(String username, String password, List<String> send_ids, List<String> numberList)
Mobitel Business Solutions Company Confidential 17/22
MBS - mSMS Premier - API Doc - 20190329
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
List<String>
send_ids
Send ids that need to be opted
List<String>
numberList
Phone Numbers that need to be opted
Return type: method returns a string containing one of the following
Status Response
213
Process is started. Numbers are started to check for correction. If there is large number list, it will take some time. You can check it from view opted numbers view after 5 minutes.
201
Error : Exception :if an exception occurred inside the web method
210
Invalid user :If the “username” ,”password” values are not valid
5.12 Web method: ViewOptedNumbers
viewOptedNumbers(String username, String password, List<String> send_ids, String start, String end)
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
List<String>
send_ids
Send ids
String
start
Start date
String
end
End date
Mobitel Business Solutions Company Confidential 18/22
MBS - mSMS Premier - API Doc - 20190329
Return type: method returns a string containing one of the following
Status Response
201
Error : Exception :if an exception occurred inside the web method
210
Invalid user :If the “username” ,”password” values are not valid
If the user is valid a json string containing the following details of the campaigns will be returned.
• sendId (send id)
• optedNum (opted number)
• smsBody (message)
• addedDate (opted date)
• user (opted by)
5.13 Web method: SendBulkWithTax
SendBulkWithTax (SMS bulkSMS)
Type Parameters Description
SMS object
bulkSMS
Object of SMS class
SMS object contains following variables
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
account_no
Account number
String
send_id
Sender id
String
language
1 (English)
2 (Other)
String
campaign_owner
Campaign owner
String
campaign_owner_mobile
Campaign owner mobile number
String
sms_content
Message to be sent (should be a plain text less than 1520 character length)
String
bulk_start_date
Campaign start date.
(Format is yyyy-MM-dd hh:mm:ss)
String
bulk_end_date
Campaign validity ending date (Should be within 48 hours from the start date in yyyy-MM-dd hh:mm:ss format)
String
campaign_name
Campaign name
List<String>
number_list
List of numbers
Mobitel Business Solutions Company Confidential 19/22
MBS - mSMS Premier - API Doc - 20190329
String
add_block_notification
1 (Add block notification)
This is an optional parameter
String
enableTax
1 – tax is added
2 – tax isn’t added
(default value is 1)
Return type: method returns a string containing one of the following
Status Response
camp_key
Generated campaign key is returned if successfully inserted: If the Bulk message sending entry is successfully added
201
Error : Exception :if an exception occurred inside the web method
208
Invalid sms content: If the “sms_content” is not valid
209
Invalid send_id: If the “send_id” is not valid
210
Invalid user: If the “username” ,”password” values are not valid
214
Text file generation error
215
Number list error
218
Account number error
220
Validation Error: SMS is empty
221
Invalid SMS content
222
Invalid language
223
SMS contains null value
Mobitel Business Solutions Company Confidential 20/22
MBS - mSMS Premier - API Doc - 20190329
224
Invalid start date: Current time is after “bulk_start_date”
225
Invalid start date: If the “bulk_start_date” is not valid
226
Invalid end date :If the “bulk_end_date” is not valid
227
Invalid end date: “bulk_end_date” is not within 48 hours from “bulk_start_date”
228
Invalid dates : “bulk_end_date” is before “bulk_start_date” or both dates are same
229
Incorrect value for enableTax
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and
Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
5.14 Web method: SendInstantSMSWithTax
SendInstantSMSWithTax (SMS instantSMS)
Type Parameters Description
SMS object
bulkSMS
Object of SMS class
SMS object contains following variables
Type Parameters Description
String
username
User name of the account
String
password
Password of the account
String
account_no
Account number
String
send_id
Sender id
String
language
1 (English)
2 (Other)
String
campaign_owner
Campaign owner
String
campaign_owner_mobile
Campaign owner mobile number
Mobitel Business Solutions Company Confidential 21/22
MBS - mSMS Premier - API Doc - 20190329
String
sms_content
Message to be sent (should be a plain text less than 1520 character length)
String
bulk_start_date
Campaign start date.
(Format is yyyy-MM-dd hh:mm:ss)
String
bulk_end_date
Campaign validity ending date (Should be within 48 hours from the start date in yyyy-MM-dd hh:mm:ss format)
String
campaign_name
Campaign name
List<String>
number_list
List of numbers
String
add_block_notification
1 (Add block notification)
This is an optional parameter
String
enableTax
1 – tax is added
2 – tax isn’t added
(default value is 1)
Return Types: same as the sendBulk method
Testing
Service can be tested through SoapUI. And please set the header when testing. Token and Timestamp can be generated from SoapUI or using IDEs. (Eg:NetBeans)
Response Codes
Response Code
Successfully inserted
101
Successfully paused
102
Error
201
campaign does not exist
202
not authorized to pause the campaign
203
not authorized to stop the campaign
204
not authorized to reschedule the campaign
205
Mobitel Business Solutions Company Confidential 22/22
MBS - mSMS Premier - API Doc - 20190329
not authorized to send test Messages
206
Invalid sms content
208
Invalid send_id
209
Invalid user
210
Invalid campaign status
211
Invalid restart date
212
Text file generation error
214
Number list error
215
Not authorized to view campaign details
216
Incorrect mobile number
217
Account number error
218
Validation Error: SMS is empty
220
Invalid SMS content
221
Invalid language
222
SMS contains null value
223
Invalid start date: Current time is after
“bulk_start_date”
224
Invalid start date: If the “bulk_start_date” is not
valid
225
Invalid end date :If the “bulk_end_date” is not
valid
226
Invalid end date: “bulk_end_date” is not within
48 hours from “bulk_start_date”
227
Invalid dates : “bulk_end_date” is before
“bulk_start_date” or both dates are same
228
Invalid campaign status
312
Incorrect value for enableTax
229