Integration of 3rd party aplications into MobilChange

Technical manual

Introduction
CTL files logic
Configuration of MobilChange application
Sending SMS
1. Text SMS
2. Binary SMS
Reports about message processing
SMS receiving
Capabilities of individual MobilChange sending channels

Introduction

MobilChange (abbreviated to MX in next text) comunicates with other applications through files in filesystem. Also "high-level" comunication tools (like COM object for SMS sending) are based on files. This document describes recommended practice for sending / receiving SMS using files.

MX is able to handle many applications which send / receive SMS concurrently with common users, which work with SMS through their e-mail client or WWW form. Every application is identified by its name - it can be any, but it should contain only english letters.

Notes:

This document describes MobilChange in version 4.0.16. Older versions work in different way
Integration of 3rd party applications can be used in MobilChange Enterprise Edition only! Standard version doesn't support this functionality.
MobilChange is (especially valid for routing rules) case sensitive!

CTL files logic

Every communication between MX and neighbourhood consists of two files. First of them (control file, CTL) contains "what to do" information - what goes on, from, to ..., second one contains data to be processed. First file always contains link to the second file. So when SMS is being sent, CTL file, which contains information who is sending SMS to which recipient, which way and also link to second TXT file, is stored into mail/in/ folder. TXT file contains text of SMS.

Recommended practice for creating these two files:

Create data file (TXT), write data and close it.
Create control file, but give it different extension (for example ".writing").
Write data and close it.
Change control file's extension to CTL.

At the moment of renaming we say MX that file can be processed - from this moment our application may not manipulate with CTL file.

Names of CTL and TXT files must be unique - you can not use the same TXT filename for more messages.

File receiving from MX should use the same logic - only when control file with correct extension appears, we can open it and read necessary information and name of data file.

Configuration of MobilChange application

For SMS sending suffices to use unique name for new application and to create its folder for receiving SMS: (MobilChange)/script/in/app_name/.

Also it is necessary set new routing rule in mxRouteCfg application - filter for phone number and message text set to ".*" (without quotations), if you want to receive all messages. Set "aa" language and "continue processing next rules for this message" option - it allows processing this message also by other applications. If you don't want to deliver SMS also to mail recipient, set "stop processing all rules for this message" option for last application in the list, which filters are valid to this SMS. Then we recommend to test in mxRouteCfg, if routing rules does what you intended.

Sending SMS

SMS sending is done by two files creating - *.CTL a *.TXT in (MobilChange)/mail/in/ folder, which is also shared as MxInQueue.

*.CTL file contains information about sender and recipient of SMS, sending mode and link to *.TXT file. That file contains SMS body text.

Text SMS

Control CTL file should have format according to the following description. Change only items marked by bold italic. Recommend values are written by red color - if not sure, use them.

[system]
type=email

priority=normal
Valid values are "high", "normal" and "low", where SMS with higher priority jump the queue of lower priority SMS

sent=3ffaede7
SMS creation time - number of seconds from 1.1.1970 as hexanumber. If your application is not able to create this format of time, leave this sample value here.
TIP: printf( "%08.8x", time() );

subject= Subject of e-mail message. Has no meaning for messages generated by application = leave empty.

nomodify=1
1 = Do not modify message text.
0 = Reformat the message - removes redundant spaces, adds info about sender...

display_cc=
display_to=

msg=TEST_1_3ffaede7.txt Name of the text file in the same folder. File contains SMS text. If transport channel allows it, it is sent in full quality, it means including line ends and similar chars.

dr=1
1 = Delivery Report requested
0 = DR not requested
Delivery Reports not always supported - it depends on driver and hardware in use.

displayonly=0
1 = "display only "SMS - displays even if user has SMS storage full. Next SMS of the same type rewrites it.
0 = normal SMS

user_app_id=15454 Application ID of this SMS. MX doesn't process this item, but returns it in all information messages about the SMS, so application knows, what SMS is related to.
If you have no ID to fill in, leave item empty - user_app_id=

replyrequired=0
1 = When SMS is displayed, phone notifies the user that sender asked for a reply and usually offers writting of the reply. Not supported by all phones - if phone has not this feature, SMS is normally displayed.
0 = Normal SMS

from_number=9001230
Phone number which will be set as sender's number for this SMS. This function is supported only by some drivers. You can set only numbers, which you negotiate with mobile operator.
If you don't want set the number, don't create this item!

via_line=line3
Explicit specification of sending line.
If you don't want specify the line, don't create this item!

maxlen=3
Maximum number of SMS, which is message split to if longer than 160 chars.
If you dont want specify this number, don't create this item!

[user]
cmd=email=$Aapp_name

Put your application name here.

cmd=address=
cmd=assist_n=
cmd=assist_p=
cmd=off_ph_2=
cmd=city=
cmd=company=
cmd=country=
cmd=custom_1=
cmd=custom_2=
cmd=custom_3=
cmd=custom_4=
cmd=custom_5=
cmd=custom_6=
cmd=custom_7=
cmd=custom_8=
cmd=custom_9=
cmd=custom_10=
cmd=department=
cmd=off_fax=
cmd=first_name=
cmd=home_ph_1=
cmd=home_ph_2=
cmd=last_name=
cmd=mobile=
cmd=office=
cmd=pager=
cmd=off_ph_1=
cmd=postcode=
cmd=state=
cmd=title=
cmd=usr1=
cmd=usr2=
cmd=usr3=

[from]
name=$Aapp_name
gateway=*
email=$Aapp_name
smtp=$Aapp_name
Put your application name here.

[to]

to=recipient name
name=recipient name Fill recipient name, or (if not available) his phone number. Used for better clarity during queue or archive viewing.

company=
dept=
title=
assist_ph=
type=TO

number=phone number Recipient's phone number. Both formats, "+420603123456" or "603123456", are possible.

[to] section can be repeated any times - SMS is then sent to more recipients.

Text file referenced by msg item contains text to be sent. If it is longer than maximum SMS length, it is split to more parts. If it contains czech characters, diacritics is removed.

Binary SMS

Control CTL file should have format according to the following description. Change only items marked by bold italic. Recommend values are written by red color - if not sure, use them.

[system]
type=email
class=3

priority=normal
Valid values are "high", "normal" and "low", where SMS with higher priority jump the queue of lower priority SMS

sent=3ffaede7
SMS creation time - number of seconds from 1.1.1970 as hexanumber. If your application is not able to create this format of time, leave this sample value here.

subject=
display_cc=
display_to=
displayonly=0
nomodify=1

msg=TEST_1_3ffaede7.txt
Name of the text file in the same folder. File contains SMS message in PDU format.

dr=1
1 = Delivery Report requested
0 = DR not requested
Delivery Reports not always supported - it depends on driver and hardware in use.

user_app_id=15454 Application ID of this SMS. MX doesn't process this item, but returns it in all information messages about the SMS, so application knows, what SMS is related to.
If you have no ID to fill in, leave item empty - user_app_id=

from_number=9001230
Phone number which will be set as sender's number for this SMS. This function is supported only by some drivers. You can set only numbers, which you negotiate with mobile operator.
If you don't want set the number, don't create this item!

via_line=line3
Explicit specification of sending line.
If you don't want specify the line, don't create this item!

[user]

cmd=email=$Aapp_name
Put your application name here.

cmd=address=
cmd=assist_n=
cmd=assist_p=
cmd=off_ph_2=
cmd=city=
cmd=company=
cmd=country=
cmd=custom_1=
cmd=custom_2=
cmd=custom_3=
cmd=custom_4=
cmd=custom_5=
cmd=custom_6=
cmd=custom_7=
cmd=custom_8=
cmd=custom_9=
cmd=custom_10=
cmd=department=
cmd=off_fax=
cmd=first_name=
cmd=home_ph_1=
cmd=home_ph_2=
cmd=last_name=
cmd=mobile=
cmd=office=
cmd=pager=
cmd=off_ph_1=
cmd=postcode=
cmd=state=
cmd=title=
cmd=usr1=
cmd=usr2=
cmd=usr3=

[from]

name=$Aapp_name
gateway=*
email=$Aapp_name
smtp=$Aapp_name Put your application name here.

[to]

to=recipient name
name=recipient name Fill recipient name, or (if not available) his phone number. Used for better clarity during queue or archive viewing.

company=
dept=
title=
assist_ph=
type=TO

number=phone number
Recipient's phone number. Both formats, "+420603123456" or "603123456", are possible.

[to] section may not be repeated. Phone number specified here must be the same as coded in PDU message. Some drivers use phone number from PDU for sending; but number in [to] section is used for message routing to correct sending line.

Text file referenced by msg item contains SMS in PDU format - without any other characters, it means without line ends etc. PDU must be full-valued - we recommend to use PduSpy tool for checking.

Reports about message processing

Reports about SMS processing are delivered into (MobilChange)/script/in/(app_name)/ folder. Report always consists of two files:

*.notify.sms - control file
*.txt - data file

Use only msg item from control file, what is link to data file. All necessary information are coded in data file.

WARNING! Don't process messages in way that you are waiting for *.txt files - file sharing problems can arise. Always wait for *.notify.sms file, read it and use text file referenced by msg item.

First item of TXT file is msg_type. It contains type of message you have received. Following types exist, that are related to the sent SMS:

sent_ok - SMS was sent to SMS center. DR wasn't requested.
sent_ok_nodr - SMS was sent to SMS center. DR was requested, but selected sending channel doesn't support DR.
sent_ok_wait - SMS was sent to SMS center. It was not delived for the present, wait for next message.
sent_ok_dr - Message, which caused "sent_ok_wait" report before, was delivered sucessfully.
sent_err_ndr - Message, which caused "sent_ok_wait" report before, was not delivered - it was accepted by SMS center, but delivery attempt failed.
sent_err_timeout - No other information was received in timeout period about message, which caused "sent_ok_wait" report before. Maybe it was delivered, maybe not.
sent_err_send - Message delivery failed.
e_nosms - Your application is prohibited to send SMS - check settings in mxUserManager.

Text file can contain folowing items:

Item name Description Included in message types

msg_type Message type name all

description Human readable description of message type (for debugging etc.) all

name Recipient's name all

number Phone number where SMS was/should be delivered. all except e_nosms

user_app_id Application ID from message being sent all

time Time of sending in YYYY/MM/DD hh:mm:ss format all except e_nosms

operator GSM operator name which network is message sent to.
ATTENTION! It is not in normalized format, data returned by GSM module are written here. all except e_nosms

line Line name through which message was sent all except e_nosms

cost Cost for message sending all except e_nosms

num How many SMS was text split to? all except e_nosms

rcv Time of delivery to the target mobile phone. sent_ok_dr

text Preview of SMS splitting
ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end. all except e_nosms

drtext Text of DR/NDR message from the operator.
ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end. sent_err_ndr. sent_ok_dr, sent_err_timeout

errors Description of errors.
ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end. sent_err_send

Report example:

msg_type=sent_ok_wait
description=Your message has been sent to SMS center. Delivery or non-delivery report will be sent.
name=MZa
user_app_id=15454
number=420777267556
time=2004/01/06 17:29:28
operator=Virtual/Debug
line=line1
cost=1.05
num=1
text=[STX]*stav#F:$AMainRouter test SMS with
end of line[ETX]

Files for formatting reports you can see in (MobilChange)/data/aa/ folder. Item sequence is visible here and also what items are present in what file type.

SMS receiving

Received messages, for which was routing set to given application (via mxRouteCfg), are also transferred into (MobilChange)/script/in/(app_name)/ folder together with reports about sent SMS processing.

CTL/TXT files processing is described here - it is the same for received SMS.

TXT file format for received SMS messages is as follows:

msg_type=rcv_sms Type: received SMS

number=+420603123456 Phone number of the sender

time=2004/01/06 18:24:41 Time of SMS delivery into MX in YYYY/MM/DD hh:mm:ss format

operator=Paegas GSM operator name, which network is GSM module logged in.
ATTENTION! It is not in normalized format, data returned by GSM module are written here.

line=line1 Line name, through which was SMS received.
There is underscore behind line name and phone number which was SMS sent to for Premium SMS, for example line1_9004530.

text=[STX]abc[ETX]
Text of SMS.
If SMS is binary, PDU format of SMS can be here - or nothing.
ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end.

binary=0 0 = text SMS
1 = binary SMS

pdu=0015454454... Message in PDU format - for binary SMS.
It can be present also for text SMS, but it isn't guaranteed.

Capabilities of individual MobilChange sending channels

Driver Binary SMS Delivery reports Setting the sender's number Premium SMS - more numbers on single line Speed

T-Mobile UCP/EMI (emi.dll)
yes no yes yes 10/sec

Vodafone CZ (oskar.dll) yes no yes yes 10/sec

Eurotel BMG (cimd.dll) yes no no no 13/sec

Eurotel M2M (m2m.dll)
yes yes - text and binary SMS, doesn't change message size yes yes 2/min

O2 SMS Connector (WebServices) yes yes - text and binary SMS, doesn't change message size yes yes ?

Siemens and Ericsson GSM modules and phones; 2N and Ericsson GSM gateways yes yes - only for text messages, cuts down SMS text length by a few characters no no 5/min

Nokia GSM modules and phones yes yes - only for text messages, for drtype=128 setting doesn't change message size no no 5/min

[system] type=email
priority=normal	Valid values are "high", "normal" and "low", where SMS with higher priority jump the queue of lower priority SMS
sent=3ffaede7	SMS creation time - number of seconds from 1.1.1970 as hexanumber. If your application is not able to create this format of time, leave this sample value here. TIP: printf( "%08.8x", time() );
subject=	Subject of e-mail message. Has no meaning for messages generated by application = leave empty.
nomodify=1	1 = Do not modify message text. 0 = Reformat the message - removes redundant spaces, adds info about sender...
display_cc= display_to=
msg=TEST_1_3ffaede7.txt	Name of the text file in the same folder. File contains SMS text. If transport channel allows it, it is sent in full quality, it means including line ends and similar chars.
dr=1	1 = Delivery Report requested 0 = DR not requested Delivery Reports not always supported - it depends on driver and hardware in use.
displayonly=0	1 = "display only "SMS - displays even if user has SMS storage full. Next SMS of the same type rewrites it. 0 = normal SMS
user_app_id=15454	Application ID of this SMS. MX doesn't process this item, but returns it in all information messages about the SMS, so application knows, what SMS is related to. If you have no ID to fill in, leave item empty - user_app_id=
replyrequired=0	1 = When SMS is displayed, phone notifies the user that sender asked for a reply and usually offers writting of the reply. Not supported by all phones - if phone has not this feature, SMS is normally displayed. 0 = Normal SMS
from_number=9001230	Phone number which will be set as sender's number for this SMS. This function is supported only by some drivers. You can set only numbers, which you negotiate with mobile operator. If you don't want set the number, don't create this item!
via_line=line3	Explicit specification of sending line. If you don't want specify the line, don't create this item!
maxlen=3	Maximum number of SMS, which is message split to if longer than 160 chars. If you dont want specify this number, don't create this item!
[user] cmd=email=$Aapp_name	Put your application name here.
cmd=address= cmd=assist_n= cmd=assist_p= cmd=off_ph_2= cmd=city= cmd=company= cmd=country= cmd=custom_1= cmd=custom_2= cmd=custom_3= cmd=custom_4= cmd=custom_5= cmd=custom_6= cmd=custom_7= cmd=custom_8= cmd=custom_9= cmd=custom_10= cmd=department= cmd=off_fax= cmd=first_name= cmd=home_ph_1= cmd=home_ph_2= cmd=last_name= cmd=mobile= cmd=office= cmd=pager= cmd=off_ph_1= cmd=postcode= cmd=state= cmd=title= cmd=usr1= cmd=usr2= cmd=usr3=
[from] name=$Aapp_name gateway=* email=$Aapp_name smtp=$Aapp_name	Put your application name here.
[to]
to=recipient name name=recipient name	Fill recipient name, or (if not available) his phone number. Used for better clarity during queue or archive viewing.
company= dept= title= assist_ph= type=TO
number=phone number	Recipient's phone number. Both formats, "+420603123456" or "603123456", are possible.

[system] type=email class=3
priority=normal	Valid values are "high", "normal" and "low", where SMS with higher priority jump the queue of lower priority SMS
sent=3ffaede7	SMS creation time - number of seconds from 1.1.1970 as hexanumber. If your application is not able to create this format of time, leave this sample value here.
subject= display_cc= display_to= displayonly=0 nomodify=1
msg=TEST_1_3ffaede7.txt	Name of the text file in the same folder. File contains SMS message in PDU format.
dr=1	1 = Delivery Report requested 0 = DR not requested Delivery Reports not always supported - it depends on driver and hardware in use.
user_app_id=15454	Application ID of this SMS. MX doesn't process this item, but returns it in all information messages about the SMS, so application knows, what SMS is related to. If you have no ID to fill in, leave item empty - user_app_id=
from_number=9001230	Phone number which will be set as sender's number for this SMS. This function is supported only by some drivers. You can set only numbers, which you negotiate with mobile operator. If you don't want set the number, don't create this item!
via_line=line3	Explicit specification of sending line. If you don't want specify the line, don't create this item!
[user]
cmd=email=$Aapp_name	Put your application name here.
cmd=address= cmd=assist_n= cmd=assist_p= cmd=off_ph_2= cmd=city= cmd=company= cmd=country= cmd=custom_1= cmd=custom_2= cmd=custom_3= cmd=custom_4= cmd=custom_5= cmd=custom_6= cmd=custom_7= cmd=custom_8= cmd=custom_9= cmd=custom_10= cmd=department= cmd=off_fax= cmd=first_name= cmd=home_ph_1= cmd=home_ph_2= cmd=last_name= cmd=mobile= cmd=office= cmd=pager= cmd=off_ph_1= cmd=postcode= cmd=state= cmd=title= cmd=usr1= cmd=usr2= cmd=usr3= [from]
name=$Aapp_name gateway=* email=$Aapp_name smtp=$Aapp_name	Put your application name here.
[to]
to=recipient name name=recipient name	Fill recipient name, or (if not available) his phone number. Used for better clarity during queue or archive viewing.
company= dept= title= assist_ph= type=TO
number=phone number	Recipient's phone number. Both formats, "+420603123456" or "603123456", are possible.

Item name	Description	Included in message types
msg_type	Message type name	all
description	Human readable description of message type (for debugging etc.)	all
name	Recipient's name	all
number	Phone number where SMS was/should be delivered.	all except e_nosms
user_app_id	Application ID from message being sent	all
time	Time of sending in YYYY/MM/DD hh:mm:ss format	all except e_nosms
operator	GSM operator name which network is message sent to. ATTENTION! It is not in normalized format, data returned by GSM module are written here.	all except e_nosms
line	Line name through which message was sent	all except e_nosms
cost	Cost for message sending	all except e_nosms
num	How many SMS was text split to?	all except e_nosms
rcv	Time of delivery to the target mobile phone.	sent_ok_dr
text	Preview of SMS splitting ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end.	all except e_nosms
drtext	Text of DR/NDR message from the operator. ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end.	sent_err_ndr. sent_ok_dr, sent_err_timeout
errors	Description of errors. ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end.	sent_err_send

msg_type=rcv_sms	Type: received SMS
number=+420603123456	Phone number of the sender
time=2004/01/06 18:24:41	Time of SMS delivery into MX in YYYY/MM/DD hh:mm:ss format
operator=Paegas	GSM operator name, which network is GSM module logged in. ATTENTION! It is not in normalized format, data returned by GSM module are written here.
line=line1	Line name, through which was SMS received. There is underscore behind line name and phone number which was SMS sent to for Premium SMS, for example line1_9004530.
text=[STX]abc[ETX]	Text of SMS. If SMS is binary, PDU format of SMS can be here - or nothing. ATTENTION! This item can contain also characters like "end of line" etc., so it is marked out by control codes - 0x02 (STX) at the beginning, 0x03 (ETX) at the end.
binary=0	0 = text SMS 1 = binary SMS
pdu=0015454454...	Message in PDU format - for binary SMS. It can be present also for text SMS, but it isn't guaranteed.

Driver	Binary SMS	Delivery reports	Setting the sender's number	Premium SMS - more numbers on single line	Speed
T-Mobile UCP/EMI (emi.dll)	yes	no	yes	yes	10/sec
Vodafone CZ (oskar.dll)	yes	no	yes	yes	10/sec
Eurotel BMG (cimd.dll)	yes	no	no	no	13/sec
Eurotel M2M (m2m.dll)	yes	yes - text and binary SMS, doesn't change message size	yes	yes	2/min
O2 SMS Connector (WebServices)	yes	yes - text and binary SMS, doesn't change message size	yes	yes	?
Siemens and Ericsson GSM modules and phones; 2N and Ericsson GSM gateways	yes	yes - only for text messages, cuts down SMS text length by a few characters	no	no	5/min
Nokia GSM modules and phones	yes	yes - only for text messages, for drtype=128 setting doesn't change message size	no	no	5/min