Message Manager

Sending & Receving

Webservice API
Developer Reference
Version 6.00

1/14
 Table of Contents

I.   MESSENGER API FUNCTIONS AS WEBSERVICE .....................................................................................3  

I.1.   API PARAMETERS UNIVERSAL TO ALL FUNCTIONS ...........................................................................................3  
I.1.a.   customerID ...............................................................................................................................................3  
I.1.b.   customerUserName ..................................................................................................................................3  
I.1.c.   originatorName ........................................................................................................................................3  
II.   AUTHENTICATING THE USER .....................................................................................................................4  
III.   SENDING SMS MESSAGES ............................................................................................................................5  
IV.   SENDING BINARY SMS MESSAGES ...........................................................................................................6  
V.   SENDING MMS MESSAGES ............................................................................................................................8  
V.1.   TRANSFORMING MMS CONTENT INTO ‘MM7’ FORMAT AND SENDING THE RESULTING MM7 FILE ..................8  
VI.   GETTING SMS/MMS MESSAGE STATUS ................................................................................................12  
VII.   SENDING SERVICE SMS MESSAGES .....................................................................................................13  

2/14
 I. Messenger API functions as webservice
This set of functions is designed for sending and receiving SMS/MMS messages and for Inbox
operation in third-party clients. Each function comes in two variants: for UTF-8 and for
Windows-1256 encoding. The function parameters universal to all functions are underlined,
and you can see their full descriptions in the API parameters universal to all functions.

Messenger API uses SOAP services, so you need to add a Web Reference called
‘MessengerService’ to your project before you can compile the examples from this document.

The URL for the Web Service for Zain SMS System is
http://bulkcorporate.sa.zain.com/bms/Soap/Messenger.asmx

For Arabic codepage compatibility you can access the same webservice at
http://bulkcorporate.sa.zain.com/bms/Soap1256/Messenger.asmx

Please use the following code to initialize Messenger API before calling any of its functions:

MessengerSoapClient messenger =
new MessengerService.MessengerSoapClient("MessengerSoap");
// "MessengerSoap" - endpoint name in configuration file

I.1. API parameters universal to all functions

I.1.a. customerID
The unique identifier for every customer (wholesaler) in the Message Manager Platform
database.

I.1.b. customerUserName
A user is the actual actor who uses the Messaging Platform services. A customer can have
several users who access the Messaging Platform services under the customer account. A
user does not have a balance of their own, when a user is sending messages, their customer
account is charged. Every user has a separate user name, a password, and can have a
separate set of originators.

I.1.c. originatorName
The originator is the name or number that the recipient sees as the signature for the
message received.

3/14
 II. Authenticating the user
The Authenticate function authenticates the user specified by the customer ID, user name,
language, and password in MESSAGEMANAGER PLATFORM system.

The example provided below is the Authenticate function prototype:

Authenticate(SoapUser user)

The required parameters are:

• customerID
• userName—the customerID
The unique identifier for every customer (wholesaler) in the Message Manager Platform
database.

• customerUserName for the user for whom the list of originators is requested.
• Language—the language in which the client application is going to communicate with
the user.
• userPassword—the password of the user specified.

An example of calling the Authenticate function is provided below:

SoapUser user = new SoapUser();
user.CustomerID = 1;
user.Name = "Bob";
user.Language = "en";
user.Password = "secret";

AuthResult authData = messenger.Authenticate(user);

if (authData.Result == "OK")
{
Console.WriteLine("Hello, Bob");
}
else
{
Console.WriteLine("Error: " + authData.Result);
}

An example of responding to the Authenticate function is provided below:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<AuthenticateResponse xmlns="http://pmmsoapmessenger.com/">
<AuthenticateResult>
<NetPoints>string</NetPoints>
<Originators>
<string>string</string>
<string>string</string>
</Originators>
<CustomerID>int</CustomerID>
<CreditSMS>string</CreditSMS>
<CreditMMS>string</CreditMMS>
</AuthenticateResult>
</AuthenticateResponse>
</soap:Body>
</soap:Envelope>

4/14
You can also use the HTTP_Authenticate alias to call this function without using SOAP, by
the means of pure HTTP GET, as shown in the example below:
GET /MessageManager
Platform/soap/Messenger.asmx/HTTP_Authenticate?customerID=string&userName=str
ing&userPassword=string
HTTP/1.1

III.Sending SMS messages

With the help of the SendSms function the customer can send SMS messages using the
specified parameters.

The example provided below is the SendSms function prototype:

SendSms(SoapUser user, string originator, string smsData, string
recipientPhone, MessageType messageType, string defDate, boolean blink,
boolean flash, boolean private)

The required parameters are:

• customerID
• userName—the customerID
The unique identifier for every customer (wholesaler) in the Message Manager Platform
database.

• customerUserName for the user for whom the list of originators is requested.
• userPassword—the password of the user specified.
• originator—the parameter identical to originatorName
• smsText—the text for the SMS message to be sent.
• recipientPhone—the recipient’s phone numbers separated by commas (the parameter
can contain just one number).
• messageType—the type of the character set used in the SMS text (Latin, Arabic with
Latin numbers, Arabic with Arabic numbers).
• defDate—the parameter specifying the date and time of deferred delivery (must be in
the yyyyMMddhhmmss format).
• flash—the parameter defines whether the SMS message is to be saved in the recipient
phone inbox (True—the message is not saved, False—the message is saved).
• blink—the parameter defines whether the SMS message blinks when onscreen
(applicable for some makes of Nokia mobile phones).
• private—the parameter defines whether the SMS message appears in the account
statement.

An example of calling the SendSms function is provided below:

SoapUser user = new SoapUser();
user.CustomerID = 1;
user.Name = "Bob";
user.Language = "en";
user.Password = "secret";

string originator = authResult.Originators[0];

string defDate = DateTime.UtcNow.AddHours(1).ToString("yyyyMMddhhmmss");
string smsData = "test";
string phone = "966592000001, 966592000002, 966592000003";

SendResult result = messenger.SendSms(user, originator, smsData, phone,

MessageType.Latin, defDate, false, false, false);
Console.WriteLine(result.Result);

5/14
An example of responding to the SendSms function is provided below:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendSmsResponse xmlns="http://pmmsoapmessenger.com/">
<SendSmsResult>
<RejectedNumbers>
<string>string</string>
<string>string</string>
</RejectedNumbers>
<TransactionID>string</TransactionID>
<NetPoints>string</NetPoints>
</SendSmsResult>
</SendSmsResponse>
</soap:Body>
</soap:Envelope>
You can also use the HTTP_SendSms alias to call this function without using SOAP, by the
means of pure HTTP GET, as shown in the example below:
GET /MessageManager
Platform/soap/Messenger.asmx/HTTP_SendSms?customerID=string&userName=string&u
serPassword=string&originator=string&smsText=string&recipientPhone=string&mes
sageType=string&defDate=string&blink=string&flash=string&Private=string
HTTP/1.1

IV. Sending Binary SMS messages

With the help of the SendBinarySms function the customer can send binary SMS messages
using the specified parameters.

The example provided below is the SendBinarySms function prototype:

SendBinarySms(SoapUser user, String originator, String binaryBody,
String recipientPhone, String defDate, String data_coding, String esm_class,
String PID)

The required parameters are:

• customerID
• userName—the customerID
The unique identifier for every customer (wholesaler) in the Message Manager Platform
database.

• customerUserName for the user for whom the list of originators is requested.
• Language—the language in which the client application is going to communicate with
the user.
• userPassword—the password of the user specified.
• originator—the parameter identical to originatorName.
• binaryBody—the binary body of the SMS message.
• recipientPhone— the recipient’s phone numbers separated by commas (the parameter
can contain just one number).
• defDate—the parameter specifying the date and time of deferred delivery (must be in
the yyyyMMddhhmmss format).
• data_coding—the coding for the binary body of the SMS message.
• esm_class—the parameter related to the coding of the binary body of the SMS
message.

6/14
 • PID—the protocol ID.

An example of calling the SendBinarySms function is provided below:

SoapUser user = new SoapUser();
user.CustomerID = 1;
user.Name = "Bob";
user.Language = "en";
user.Password = "secret";

string originator = authResult.Originators[0];

string defDate = DateTime.UtcNow.AddHours(1).ToString("yyyyMMddhhmmss");
string smsData = "test";
string phone = "966592000001";

SendResult binSmsSendResult =
messenger.SendBinarySms(user, originator, smsData , phone, defDate,
string.Empty, string.Empty, string.Empty);
Console.WriteLine();

An example of responding to the SendBinarySms function is provided below:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendBinarySmsResponse xmlns="http://pmmsoapmessenger.com/">
<SendBinarySmsResult>
<RejectedNumbers>
<string>string</string>
<string>string</string>
</RejectedNumbers>
<TransactionID>string</TransactionID>
<NetPoints>string</NetPoints>
</SendBinarySmsResult>
</SendBinarySmsResponse>
</soap:Body>
</soap:Envelope>
You can also use the HTTP_SendBinarySms alias to call this function without using SOAP,
by the means of pure HTTP GET, as shown in the example below:
GET /MessageManager
Platform/soap/Messenger.asmx/HTTP_SendBinarySms?customerID=string&userName=st
ring&userPassword=string&originator=string&binaryBody=string&recipientPhone=s
tring&defDate=string&data_coding=string&esm_class=string&PID=string
HTTP/1.1

7/14
 V. Sending MMS messages
With the help of the SendMMS function the customer can send MMS messages using the
specified parameters.

The example provided below is the SendMMS function prototype:

SendMMS(byte[] mm7Data)

The required parameter is:

• mm7Data—the standard format for sending MMS messages. Along with media files
and other data, the parameter contains the recipient phone numbers separated by
commas (one number is possible).

An example of calling the SendMMS function is provided below:

Byte[] mm7Data;
using (FileStream fileStream = new FileStream(path, FileMode.Open))
{
mm7Data = new Byte[fileStream.Length];
fileStream.Read(mm7Data, 0, mm7Data.Length);
}

SendMMSResult mmsSendResult = messenger.SendMMS(mm7Data);

Console.WriteLine(mmsSendResult.Result);

An example of responding to the SendMMS function is provided below:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SendMMSResponse xmlns="http://pmmsoapmessenger.com/">
<SendMMSResult>
<MESSAGEMANAGER PLATFORMTransactionID>string</MESSAGEMANAGER
PLATFORMTransactionID>
</SendMMSResult>
</SendMMSResponse>
</soap:Body>
</soap:Envelope>

V.1. Transforming MMS content into ‘mm7’ format and

sending the resulting mm7 file
The three pieces of code provided below show how to compile and send an MMS message
using the SendMMS function. The second piece details one of the methods (GenerateMIME)
mentioned in the first part, and the third piece details one of the methods (WriteToMime)
mentioned in the second piece.

First, the paths where to put the ‘SMIL’ file and the MMS content are defined. Then the
GenerateMIME method uses the paths to generate the resulting mm7 file and save it to the
path specified. Then the FileStream method takes the mm7 file and transforms it into a
datastream to be transferred to the SendMMS function.
String mm7FilePath = "D:\\<some_folder_1>\\<some_folder_2>\\<mm7FileName>";

String mmsContentFolderPath = "D:\\<some_folder_1>\\<some_folder_2>\\";

GenerateMIME( mmsContentFolderPath, mm7FilePath );

Byte[] mm7data = null;

8/14
using (FileStream fs = new FileStream(mm7FilePath, FileMode.Open,
FileAccess.Read))
{
mm7data = new Byte[fs.Length];
fs.Read(mm7data, 0, mm7data.Length);
String mm7DataString = Convert.ToBase64String(mm7data,
Base64FormattingOptions.None);
}

Messenger.Messenger messengerService = new Messenger.Messenger();

SendMMSResult sendMMSresult = messengerService.SendMMS(mm7data);

The GenerateMIME method mentioned in the example above puts the SMIL file into the
mm7 file. The GenerateMIME method is detailed in the lengthy example below:
public static void GenerateMIME(String dataDirectoryName, string
outputFileName)
{
DateTime dt = DateTime.Now;
String sMonth = String.Empty;
String sDay = String.Empty;
String sYear = String.Empty;
String sHour = String.Empty;
String sMinute = String.Empty;
String sSecond = String.Empty;
String sMillisecond = String.Empty;

// Getting data for boundary string

int iMonth = dt.Month;
if (iMonth <= 9) sMonth = "0" + iMonth.ToString();
else sMonth = iMonth.ToString();

int iDay = dt.Day;

if (iDay <= 9) sDay = "0" + iDay.ToString();
else sDay = iDay.ToString();

int iYear = dt.Year;

sYear = iYear.ToString().Substring(2, 2);

int iHour = dt.Hour;

if (iHour <= 9) sHour = "0" + iHour.ToString();
else sHour = iHour.ToString();

int iMinute = dt.Minute;

if (iMinute <= 9) sMinute = "0" + iMinute.ToString();
else sMinute = iMinute.ToString();

int iSecond = dt.Second;

if (iSecond <= 9) sSecond = "0" + iSecond.ToString();
else sSecond = iSecond.ToString();

int iMillisecond = dt.Millisecond;

if (iMillisecond <= 99)
{
if (iMillisecond <= 9) sMillisecond = "00" + iMillisecond.ToString();
else sMillisecond = "0" + iMillisecond.ToString();
}
else sMillisecond = iMillisecond.ToString();

String sDt = sMonth + sDay + sYear + sHour + sMinute + sSecond +

sMillisecond;
String content_ref = "11351";
String smil_reference = "20412";
// Set up boundary string
String boundary = "--------" + sDt;

9/14
String[] files = Directory.GetFiles(dataDirectoryName, "*.smil");

String smilFileFull = files[0];

String[] a = smilFileFull.Split('\\');
int count = a.Length;
String smilFileName = a[count - 1];

// Writing data into mime-file

StreamWriter sw = File.CreateText(outputFileName);
StreamReader sr = new StreamReader(smilFileFull);

try
{
// header generation
sw.WriteLine("Content-Type: multipart/related;");
sw.WriteLine("\t boundary=\"" + boundary + "\";");
sw.WriteLine("\t start=\"smil_reference_" + smil_reference + "\";");
sw.WriteLine("\t type=\"application/smil\"");
sw.WriteLine("Content-Id: <content_ref_" + content_ref + ">");

// smil inserting
sw.WriteLine("");
sw.WriteLine("--" + boundary);
sw.WriteLine("Content-Id: <smil_reference_" + smil_reference + ">");
sw.WriteLine("Content-Type: application/smil; name=\"" + smilFileName
+ "\"");
sw.WriteLine("Content-location: " + smilFileName);
sw.WriteLine("");
sw.Write(sr.ReadToEnd());
sw.WriteLine("");

//attachments inserting

DirectoryInfo di = new DirectoryInfo( dataDirectoryName );

FileInfo[] fInfos = di.GetFiles();
String StringArray = String.Empty;

for( int i = 0; i < fInfos.Length; i++ )

{
if (!fInfos[i].Extension.Equals("smil"))
{
continue;
}

using (FileStream fs = new FileStream(fInfos[i].FullName,

System.IO.FileMode.Open))
{
if (fInfos[i].Extension.Equals("txt"))
{
StreamReader reader = new StreamReader(fs,
System.Text.Encoding.GetEncoding(1256));
StringArray = reader.ReadToEnd();
}
else
{
Byte[] ByteArray = new Byte[fs.Length];
fs.Read(ByteArray, 0, ByteArray.Length);
StringArray = Convert.ToBase64String(ByteArray, 0,
ByteArray.Length);
}

WriteToMime( sw, boundary, contentType, fInfos[i].Name,

StringArray );

10/14
 }

}
// footer generation
sw.WriteLine("");
sw.WriteLine("--" + boundary + "--");
}
catch (Exception ex)
{
//Exception handling
}
finally
{
sw.Close();
sr.Close();
}
}
(the end of the GenerateMIME method description)

The WriteToMime method mentioned in the example above is responsible for putting the
media files into the same mm7 file. The method is detailed in the example below:
public static void WriteToMime(StreamWriter sw, String boundary,
String contentType, String contentLocation,
String stringArray)
{
sw.WriteLine("");
sw.WriteLine("--" + boundary);
sw.WriteLine("Content-Id: <" + contentLocation + ">;
" + "name=\"" + contentLocation + "\"");
sw.WriteLine("Content-Type: " + contentType);
sw.WriteLine("Content-location: " + contentLocation);
if ( !contentType.StartsWith("text"))
{
sw.WriteLine( "Content-Transfer-Encoding: base64" );
}
sw.WriteLine("");

int RecordsNum = 0;
int iRes = stringArray.Length / 76;
if ((iRes * 76) < stringArray.Length) RecordsNum = iRes + 1;
else RecordsNum = iRes;
String[] a = null;
a = new String[RecordsNum];
int j = 0;
for (int i = 0; i < RecordsNum; i++)
{
if (!(i == RecordsNum - 1)) a[i] = stringArray.Substring(j, 76);
else
{
int iLengthRemain = stringArray.Length - ((RecordsNum - 1) * 76);
a[i] = stringArray.Substring(j, iLengthRemain);
}

sw.WriteLine(a[i]);

j += 76;
}
}

11/14
 VI. Getting SMS/MMS message status
To get statuses for both SMS and MMS messages, the GetSmsStatus function is used.
Actually, it operates with the message transactionID which does not depend on the message
type. The GetSmsStatus function returns the delivery status of the specified SMS/MMS
message.

The example provided below is the GetSmsStatus function prototype:

GetSmsStatus(SoapUser user, String transactionID, Boolean detailed)

The required parameter is:

• customerID
• userName—the customerID
The unique identifier for every customer (wholesaler) in the Message Manager Platform
database.

• customerUserName for the user for whom the list of originators is requested.
• Language—the language in which the client application is going to communicate with
the user.
• userPassword—the password of the user specified.
• transactionID—the unique identification of the transaction.
• detailed—Boolean value which defines if detailed statuses for multiple recipients are to
be show. It can be ‘True’ or ‘False’.

An example of calling the GetSmsStatus function is provided below:

// send sms
SendResult sendResult = messenger.SendSms(
user, authResult.Originators[0], "test", "971505000001",
MessageType.Latin, DateTime.UtcNow.ToString("yyyyMMddhhmmss"),
false, false, false);
// retrieve its' status
SmsStatus status = GetSmsStatus(user, sendResult.TransactionID, true);
Console.WriteLine(status.Result);

An example of responding to the GetSmsStatus function is provided below:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetSmsStatusResponse xmlns="http://pmmsoapmessenger.com/">
<GetSmsStatusResult>
<Statistics>xml</Statistics>
<Details>xml</Details>
<NetPoints>string</NetPoints>
</GetSmsStatusResult>
</GetSmsStatusResponse>
</soap:Body>
</soap:Envelope>
You can also use the HTTP_GetSmsStatus alias to call this function without using SOAP, by
the means of pure HTTP GET, as shown in the example below:
GET /MessageManager
Platform/soap/Messenger.asmx/HTTP_GetSmsStatus?customerID=string&userName=str
ing&userPassword=string&transactionID=string&detailed=string
HTTP/1.1

12/14
 VII. Sending Service SMS messages
With the help of the SendServiceSms function the customer can send service SMS
messages using the specified parameters.

The example provided below is the SendServiceSms function prototype:

SendServiceSms(Int32 customerID, String userName, String userPassword, String
originator, String serviceName, string serviceUrl, String recipientPhone,
MessageType messageType, String defDate, Boolean blink, Boolean flash,
Boolean Private)

The required parameters are:

• customerID
• userName—the customerID
The unique identifier for every customer (wholesaler) in the Message Manager Platform
database.

• customerUserName for the user for whom the list of originators is requested.
• userPassword—the password of the user specified.
• originator—the parameter identical to originatorName
• serviceName—the name of the service.
• serviceUrl—the URL of the service.
• recipientPhone—the recipient’s phone numbers separated by commas (the parameter
can contain just one number).
• messageType—the type of the character set used in the SMS text (Latin, Arabic with
Latin numbers, Arabic with Arabic numbers).
• defDate—the parameter specifying the date and time of deferred delivery (must be in
the yyyyMMddhhmmss format).
• flash—the parameter defines whether the SMS message is to be saved in the recipient
phone inbox (True—the message is not saved, False—the message is saved).
• blink—the parameter defines whether the SMS message blinks when onscreen
(applicable for some makes of Nokia mobile phones).
• private—the parameter defines whether the SMS message appears in the account
statement.

An example of calling the SendServiceSms function is provided below:

int id = 2;
string userName = "Bob";
string password = "secret";
string originator = authResult.Originators[0];
string defDate = DateTime.UtcNow.AddHours(1).ToString("yyyyMMddhhmmss");
string smsData = "test";
string phone = "966592000001";
string serviceName = "bar";
string serviceUrl = "http://url/mm/soap/messenger.asmx";
messenger.SendServiceSms(id, userName, password, originator, serviceName,
serviceUrl, phone, MessageType.Latin, defDate, false, false, false);

An example of responding to the SendServiceSms function is provided below:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>

13/14
 <SendServiceSmsResponse xmlns="http://pmmsoapmessenger.com/">
<SendServiceSmsResult>
<RejectedNumbers>
<string>string</string>
<string>string</string>
</RejectedNumbers>
<TransactionID>string</TransactionID>
<NetPoints>string</NetPoints>
</SendServiceSmsResult>
</SendServiceSmsResponse>
</soap:Body>
</soap:Envelope>

14/14