System Requirements Negotiated International Operators User Information Control Reporting

Notice Regarding Characters To Be Used Error Codes Message (SMS) Sending Reasons For SMS Delivery Failure

General

Mobildev XML / JSON Interfaces are developed for the software developers who work with XML or JSON documents. With this API, software developers can integrate SMS sending into their applications over XML or JSON.

Being a tool supported by every operating system platform and allowing usage with every IDE, it is our solutions that solutions developers prefer. With this tool, you can perform sending of up to (30.000, recommended) SMS messages with the same or different content.

Using the information provided in this document, software developers can prepare and XML or JSON statements in their own solutions as HTTP/ XML or HTTP/JSON POST request and send to http://gateway.mobildev.com/xml (XML) or to http://gateway.mobildev.com/json (JSON), to the gateway, in short. Once the XML or JSON statement is sent, it will be processed by XML Parser. If any error is found within the XML/JSON statement or within the parameter nodes in the XML/JSON statement; a predefined error code will be returned to the sender over HTTP. If there are no errors, an appropriate return statement -that is suitable for the XML/JSON function- will be prepared and sent back to the sender over HTTP. 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, Windows7, Windows8, UNIX, Linux or MacOS Operating System

• Internet Explorer 6 SP1 (for Windows platform)

• cURL library (for developers using PHP)

Notice Regarding Characters To Be Used

Mobildev XML API solution should be used taking into consideration the following points:

• Message cannot contain Turkish characters, LineFeed, Enter, Tab,"~", and "€".
• GSM numbers must be formatted as 05326541220, 5326541220 or 905326541220. In order to send international messages, the country code must be added to the beginning of the GSM number. It will not be necessary to add country code for the domestic numbers.

Sample Table

Format	International	Domestic
532XXXXXXX	Valid	Valid
542XXXXXXX	Valid	Valid
0090542XXXXXXX	Valid	Valid
0090532XXXXXXX	Valid	Valid
0044XXXXXXXXXX	Valid	Invalid
90542XXXXXXX	Valid	Invalid
90532XXXXXXX	Valid	Invalid
44XXXXXXXXXX	Valid	Invalid

• Mobildev SMS Gateway is a solution for bulk message sending. Therefore, the messages must be prepared and sent as single XML/JSON statement to the Gateway, as much as possible.

Negotiated International Operators

Please click HERE for the table of the negotiated international operators.

Error Codes

Error Code	Description
01	Incorrect user name – password – dealer code
02	Message Sending: Insufficient credits Invalid ID: No such message (ID) code Reporting: Package is not processed or it is pending at the Gateway side
03	Undefined Action parameter
04	No XML received
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

User Information Control

Once you send the below XML / JSON statement, adding the required information to the parameter nodes, to the Gateway; user credit balance and originator definitions are sent as the return values:

XML	JSON
<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>4</Action> </MainReportRoot>	{ "MainReportRoot": { "UserName": "username-company_code", "PassWord": "password", "Action": "4" } }

The below is the list for the parameters and what they refer to:

Parameter	Description
UserName	Your Mobiltim SMS services user name,
PassWord	Password, associated with your user name,
Action	The function for which the XML statement is sent.

Caution must be observed when transferring variable to the UserName parameter node. The transferred parameter value must be in username-company_code format. Username parameter refers to your user name and the company_code parameter refers to the channel you are associated. Please refer to Example 5.4.1 

Example 5.4.1:  XML and JSON statements prepared for the user information control:

XML	JSON
<MainReportRoot> <UserName>test-mb1000</UserName> <PassWord>XXXXX</PassWord> <Action>4</Action> </MainReportRoot>	{ "MainReportRoot": { "UserName": "test-mb1000", "PassWord": "XXXXX", "Action": "4" } }

Note: "mb1000" value is different for each channel. If you are dealing with Mobildev's SMS Services as an end user, you must use "mb1000" as the company_code parameter value. And if you are dealing as a channel, then you must use the value defined for your name. Creating HTTP XML or HTTP JSON request and sending the above XML statement to the Gateway results in receiving the below return values: 

If the operation is successful: 
Balance credit<10>
Originator1<10>
Originator2<10>
OriginatorN 

If an error occurred: Please refer to the Error Codes Table. <10> represents the LineFeed character. Originator information represents the information that will be displayed as the "Sender" on the target GSM number. This information can be a numeric or alphanumeric statement, consisting of 11 characters, excluding Turkish and special characters like &, <, and, >.

Message (SMS) Sending

XML / JSON Interfaces provide two types of XML / JSON statements for SMS sending: 

• SMS To Many SMS 
• MultiSenders

SMS To Many / SMS To Many Concat

SMS To Many statement is used to send the same message to different GSM numbers. Recommended SMS package size is 30.000. The below is an example for SMS to Many XML / JSON statement. 

In order to send SMS with more than 160 characters, input 40 value into the <Action>0</Action> part in the XML User Manual below. 

NOTE: If your message text is equal to 160 or less than that and you use action value as 40, then SMS sending will fail. 

Example 5.5.1.1: SMS To Many statement example:

XML	JSON
<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>0</Action> <Mesgbody>message</Mesgbody> <Numbers>05421234567,05321234567</Numbers> <Originator>CorporateSMS</Originator> <SDate>150820041530</SDate> </MainmsgBody>	{ "MainmsgBody": { "UserName": "username-company_code", "PassWord": "password", "Action": "0", "Mesgbody": "message", "Numbers": "05421234567,05321234567", "Originator": "CorporateSMS", "SDate": "150820041530" } }

Number of the message depends on the characters used when you type the message text:

1 to 153 characters: 1 SMS

153 to 306 characters: 2 SMS

306 to 459 characters: 3 SMS

459 to 612 characters: 4 SMS

Not: For messages above 160 characters, each of the messages will only have 153 characters left.

The statements above refer to the descriptions as the below: 

Parameter	Description
UserName	Your user name defined on our system,
PassWord	Your password, associated with your user name on our system,
Action	The information for the function for which the XML statement is sent,
Mesgbody	Message content to send,
Numbers	The GSM number to send the message to,
Originator	The statement which will be displayed as the sender on the target GSM number,
SDate	Time of sending in ddmmyyyyhhmm (DateMonthYearHourMinute) format.

If you do not input any value to the Originator parameter node, then the initial Originator information which is defined for the user will be used. If you do input any value to the SDate parameter node, then the sending of the messages will start immediately. And if you input a value, then sending of the messages will be performed on that date.

Once the XML statement makes its way to the gateway, there will be 2 return values:

If the operation is successful: TimerID information belonging to the message sending package as "ID: 3152005" will be returned.
If an error occurred: Please refer to Error Codes - Table

SMS MultiSenders / SMS MultiSenders Concat

SMS MultiSenders statement is used to send different messages to different GSM numbers. Recommended SMS package size is 30.000. The below is an example for SMS MultiSenders XML / JSON statement. 

In order to send SMS with more than 160 characters, input 41 value into the <Action>1</Action> part in the XML User Manual below. 

NOTE: If your message text is equal to 160 or less than that and you use action value as 41, then SMS sending will fail.

Example 5.5.2.1: SMS MultiSenders Examples

XML	JSON
<MainmsgBody> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>1</Action> <Messages> <Message> <Mesgbody>your message1</Mesgbody> <Number>05427654321</Number> </Message> <Message> <Mesgbody>your message2</Mesgbody> <Number>05327654321</Number> </Message> </Messages> <Originator>CorporateSMS</Originator> <SDate>011120120101</SDate> </MainmsgBody>	{ "MainmsgBody": { "UserName": "username-company_code", "PassWord": "password", "Action": "1", "Messages": { "Message": [ { "Mesgbody": "your message1", "Number": "05427654321" }, { "Mesgbody": "your message2", "Number": "05327654321" } ] }, "Originator": "CorporateSMS", "SDate": "011120120101" } }

Number of the message depends on the characters used when you type the message text:

1 to 153 characters: 1 SMS

153 to 306 characters: 2 SMS

306 to 459 characters: 3 SMS

459 to 612 characters: 4 SMS

Note: For messages above 160 characters, each of the messages will only have 153 characters left.

The statements above refer to the descriptions as the below: 

Parameter	Description
UserName	Your user name defined on our system
PassWord	Your password, associated with your user name on our system
Action	The information for the function for which the XML statement is sent
Mesgbody	Message content to send
Number	The GSM number to send the message to
Originator	The statement which will be displayed as the sender on the target GSM number
SDate	Time of sending in ddmmyyyyhhmm (DateMonthYearHourMinute) format

If you do not input any value to the Originator parameter node, then the initial Originator information which is defined for the user will be used. If you do input any value to the SDate parameter node, then the sending of the messages will start immediately. And if you input a value, then sending of the messages will be performed on that date.

Once the XML statement makes its way to the gateway, there will be 2 return values:

If the operation is successful: TimerID information belonging to the message sending package as "ID: 3152005" will be returned.

If an error occurred: Please refer to Error Codes - Table

Reporting

Mobildev XML Interfaces offers 2 options for the reporting of the SMS messages sent:

• Date Based Reporting

• Reporting Basing On Message Sent

Date Based Reporting
Date Based Reporting is used for reporting the SMS sending performed between 2 dates as a whole. The below are the XML and JSON statements necessary for getting a report basing on date.

Example 5.5.1.1: The statements necessary for getting date based reporting:

 

XML	JSON
<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>2</Action> <FDate>2012-06-28</FDate> <LDate>2012-07-28</LDate> </MainReportRoot>	{ "MainReportRoot": { "UserName": "username-company_code", "PassWord": "password", "Action": "2", "FDate": "2012-06-28", "LDate": "2012-07-28" } }

Parameter	Description
UserName	Your user name defined on our system
PassWord	Your password, associated with your user name on our system
Action	The information for the function for which the XML statement is sent
FDate	Starting date of the report (in "Year-Month-Date" format)
LDate	Ending date of the report (in "Year-Month-Date" format)

 

Once the XML statement makes its way to the gateway, there will be 2 return values:

If the operation is successful: "TimerID<32>GSM Number<32>Status<32>Delivery Date<32>Reason for delivery failure<10>" 

Example: Return value for date based reporting

1234<32>905358838799<32>2<10>2012-11-01 11:11:00<10> <32>
1234<32>905428838799<32>3<10>2012-11-01 12:00:00<10>101<32>
1234<32>905558838799<32>1<10>1900-01-01 00:00:00<10> <32>

Note: In the status information, "1" means the message is awaiting, "2" means the message is sent, "3" means that it was not delivered. In all the return values, <32> represents space character and <10> represents LineFeed character. Delivery date is given for the delivered and not delivered messages. Otherwise, 1900-01-01 00:00:00 value is received. Reason for delivery failure is only received for the SMS messages that could not delivered. For the list of the reasons given by the operator, please refer to Reasons For SMS Delivery Failure - Table

If an error occurred: Please refer to Error Codes - Table

TimerID Based Reporting
TimerID (Message Code) based reporting is used for reporting performed message sending for a SMS package.

The example below shows the statements necessary for getting TimerID based reporting:

XML	JSON
<MainReportRoot> <UserName>username-company_code</UserName> <PassWord>password</PassWord> <Action>3</Action> <MsgID>TimerID</MsgID> </MainReportRoot>	{ "MainReportRoot": { "UserName": "username-company_code", "PassWord": "password", "Action": "3", "MsgID": "TimerID" } }

The statements above refer to the descriptions as the below:

Parameter	Description
UserName	Your user name defined on our system
PassWord	Your password, associated with your user name on our system
Action	The information for the function for which the XML statement is sent
MsgID	TimerID information belonging to the SMS package for reporting

 

Once the XML or JSON statement makes its way to the gateway, there will be 2 return values:

If the operation is successful: "TimerID<32>GSM Number<32>Status<32>Delivery Date<32>Reason for delivery failure<10>" 

Example: Return value for date based reporting
1234<32>905358838799<32>2<10>2012-11-01 11:11:00<10> <32>
1234<32>905428838799<32>3<10>2012-11-01 12:00:00<10>101<32>
1234<32>905558838799<32>1<10>1900-01-01 00:00:00<10> <32>

Note: In the status information, "1" means the message is awaiting, "2" means the message is sent, "3" means that it was not delivered. In all the return values, <32> represents space character and <10> represents LineFeed character. Delivery date is given for the delivered and not delivered messages. Otherwise, 1900-01-01 00:00:00 value is received. Reason for delivery failure is only received for the SMS messages that could not delivered. For the list of the reasons given by the operator, please refer to Reasons For SMS Delivery Failure - Table

If an error occurred: Please refer to Error Codes - Table 

Reasons For SMS Delivery Failure

Error Code	Description
000	Unknown subscriber ->Number is not defined in Turkcell Network -> Not to be retried
001	Service temporary not available ->Can be retried
002	Service temporary not available ->Can be retried
003	Service temporary not available ->Can be retried
004	Service temporary not available ->Can be retried
005	Service temporary not available ->Can be retried
006	Service temporary not available ->Can be retried
007	Service temporary not available ->Can be retried
008	Service temporary not available ->Can be retried
009	Illegal error code
010	Network time-out
100	Facility not supported
101	Unknown subscriber -> Number is not defined in Turkcell Network -> Not to be retried
102	Facility not provided
103	Call barred ->SMS service usage restricted -> Not to be retried
104	Operation barred ->Not to be retried
105	SC congestion
106	Facility not supported
107	Absent subscriber ->Mobile station is off, not to be retried considering it will not be turned on in a short period of time.
108	Delivery fail ->Message failure -> The application must decide whether to retry
109	Sc congestion ->Not to be retried
110	Protocol error ->Not to be retried
111	MS not equipped ->Not to be retried
112	Unknown SC->Not to be retried
113	SC congestion ->Not to be retried
114	Illegal MS ->Error with the mobile station, not to be retried considering it will not be fixed in a short period of time
115	MS not a subscriber ->Not to be retried
116	Error in MS ->Not to be retried
117	SMS lower layer not provisioned ->Not to be retried.
118	System fail ->System failure, the application may decide whether to retry
119	PLMN system failure ->Not to be retried
120	HLR system failure ->Not to be retried
121	VLR system failure ->Not to be retried
122	Previous VLR system failure ->Not to be retried
123	Controlling MSC system failure ->Not to be retried
124	VMSC system failure ->Not to be retried
125	EIR system failure ->Not to be retried
126	System failure ->System failure, the application may decide whether to retry
127	Unexpected data value ->Not to be retried
200	Error in address service centre ->Not to be retried
201	Invalid absolute Validity Period
202	Short message exceeds maximum
203	Unable to Unpack GSM message
204	Unable to convert to IRA ALPHABET ->Not to be retried
205	Invalid validity period format
206	Invalid destination address
207	Duplicate message submit
208	Invalid message type indicator

Get A Test AccountI Have a Project!