Bulk SMS XML API


	System Requirements
	Notice Regarding Characters To Be Used
	Notice Regarding Standard Language Translation
	Notice Regarding Usage of Action Basing on Character Count
	Notice Regarding Method for Sending Bulk SMS
	Notice Regarding Status Control for Reporting
	Error Codes


	User Information Control
	Notice Regarding GSM Number Format
	Notice Regarding Sender Information Usage
	Notice Regarding Character Control for Messages With More Than 160 Characters
	Notice Regarding Reporting
	Notice Regarding OTP Service Usage
	XML API Sample Codes

General

Mobildev XML Interfaces were developed for software developers who deal with XML documents. With Mobildev XML Interfaces, you can easily integrate sending of SMS into your applications.

Software developers prefer our solution as it is a tool that is supported by every operating system platform and as it is usable with every IDE.

Software developers who can prepare an XML statement using the information provided in this document will be able to send their own XMLHTTP request to http://gateway.mobilus.net/com.mobilus (will be referred to as Gateway). Once the XML statement is sent, it will be processed by XML Parser. If any error is found within the XML statement or within the parameter nodes; a predefined error code will be returned to the sender over http. If there are no errors, an appropriate return statement will be prepared and sent back to the sender. Predefined error codes will be explained in detail within the document.

System Requirements

Following is the minimum system requirements list in order to use Mobildev XML API solution:

Windows 98 SE, ME, 2000, XP, UNIX, Linux or MacOS
Internet Explorer 6 SP1 (for Windows platform)
cURL library (for developers using PHP)

User Information Control

Before starting with sending SMS, SMS user information control must be carried out. If you don’t have a current SMS account please click here to obtain a test account from Mobildev Customer Services.

When Gateway receives the user information, the system verifies it and sends credit and originator information associated with it. During verification of the user information, username, company code, password and action information is checked.

Username: is your Mobildev SMS user name.
Company Code: is your channel information associated with your SMS user name –also known as client code-.
Password: is your SMS password.
Action: is the numerical parameter node stating the function for which the Gateway XML statement was sent.

After checking the information sent to Gateway, 01 Error Code will be returned if the information is not correct. Error Code 01 means that one or all of the following is incorrect: user name – password – company code. In this case, please contact with Mobildev Technical Support Team and check your login details.

An XML statement must contain the following lines for user information control:
<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>4</Action> </MainReportRoot>
Sample XML Statement For Information Control:
<MainReportRoot> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>4</Action> </MainReportRoot>

After the information sent to Gateway is checked, the below values will be returned if the information is correct:

Credits remaining<10> Originator1<10> Originator2<10> OriginatorN

Notice Regarding Characters To Be Used

During sending, the below is not allowed:

Turkish characters (ç,ş,ü,ö,ğ,Ç,Ü,Ş,Ğ,Ö,İ) .
~, ^^, &, <, >, €, £, ã, Ã, ‰, €, ©, ®, ∞, ° signs
LineFeed, Enter, Tab commands

Within a message, only the following characters are allowed: ( ) [ ] { } = * ? \ / % + # ! ” : ; _ |

Notice Regarding GSM Number Format

GSM numbers must be formatted as 05321234567, 5321234567, 905321234567 and written within Numbers parameter node. 04 Error Code will be returned should the GSM numbers are not in appropriate format. Error Code 04 means that the GSM number format is incorrect. In this case, please consider checking the information quoted under Notice Regarding GSM Number Format.

Sample Usage:

<Numbers>05321234567</Numbers> <Numbers>5321234567</Numbers> <Numbers>905321234567</Numbers>

Notice: You cannot send should you format numbers as +905321234567, 532 123 45 67, +05321234567 and use -, ( ), [ ], { } etc. characters.

Notice Regarding Standard Language Translation

If non-ASCII (American Standard Code for Information Interchange) characters were used within the text, use of a language translator will be necessary.

Sample Translator Code:

public static string ConvertMessage(string    message)
 {
 message =    message.Replace("Ü", "U");
 message =    message.Replace("ü", "u");
 message =    message.Replace("Ğ", "G");
 message =    message.Replace("ğ", "g");
 message =    message.Replace("İ", "I");
 message =    message.Replace("ı", "i");
 message = message.Replace("Ş",    "S");
 message =    message.Replace("ş", "s");
 message =    message.Replace("Ç", "C");
 message =    message.Replace("ç", "c");
 message =    message.Replace("Ö", "O");
 message =    message.Replace("ö", "o");
 message =    message.Replace("é", "e");
 message =    message.Replace("`", "'");
 message =    message.Replace("^", "'");
 message =    message.Replace("…", ".");
 message =    message.Replace("ˆ", "'");
 message =    message.Replace("‘", "'");
 message =    message.Replace("’", "'");
 message =    message.Replace("‘", "'");
 message =    message.Replace("\r", "");
 message =    message.Replace("\n", "");
 message =    message.Replace("\r\n", "");
 message =    message.Replace("?", "##S##");
 message =    System.Text.Encoding.ASCII.GetString(System.Text.Encoding.ASCII.GetBytes(message));
 message = message.Replace("?",    "");
 message =    message.Replace("##S##", "?");
 message =    message.Replace("&", "&");
 message =    message.Replace("<", "<");
 message =    message.Replace(">", ">");
 return message;
 }

Notice Regarding Sender Information Usage

Sender Information (Alphanumeric/Originator), is the sender name in the messages. This name is 11 characters long and is company dependant. While sending, the exact sender information –provided by the activation unit during account activation- must be quoted within the Originator Parameter node. 06 Error Code will be returned should Sender Information does not match. Error Code 06 means that the Originator information is not defined.

Sample Usage with Upper and Lower Case:
<Originator>MOBILDEV</Originator> <Originator>mobildev</Originator>

Notice: The Originator statement cannot contain Turkish characters and &, <, >, -, ( ), [ ], / signs.

Notice Regarding Usage Of Action Basing On Character Count

If the SMS package contains texts below and above 160 characters, a character control must be carried out and Action parameter must be set up before sending. Messages below 160 characters and messages above 160 characters must be sent as separate packages.

Usage Of Action For Texts Below 160 Characters:
In case same text below 160 characters will be sent to different GSM numbers: <Action>0</Action>
In case different texts below 160 characters will be sent to different GSM numbers:<Action>1</Action>

Usage Of Action For Texts Above 160 Characters:
In case same text above 160 characters will be sent to different GSM numbers: <Action>40</Action>
In case different texts below 160 characters will be sent to different GSM numbers: <Action>41</Action>

Notice Regarding Character Control For Messages With More Than 160 Characters (Concat SMS)

SMS quantity depends on character length as below

1 to 153 characters 1 SMS

153 to 306 characters 2 SMS

306 to 459 characters 3 SMS

459 to 612 characters 4 SMS

Notice: For messages above 160 characters, each of the messages will only have 153 characters left!

Notice Regarding Method For Sending Bulk SMS

Bulk Messages should be sent as bulk packages rather than individual packages. Individual packages cause the system to become busy, consequently, cause the messages to be sent in a delay. Messages should be sent to the Gateway using a single statement where possible. 30.000 SMS packages should be preferred in order to avoid possible delays due to internet connection and system overload.

There are 2 XML statements for sending XML SMS API; SMS to Many: where the messages are the same and SMS Multi Senders: where the messages are different.

SMS to Many:

SMS To Many statement is used to send the same message to different GSM numbers. We suggest using 30.000 SMS package. The following is the SMS to Many XML statement:
<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>0</Action> <Mesgbody>message</Mesgbody> <Numbers>GSM No1, GSM No2</Numbers> <Originator>originator</Originator> <SDate></SDate> </MainmsgBody>

Sample SMS To Many XML Statement
<MainmsgBody> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>0</Action> <Mesgbody>happy birthday</Mesgbody> <Numbers>05421234567,05321234567</Numbers> <Originator>MOBILDEV</Originator> <SDate>010120121530</SDate> </MainmsgBody>

SMS MultiSenders:

SMS MultiSenders is used to send different messages to different GSM numbers. We suggest using 30.000 SMS package. The following is the SMS MultiSenders XML statement:

<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>1</Action> <Messages> <Message> <Mesgbody>message1</Mesgbody> <Number>GSM No1</Number> </Message> <Message> <Mesgbody>message2</Mesgbody> <Number>GSM No2</Number> </Message> </Messages> <Originator>originator</Originator> <SDate></SDate> </MainmsgBody>

Sample SMS MultiSenders XML Statement
<MainmsgBody> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>1</Action> <Messages> <Message> <Mesgbody>happy birthday to you</Mesgbody> <Number>05427654321</Number> </Message> <Message> <Mesgbody>happy new year.</Mesgbody> <Number>05327654321</Number> </Message> </Messages> <Originator>MOBILDEV</Originator> <SDate></SDate> </MainmsgBody>

Concat SMS To Many XML

<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>40</Action> <Mesgbody>message</Mesgbody> <Numbers>GSM No 1,GSM No 2</Numbers> <Originator>originator</Originator>

Sample Concat SMS To Many XML

<MainmsgBody> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>40</Action> <Mesgbody>We will be pleased to see you at our grand opening which will take place on 01.Jan.2012 Monday at 10.00 at STOP&SHOP NOW! Shopping centre in Parsons Green in London.</Mesgbody> <Numbers>05421234567,05321234567</Numbers> <Originator>MOBILDEV</Originator>

Concat SMS MultiSenders XML

<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>41</Action> <Messages> <Message> <Mesgbody>message 1</Mesgbody> <Number>GSM No1</Number> </Message> <Message> <Mesgbody>message 2</Mesgbody> <Number>GSM No2</Number> </Message> </Messages> <Originator>originator</Originator> <SDate></SDate> </MainmsgBody>

Sample Concat SMS MultiSenders XML

<MainmsgBody> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>41</Action> <Messages> <Message> <Mesgbody>We will be pleased to see you at our grand opening which will take place on 01.Jan.2012 Monday at 10.00 at STOP&SHOP NOW! shopping centre in Parsons Green in London.</Mesgbody> <Number>05427654321</Number> </Message> <Message> <Mesgbody>New branch, new customers, discounted prices! Pay a visit to our new shop at STOP&SHOP NOW! shopping centre in Parsons Green in London and get 10% extra discount ticket for your next shopping!</Mesgbody> <Number>05327654321</Number> </Message> </Messages> <Originator>MOBILDEV</Originator> <SDate></SDate> </MainmsgBody>

Notice Regarding Reporting

Report Basing on TimerID: System will provide TimerID information on each of the SMS package (XML statement) sending. TimerID is the automatically assigned number by the system to each of the SMS packages.

In order to get a TimerID report (basing on package), the following XML statement should be used. The parameter for Action should be 3:

<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>3</Action> <MsgID>TimerID</MsgID> </MainReportRoot>

Sample TimerId Report:

<MainReportRoot> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>3</Action> <MsgID>65432</MsgID> </MainReportRoot>

Report Basing On Date: For this report, the Action parameter should be 2. For quoting a period use Fdate for starting date and Ldate for ending date.

In order to get a report basing on date, the following XML statement should be used:
<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>2</Action> <FDate>year-month-day</FDate> <LDate>year-month-day</LDate> </MainReportRoot>
Sample Report Basing On Date:

<MainReportRoot> <UserName>test-mb1000</UserName> <PassWord>12345</PassWord> <Action>2</Action> <FDate>2012-01-01</FDate> <LDate>2012-03-31</LDate> </MainReportRoot>

Once the XML statement makes its way to the gateway, there will be 2 values to return:
1- Successful
2- Error Return Value; Please refer to Error Codes

Notice: Reports may date back to 3 months, the most.

Notice Regarding Status Control Report

3 different status values will be returned after a report is called:

"1" means the message is awaiting;

"2" means the message was sent;

"3" means the message was not delivered.

Notice Regarding OTP Service Usage

API integration for both the OTP Service and the Bulk SMS are exactly the same. While activating the Bulk SMS account, definitions will also be made for OTP Service.

Notice: As OTP SMS is used in only sending passwords and instant notification passwords, no Bulk SMS should be sent.

Error Codes

Error Codes	Description
01	Incorrect User Name Incorrect Password Incorrect company code
02	Sending Message: Insufficient credits Invalid ID: No such message (ID) code Reporting: Package was not processed or awaiting at Gateway
03	Undefined Action parameter
04	No Incoming XML
05	Incorrect or missing XML node
06	Undefined Originator Information
07	Missing message code (ID)
08	No SMS were sent for the given dates
09	Date fields are empty - incorrect
10	SMS was not sent
11	Unidentified error
12	Unauthorized access attempt
13	No user was specified for the report

XML API Sample Codes

	ASP Scripti		PHP Scripti
	VB Project		Delphi Project
	VB.net Project		C# Project
	Java Project		Phyton Project

Get A Test Account I Have a Project!