Sending SMS using the Application Programming Interface - MCTel

VIDEOSMS HTTP/HTML Interface Manual v. 1.2IntroductionIntroductionMost people in developed countries own a mobile phone and the recreational and professionaluse of mobile applications and services is growing at a very fast rate. The mobile phonemarket has now reached maturity regarding the usage of voice calls, but the mobile andconsumers data applications are only beginning their expansion.With VIDEOSMS software set, Monaco Telematique MCTEL offers a complete solution toeasily integrate this new technology to offer to your customers and users advancedapplications that could be reached from any mobile phone, anywhere, anytime.Monaco Telematique MCTEL SMS solutions include a complete service and software packallowing to easily send and process SMS from your computer applications and Web services.Amongst those functions, the HTTP/HTML Web interface, described in this manual, allowsany computer application or Web service to send SMS messages by simply sending a HTTPGET or POST request.How SMS works ?SMS stands for Short Message Service, a mobile facility allowing to send and receive text oreven binary messages to and from a mobile phone.SMS are very easy to use even if the mobile phone keyboard is usually not very well suited toalphabetic data collection. More than 160 billion SMS are exchanged each month in Europeancountries.SMS use the GSM special signaling channel instead of the voice channel and is therefore avery reliable media channel. SMS may often be transmitted even when the mobile network isoverloaded 1According to the origin of the message, SMS could be named:• Mobile Originated (MO): SMS-MO are sent from a mobile phone and could be senteither to another mobile phone (such when a mobile subscriber sends a personalmessage to another subscriber) or to a computer application that will process themessage.• Mobile Terminated (MT): SMS-MT are transmitted to a mobile phone. They alsocould be sent by another mobile phone or generated by a computer application.The SMS processing computer applications usually runs on corporate servers that areconnected to the SMS network through specialized connectors and gateways connected to theSMS Centers of mobile operators. As they are processing huge number of SMS and in order1 The only exception beeing the new year event where even the GSM signalling channel is congested byhundreds of millions of SMS exchanged by users.Monaco Telematique MCTEL 5 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2to make them easier to remember, these servers are assigned short numbers instead of thetraditional 10-digits mobile numbers. These short numbers are called short codes and containsonly 4 to 6 digits.Each short number is usually specific to a given country and shared by all operators of thecountry.Glossary• Alias : in several countries, on Premium SMS services, the user mobile number(MSISDN) is masked by the operator and replaced by an unique alias number, in orderto avoid the creation of unauthorized mobile numbers databases for marketingpurposes byh the information provider.• Short code : abbreviated number (usually from 4 to 6 digits) allocated to a SMSserver running Premium SMS applications and allowing the user to send his/hermessage to a short code easy to remember instead of a 10 digits full mobile number.• OTA (Over the Air) : this technology is used to download binary data to a mobilephone, for example : logos, ringtones, email or Wap configuration download by themobile operator, SIM card customization by mobile network operator.• Push-SMS : sending an unsolicited SMS-MT to a mobile user.• SMS = Short Message Service : short text or binary message exchanged between twomobile phones 2 or a mobile phone and a computer application.• SMS-C : SMS Service Center : is the SMS transmission platform run by the mobileoperator. It uses a specific protocol to exchange SMS messages between mobilephones and the VIDEOSMS software (either installed on a customer system or run bythe Monaco Telematique shared host center). The SMS-C use a store and forwardtechnology allowing it to store a message until a given mobile phone becomesreachable. Monaco Telematique VIDEOSMS software is able to interwork with anySMS-C worldwide.• SMS-MO (Mobile Originated) : SMS sent from a mobile phone.• SMS-MT (Mobile Terminated) : SMS sent to a mobile phone.2 In numerous countries, it is also possible to send and receive SMS message from ordinary or advanced phonesconnected to the switched telephonic network.Monaco Telematique MCTEL 6 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2What could be done with SMS services ?The applications of SMS are nearly endless : this channel could be used to offer a wide rangeof services to mobile users.Bulk SMS : sending personalized messages to recipientsSMS is a very effective way to send immediately a customized message to one or thousandsof users.Figure 1: A computer system or application sends automatically personalized SMS-MT to mobilerecipientsThey could be used to:• Improve communication between employees by integrating SMS within theenterprise messaging system and other integrated software (ERP) :o It is possible to send a message through SMS from the enterprise messagingsystem.o Any company application could automatically dispatch information throughSMS to its intended recipient.o The company ERP or a secretary could automatically forward to the user:• His new appointments: using vCalendar format, they will be displayedand automatically entered in the phone calendar application.• His new customers data: they will be displayed and automaticallyentered in the mobile directory thanks to the vCard format.o SMS is a very reliable network : all messages will be acknowledged by thenetwork when received by mobile recipient. In case of transmission problem(e.g. mobile unreachable), an alarm could be generated and the message couldbe automatically routed through another network (e.g. fax).• Send informational or promotional messages, customized or not. For example :o Banks could send account balances at regular intervals.o A company could perform direct marketing operations to its customers.• Automatically send time-sensitive personalized information at predefined timesor when a given event occurs : the user could subscribe in advance to the serviceusing SMS, Web, or any other method and he select which kind of information he willMonaco Telematique MCTEL 7 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2receive. The SMS application will then send him at predefined times or when a giveneven occurs:o Updated informations :• Weather of the day• Account balance• Daily news alerts• Sports updateso Alarm messages :• Account balance debtor.• Delay or cancellation of a flight.• Postponement of an appointmento Specific message on a given event:• When a stock value reach a given amount.• When an ad matching the criteria specified in advance is passed.• When a given news event occur (e.g. sporting match result).• When a pre-sold item becomes available.• And so on.Device customizationThe market of phone set customization is currently a very lucrative service in Europe: usersare choosing and downloading ringtones, logos or images on their handset.Although simple in principle, these services are complicated by the wide variety of handsetsand supported standards. The added value of these services remains quite low: the user ask fora ringtone or a logo and get it, either through SMS or Wap push.More added value applications may be built where the user download a Java game to be runon their phone. Advanced game or applications may be downloaded this way, and are selectedeither by SMS or more often via mobile Wap browsing.Interactive processing : answering user requestThose applications may offer very high added value as they may allow any mobile user toperform any kind of request thru their mobile phone.From the text content of the request SMS transmitted by the user, the server will be able toperform any kind of data processing: relational database search,The exclusive Monaco Telematique SMS Grabber and Formatter technology allows toautomatically perform search on existing Web sites, FTP files, videotex or computerapplications according to user requests to immediately create a high value added SMS servicetaking advantage of the existing applications without any new development.Monaco Telematique MCTEL 8 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Figure 2: Example of interactive SMS service : the user sends a SMS-MO request that will be forwardedby his mobile network operator to the host server of the information provider. After processing, theinformation provider will send back one (or several) SMS-MT in answer with the requested information.Amongst possible examples :• Real-time request by sale forces of available stock of a given item with current price.• SMS online banking operations: get account balance, get an alarm SMS message if thebalance is negative,• Taxi request: the system may even in some countries find the user geographicalposition in order to forward him the nearest taxi.• Get the status of a plane flight.• Interworking between SMS network and other networks: fax, email, telex, and so on.• Meteorological information retrieval either for the general public or for special uses(aeronautical, nautical, mountain…).• Games.The Premium model allows the SMS information provider to get paid for each userrequest: depending on the short number used, charging rate selected and his contract with thenetwork operator, the information provider will earn a given amount at each SMS-MO requestsent by a mobile user. The mobile user will be invoiced directly on his phone bill by hisnetwork operator, and the network operator will pay back his share to the informationprovider.Monaco Telematique MCTEL 9 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2SMS characteristicsSMS featuresSize and type of messagesShort messages may contain:• Text data : the size of a single text SMS may not exceed 160 characters.• Binary data, such ringtones and pictures : the size of a single binary SMS is limitedto 140 bytes. Binary SMS may be used:o to send a ringtone or logo to the mobile.o to push a Wap URL (Wap Push command) to the mobile, allowing the user toconnect to the pushed URL in order to access a Wap service or to downloadany kind of content: ringtone, picture, executable content.o to send OTA (Over The Air) commands to configure the mobile remotely.It is nevertheless possible to transmit longer messages : a longer message can be split and sentas several SMS messages that will be ‘concatenated’ upon reception by the mobile in order toreconstitute the complete original message.Transmission mechanism, error processing, time to liveSMS are transmitted by the mobile network operator to the the recipient mobile phone of thesusbcriber. When the recipient is unreachable (mobile offline or outside network coverage forexample), the message will be stored in the SMS Center of the mobile operator to betransmitted again should the mobile becomes available.After a given time delay (the SMS time to live), the SMS will be destroyed if not successfullytransmitted and a non-delivery acknowledgment will be returned to the sender.The application generating the SMS may define :• The maximal SMS time to live that could not exceed a limit depending on the network(often 3 days).• The transmission date and time for delayed SMS : they will be stored and transmittedonly after specified time.Display and storage modesThe processing of the received SMS may vary depending on the SMS message class:• Message stored in the phone memory.• Message stored on SIM. If the SIM is full, the SMS may be lost.Monaco Telematique MCTEL 10 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2• Flash message displayed immediately on the screen. The advantage is the display doesnot need any user action. The drawback is the message will not be stored and will bedestroyed after reading.AcknowledgementsThe sending computer application may get an acknowledgement when the SMS has beensuccessfully transmitted to its recipient or an error status with detailed error cause in case ofproblem.The computer application may at all time retrieve the current message status:• SMS-MT submitted to the gateway.• SMS-MT transmitted to mobile operator SMS-C.• SMS-MT delivered to the mobile phone.• SMS-MT could not be delivered to the mobile phone, with error cause. Depending onthe error cause, retries may be performed or not.Interworking with SMS networksThe link between your computer applications or Web service and the mobile networkoperators SMS-Centers is provided by the MCTEL worldwide VideoSMS Gateway.With this solution, your could run on your own computer systems your value-addedapplications using the client/server VIDEOSMS interfaces to use the Monaco Telematiqueworldwide SMS shared hosting center for network connectivity. In this case, you will get thesame flexibility and advanced processing features than if you would have purchased acomplete SMS server, without the associated costs and without the need to connect andmanage all SMS mobile networks connectivity.However this solution is completely flexible and your could anytime purchase a VideoSMSgateway from MCTEL, in order to operate yourself your own SMS gateway, running on asystem in your premises where VideoSMS Gateway has been installed. Your system must beconnected and interwork with all mobile networks operators or international gateways neededfor your application. That means that networking and infrastructure costs are to be taken inaccount.Monaco Telematique MCTEL 11 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2How to send SMS automatically (push-SMS)The automated sending of personalized SMS from computer applications, Web sites,enterprise messaging system or emailing tools could be set up very quickly, at a very lowcost, and without setup fee. The only requirement is to have an Internet access available(X.25 also supported).Sending SMS from computer applications or Web sitesFrom any PC, computing application or Web site, it is very easy to send SMS :• No specific equipment is needed, as the Monaco Telematique gateway will take incharge the interworking with the mobile operators. Of course, if the customer wish, acomplete SMS gateway may also be supplied and installed on the customer computercenter: in this case the customer will be directly connected to the mobile operators.• Push SMS sending tools are supplied free of charge: PC program, HTTP/HTMLand FTP/XML tools, API.• No subscription is necessary, the only cost incurred are the transmission costs of theSMS successfully sent.From the IT manager point of view, the integration of push SMS functions in the companycomputing applications, ERP and messaging system is very quick and easy. The push SMScould be sent:• Calling a Web cgi on the MCTEL Web/SMS gateway.• Creating a XML text file describing the SMS to send and transmit it to MonacoTelematique SMS gateway through FTP or using a XML sender.• Integrating the VIDEOSMS/Client functions within the computer applications : forexample sms_send function request the transmission of a push SMS, thesms_read_status get back the SMS transmission status.Integrating Push-SMS send to any computer application or Web service is very easy andcould be setup almost immediately. Several methods could be used to send the SMS (alldocuments could be downloaded from http://www.smsfax.com ):• HTTP/HTML Web interface, described in this document.• FTP/XML file interface, documented in the "VideoSMS FTP/XML InterfaceManual".• SMTP email interface.• The VideoSMS Application Programming Interface (API), described in the"VideoSMS Application Programming Interface Functions Manual".PrerequisitesUsing the HTTP/HTML Web interface, you only need to send a HTTP GET or POST requestto a Web URL to integrate SMS functions in your applications and Web services.Monaco Telematique MCTEL 12 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2If your network is secured by a firewall, it must be configured to allow outgoing calls to theSMS Web gateway of Monaco Telematique, on the port 80 (as this is the standard port forWeb, this is usually already configured in the company firewall).User Interface ErgonomicsWhen sending push-SMS, try to design the content of the SMS in order to keep in mindergonomics recommendations to offer the best possible service for the SMS recipient.Message sizeSend SMS of reasonable size, as a single text SMS message could not exceed 160 characters.It is nevertheless possible to send bigger SMS messages: they will be automatically split intoseveral smaller messages and concatenated by the recipient mobile phone.Regarding SMS message size :• A single SMS message may contain up to 160 alphanumeric characters encoded toGSM format 3 . If the message size is greater, the message will be split in several partstransmitted as separated SMS. The recipient mobile phone will automaticallyconcatenate the received parts in order to reconstitute the original complete message.On most phones, up to 3 parts are supported, allowing a maximum message size of469 characters (less than 160 x 4, because for concatenated messages, 7 header bytesare used to store concatenation information).• A binary SMS could contain up to 140 bytes. It is also to split a greater message totransmit up to 384 bytes in 3 SMS messages.Number of SMS Alphanumeric characters size Binary data sizemessages1 1 to 160 1 to 1332 161 to 206 134 to 2563 207 to 469 257 to 3844 4 470 to 623 385 to 512In order for an application to be able to send a large message, the easier way is to send to themobile a Wap Push SMS message enabling the recipient to automatically connect and displaya Wap page containing the data (provided the recipient subscription and phone are Wapenabled).Presentation of most relevant data3 If the SMS alphabet encoding used is Unicode, usually used for non-latin alphabets (arabic, japanese,chineese), the size of a single SMS message could not exceed 70 Unicode characters.4 Numerous phones does not support the sending of more than 3 concatenated messages. Except if the recipientphone is known to support them, it is therefore not recommended to send messages of more than 469alphanumeric characters 384 binary bytes.Monaco Telematique MCTEL 13 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Most phones are not able to display the complete length of a big SMS message because of thesmall size of the display. The user will have to browse on the display to read all the message.It is usually recommended to try to present the most relevant data in the most compact formpossible at the beginning of the message in order to allow the user to read immediately theimportant part of the message.Character Set• Try to use Ascii ISO 8859-1 (IsoLatin 1) characters also present in the GSM characterset. If you use ISO 8859-1 characters not existing in the GSM character set (forexample sparsely used accented characters), they will be replaced by their nearestequivalent (e.g.: â by a) or if no equivalent cound be found by a '?'. The Appendix 2shows the GSM character set along with the ISO 8859-1 to GSM translation.• If needed, you could use Unicode alphabet to transmit non-latin characters (arabic,russian, greek 5 , japanese, chineese, etc.). Using the Unicode alphabet will limit thenumber of characters for a single SMS to 70 instead of 160.Sender identificationDepending on the country and mobile network operator of the recipient and your accountprofile, the SMS you will send may bear your mobile phone identification number, yourcompany alphanumeric identifier, or may be sent from a generic SMS short id.When the SMS is sent from a generic short id, you must include within the SMS text theneeded information allowing the recipient to understand whom has sent him a message.Usually, this information is presented either at the beginning of the message (e.g.: MCTEL:message body) or at the end of the message (e.g. send from MCTEL).Conforming to deontological rules and applicable lawsNeedless to say, all the messages sent must be conformant to:• all domestic and international laws applicable. It is of course prohibited to sendoffensive, illegal, prohibited content.• most mobile operators and countries prohibit the sending of advertising messages torecipient who have not accepted to receive such messages (said "opt-in"). An easyway must be available to allow an user to ask to be removed from the distribution list"opt-out".• most mobile operators prohibit advertising messages or sponsored messages fromcompeting mobile network operators.5 Instead of using Unicode character set for Greek messages, the best solution is usually to take advantage of theGreek characters included in the GSM character set, however only uppercase characters will be available.Monaco Telematique MCTEL 14 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2SMTP email InterfaceYou could also send SMS directly by email using the VideoSMS STMP Gateway, from anymail sender.VIDEOSMS/PC SoftwareIf you do not want to integrate SMS features in your computer application or Web service, butsimply use an easy to use PC application with Outlook integration to send SMS, you coulddownload and install the free VideoSMS/PC SMS Desktop sender from www.smsfax.com.Monaco Telematique MCTEL 16 July 2004

VAX 6240VIDEOSMS HTTP/HTML Interface Manual v. 1.2Accessing SMS features using MCTEL HTTP GatewayIntroductionHTTP/1.1 POST or GETIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIIHTTP/1.1 ReplyCustomer serverMCTEL VIDEOSMSHTTP GatewayFigure 3: MCTEL VideoSMS gateway communication using Web HTTP/HTML protocolWhen using the HTTP/HTML interface, the customer Web application service or computerapplication will communicate with MCTEL SMS Gateway using HTTP GET or POSTrequests.Requests are available to perform various kind of operations:• sending SMS messages.• retrieving detailed status of a SMS message previously submitted.• sending Wap Push commands by SMS.Connecting to the MCTEL SMS HTTP GatewayThe client should send a HTTP POST or GET request to the VIDEOSMS HTTP Gateway andwait for the gateway response.The following URLs are used to connect to the gateway:• http://www.smsfax.com/cgi-bin/sendsms.cgi?command=sendsms&... to send amessage• http://www.smsfax.com/cgi-bin/sendsms.cgi?command=readstatus&... to check if agiven message has successfully been transmitted.The calls should be made to the symbolic DNS name of the HTTP gateway(www.smsfax.com) instead of its IP address because several systems offering load balancingand fault tolerant configuration and used and because furthermore the IP address of thegateways are subject to change without prior notice.sont susceptibles d’être modifiées à tout moment.Monaco Telematique MCTEL 17 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Perform the HTTP requests in NoCache mode if a HTTP proxy is installed on your enterprisenetwork.When connecting it is necessary to specifiy your username and password (and in some casea company name and optionnaly a company password). You could get these parameters byseveral ways:• your company has opened an account: your parameters has been given to you byMCTEL.• your are a MCTEL partner: same• you could also immediately (if not already done) open your own prepaid SMS accounton http://www.smsfax.com by specifying your mobile number and email address andalso the username you wish to use. If this username is not already in use, you willreceive immediately your account password by SMS on your mobile along with somefree SMS units to test your new account. You could purchase SMS units on youraccount by credit card, check and in some countries by sending a Premium SMS orconnecting to the videotex network.You could also open your account by downloading and installing the VideoSMS/PCDesktop SMS sender from http://www.smsfax.com.In all cases, whatever the method used to open your account, you could use yourusername and password to send SMS from all the methods supplied by SMS: PCDesktop sender, Web, SMS Gateway API, SMS FTP/XML Interface and the SMSHTTP/HTML interface described in this document.Submitting requests to the gatewayThe client should transmit requests using either HTTP GET or HTTP POST requests to thegateway. Submissions sent to the gateway should conform to the syntax described below.Using HTTP GET requestsFollow the following procedure :• connect to the www.smsfax.com gateway on port 8080 (see above).• transmit the GET request to the /cgi-bin/sendsms.cgi URI• send the GET request containing the needed parameters, transmitted after the URI andthe ? character, each parameter beeing encoded and separated by & (parametersencoding and formating are usually automatically performed by HTTP functions).• Do not close the connection after the request in order to be able to receive the replyfrom the gateway.Using HTTP POST requestsFollow the following procedure :• connect to the www.smsfax.com gateway on port 8080 (see above).• transmit the POST request to the /cgi-bin/sendsms.cgi URI.• The POST request must contain the following mandatory HTTP headers, separatedfrom the message content by :Monaco Telematique MCTEL 18 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2o Content-type : application/x-www-form-urlencodedo Accept-charset : utf-8o Content-length : nnn (where nnn is the length of the body).• Do not close the connection after the request in order to be able to receive the replyfrom the gateway.Request format and attributesThe HTTP requests sent to the URI must contains mandatory parameters, optional parametersmay be added. The required parameters may vary according to the type of HTTP request(SMS send, SMS check status, SMS Wap Push, and so on.). The attributes values may notcontain leading spaces, linefeed characters or quotation marks.Common parameters for all requestsAttribute name Meaning ExampleMandatory Attributes‘Command’ Specify the type of command to be performed : sendsms• ‘sendsms': sending a SMS or othermessage types (fax, telex, email...).• ‘readstatus’: check the status of apreviously transmitted message.• 'wappush': send a Wap Push commandby SMS‘UserId’‘UserPwd’‘Version’NB : according to the command specified, seebelow the mandatory and optional attributesto be specified.Registered username for authentication.If you have created yourself your own accounton www.smsfax.com or using theVideoSMS/PC Desktop sender program, specifyyour username. In this case, all SMS sent fromusing the HTTP/HTML interface will becharged to your www.smsfax.com account.Username is not case sensitive.Password securing the username, forauthentication.If you have created yourself your own accounton www.smsfax.com or using theVideoSMS/PC Destop sender program, specifyyour password that has been transmitted by thegateway to your mobile phone.Password are case sensitive.Protocol version number. The current protocolversion is 1.0Optional AttributesmctelX7u2Hzq7w11.0Monaco Telematique MCTEL 19 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2‘TestMode’ Test mode :2• 0 (default): inactive, normal SMSprocessing• 1 : test mode activated: authenticationand valid syntax parsing is checked bythe gateway, but the message is nottransmitted to the mobile and the useraccount is not charged.• 2 : same as mode 1, but the receivedparameters are displayed in the returnpage in order to allow easier applicationdebugging.‘CompanyId’ Master account name of the company whom the ACOMPANYuser account is associated from. By default,when this parameter is not specified, theusername specified by ‘UserId’ is considered asdepending of « MCTELWEBSMS » masteraccount.If no CompanyId has been specified to you, donot specify this parameter.‘CompanyPwd’ Company password. X7u2Hzq7w1Additional parameters when « command=sendsms »Attribute name Meaning ExampleMandatory Attributes‘DestNum’Phone number (MSISDN) of the recipient, at %2B33607080910international format, prefixed by a + (encoded%2B on HTTP)‘MsgContent’ Content of the message to be transmitted to the ‘hello world’recipient :• Text message (by default), encodedaccording selected character set (ASCIIor ISO 8859-1 as default) that will beautomatically converted to SMS format.• Message with binary payloadOptional Attributes‘ContentType’ SMS content type :TEXT• TEXT : default• HEXA : binary data hex-encodedNB : to activate HEX mode on your account,please contact MCTEL‘Encoding’ Encoding character set :ISO8859-1• ISO8859-1 : default, will beautomatically converted to GSMcharacter set according to Annex 2.• Other supported character set (ex:Unicode)Monaco Telematique MCTEL 20 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2‘NetworkType’ Recipient terminal equipment type :• sms: defaut: mobile with SMS support• fax• telex• email‘OptDeferred’ Defferred delivery request :• 0 (default) : none (immediate)• 1 : the attributes ‘OptDefDate’ and‘OptDefTime’ specify the date and timeof message transmission.‘OptDefDate’ Deffered delivery date, encoded dd/mm/yyyy.Skipped if ‘OptDeferred’ = 0 or unspecified‘OptDefTime’ Deffered delivery time,encoded hh:mm.Skipped if ‘OptDeferred’ = 0 or unspecified‘OptExpire’ Message expiration date : the message will bediscarded if the delivery could not succeedbefore the expiration date• 0 (default) : not specified (GSM networkexpiration settings apply)• 1 : the attributes ‘OptExpiryDate’ and‘OptExpiryTime’ specify the date andtime of message transmission.‘OptExpiryDate’ Expiration date (format dd/mm/yyyy).Ignored if ‘OptExpire’ = 0.‘OptExpiryTime’ Expiration time (format hh:mm).Ignored if ‘OptExpire’ = 0.‘OptEmailOnSuccess’ Request for email confirmation on SMSsuccessful delivery :• 0 (default) : inactive• 1 : active, the attribute‘OptEmailAddress’ must specify theemail address to which the deliveryreport must be sent.‘OptEmailOnError’ Request for email alert on SMS transmissionerror :• 0 (défaut) : inactive• 1 : active, the attribute‘OptEmailAddress’ must specify theemail address to which the non-delivery‘OptEmailAddress’‘PrivateData’report must be sent.Email address for delivery or non-deliveryreports.Ignored if ‘OptEmailOnSuccess’ = 0 AND‘OptEmailOnError’ = 0.Private text field available to store user-specificinformation, maximum length 50 characters.The content of this field is ignored and returnedas is on the result page.sms025/07/200415:30031/08/200415:3000mybox@mydomain.commy private infoMonaco Telematique MCTEL 21 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2‘PrivateReference’ Text field available to store a program-specificinternal reference entry, maximum length 15characters. This private reference will bereturned with the SMS reference number,allowing the sending program to easily retrievethe match between its internal reference and theSMS reference number in case of multiple sendoperations.‘OptFlash’ Flash message option :• 0 (défaut) : inactive (normal SMS)• 1 : active: immediate display on mobilescreen, without storage amongstreceived SMS.‘originator’ Allows to specify the numeric or alphanumericsender identification. This feature is onlysupported on some networks and depends onuser account profile.Number fields must be between 6 and 14 digits,inclusive.‘udhi’Allow to specify an User Data Header forbinary SMS. The UDH must be hex-encoded.Refer to additional documentation for UDH use."ABC123456"0mctelAdditional parameters when « command=readstatus »Attribute name Meaning ExampleMandatory Attributes‘MsgRef’Internal reference number of the SMS whose5817state is requested.This value is those returned by the 'sendsms'request status in the tag.Optional AttributesNoneAdditional parameters when « command=wappush »AttributeMeaningExamplenameMandatory Attributes‘WapURL’ Wap URL to be pushed by SMS http://wap.smsfax.com/AddamsFamily.midOptional Attributes'WapText' Text to be displayed on mobile terminal Addams Family ringtone'WapContent' Wap data content in binary format'OptSingleShot' When OptSingleShot=1, the binary content ofthe Wap URL could only be downloaded once(eg Premium content)Monaco Telematique MCTEL 22 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Return statusWhen receiving a HTTP command, the HTTP SMS gateway will perform the followingoperations:• parsing attributes and syntax checking.• user authentication, access rights check.• user account credit check when send operation for a prepaid account.• execute the required operation (send SMS, check SMS status, send Wap Pushmessage, and so on).The request result status will be immediately returned by the gateway in HTML format.The application having performed the POST or GET operation must check the return status asfollow:• If the gateway times out, no response is returned to the client, no SMS message will besent to the mobile, and the customer account will not be charged.• When the request has been processed (even if an error has occured), the gateway willreturn the '200 OK' HTTP code, then a HTML page with XML tags, encoded asfollow:ValueMonaco Telematique MCTEL 23 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Tags returned for all the requestsTag Meaning Example Numeric result status (success or error) of the1request. Success is 1, all other values are errorcodes listed in appendix 1. Text result status of the request. Success isOK'OK'.Additional tags returned when « command=sendsms »The following tags are only returned when SMSRESULT=1 (SMS submitted successfully):Tag Meaning ExempleUnique internal reference number assigned 35817to the SMS. This reference number must bepassed to the ‘command=readstatus’ requestto get the status of a submitted SMS. If the ‘PrivateData’ attribute was included My private infoin the submit operation, its content isreturned as is. If the ‘PrivateReference’ attribute was ABC123456specified during the submit operation, itscontent is returned.Additional tags returned when « command=readstatus »The following tags are only returned when SMSRESULT=1 (SMS successfully retrieved):Tag Meaning Example Numeric state of the message. The possible1values are:• 1 : successfully delivered to recipient(reception date stored in attribute)• 2 : fatal error, could not transmit• 3 : forwarded to recipient (no deliveryacknowledgement notification )• 12 : en route/pending• 13 : transient error (will be retried atregular intervals)• 18 : processed by mobile operator• 19 : waiting for transmission (priority)• 21 : delayed delivery SMS, waiting forspecified deffered delivery date/time• 99 : unknown error Message state described in text format Received byrecipient at xxxxMonaco Telematique MCTEL 24 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2 Numeric detailed error cause. A messagesuccessfully transmitted to recipient return 1.Please refer to appendex 1 for the list of errorcodes.< MSGTEXTERROR> Detailed error cause in text format explainingthe error code. When known, specify the date/time of thesuccessful reception by recipient mobile, or incase of an error of the last transmission retry.51Invalid or unknownmobile number27/07/2004 - 15:33Note : when the TestMode has been selected and set to 2 (TestMode=2), the HTML page willthen list all the request attributes received in order to help debugging the applications. In thiscase, the SMS will not be transmitted to the recipient and the user account will not beencharged.ExamplesExample of simple GET requestFrom any Web browser, you could test the sending of a SMS message by calling the URLbelow (modify your account userid and userpwd and the mobile number to use) :http://www.smsfax.com/cgibin/sendsms.cgi?command=sendsms&version=1.0&userid=mctel&userpwd=123456&msgcontent='This is a test'&destnum=%2B33607998877You will receive a return status Web page formatted as below (use the 'View source'command of your browser to see all the HTML source code) :sendsms1 Ok 138184 Warning: if the IP address check has been enabled (recommended), only GET or POSTrequests originating for the enabled authorized address will be accepted.To request the status of a SMS previously sent (specify the SMS reference returned in the field):Monaco Telematique MCTEL 25 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2http://www.smsfax.com/cgibin/sendsms.cgi?command=readstatus&version=1.0&userid=mctel&userpwd=123456&msgref=138184You will receive a return status Web page formatted as below :sendsms1 Ok 138184 ABC123456 1 Received by recipient 0 Ok 27/07/2004 - 15:33 The field will only be present if the sending program has specified aprivate reference number.Visual Basic exampleIt is very easy to send a SMS from any Visual Basic program, use the example below as atemplate.'Uses Component - Microsoft Internet Transfer Control 6.0'Place Inet Control on FormDim strUrl As StringDim strCommand As StringDim strUserId As StringDim strUserPwd As StringDim strMsgContent As StringDim strDestNum As StringDim strVersion As StringDim pageresponse As StringstrUrl = "http://www.smsfax.com/cgi-bin/sendsms.cgi?"strCommand = "Command=SendSMS"strUserId = "&UserId=mctel"strUserPwd = "&UserPwd=3gap9es3"strMsgContent = "&MsgContent=hello world"strDestNum = "&DestNum=+33607998877"StrVersion = "&version=1.0"strSend = strUrl + strCommand + strUsername + strPassword + strContent + strNumberMonaco Telematique MCTEL 26 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2+ strVersion'Send message and get return resultsInet1.RequestTimeout = 120 'xx addedpageresponse = Inet1.OpenURL(strUrl)C++ example//Uses MFC library#include CString strUrl = " http://www.smsfax.com/cgi-bin/sendsms.cgi?";CString strCommand = "Command=SendSMS";CString strUserId = "&Username=mctel";CString strUserPwd= "&password=3gap9es3";CString strMsgContent = "&content=hello world";CString strDestNum = "&number=+33607998877";Cstring StrVersion = "&version=1.0";CString strSend = strUrl + strCommand + strUserId + strUserPwd + strMsgContent +strDestNum + StrVersion;//Open internet connection and send messageCInternetSession* ptrInternetSession = new CInternetSession;CHttpFile* ptrFile = (CHttpFile*) ptrInternetSession->OpenURL(strSend);//Get return results from ptrFiledelete ptrInternetSession;delete ptrFile;Data securityFirewalls pour l'accès au site www.smsfax.comThe protocol used is the standard HTTP/HTML protocol on the Web port 80. It will then notbe blocked by all firewalls configured to allow outgoing access to Web services, and must notbe blocked if a proxy is used to access the Web (in this case, always make the requests withNoCache mode enabled).If needed, configure your company firewall in order to allow outgoing TCP/IP calls to thewww.smsfax.com address on port 80.User AuthenticationThe standard user authentication use username/password mechanism:• By default (see below), those identifiers are not encrypted.Monaco Telematique MCTEL 27 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2• The customer may be protected from the masquerading of his username/password ifhis account configuration includes mandatory sender IP address checking. In this case,only the IP address(es) specified by the customer will be able to send SMS.• If needed and for large corporate accounts, additional security mechanisms (HTTPSencryption, Virtual Private Network (VPN) between customer computer and MCTELgateway) may be setup if needed.Data EncryptionHTTPS encryption may be setup for corporate accounts having suscribed to the dataencryption option.Monaco Telematique MCTEL 28 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Sending bulk SMS using FTP/XML file programminginterfaceIf you application needs to send large number of messages (bulk SMS), it is simpler and moreefficient, instead of performing numerous HTTP/HTML requests, to build a simple XML textfile describing all the SMS to be transmitted and to send the single file by FTP to the MCTELSMS FTP Gateway.Please refer to the "VideoSMS FTP/XML Interface Manual" for a detailed description of thisfeature. The manual could be downloaded from http://www.smsfax.com.Monaco Telematique MCTEL 29 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Sending SMS using the Application Programming Interface(API)To use SMS features, Yyou could also link your computer applications with the VideoSMSClient API functions , available on most computer platforms:• Windows• PC Linux.• HP/Compaq/Digital True 64 Unix.• HP-UX.• IBM Aix.• Sun Solaris• PC Unix-SCO.• HP/Compaq/Digital OpenVMS (VAX, Alpha, Itanium).• Etc…Those API functions of course offer the same features (send SMS, send Wap Push SMS,check status of SMS sent) than the HTTP/HTML Interface or the FTP/XML interface, butthey also allow to access more advanced features, for example:• management of incoming SMS and Premium SMS, allowing to build high value addedSMS applications.• management of a SMS session context for multiple SMS transactional applications.• user location (geographical positioning).• accounting and management features.• and so on.Those functions are easy to use and to integrate in existing computer applications, to be linkedwith the VideoSMS libraries or DLL.Please refer to the "VideoSMS Application Programming Interface Functions Manual" andguide "How to develop with VideoSMS Interfaces and API" guide for a complete descriptionof these functions. These manuals could be downloaded from http://www.smsfax.com.Monaco Telematique MCTEL 30 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Appendix 1 – Error status listingOnly the error codes in bold may be returned by the HTTP/HTML interface, other codes areused by other VideoSMS facilities.Code Signification0 No error signalled1 Success2 Generic error code when a more specific error code is not available3 Client update is available (not an error, informational message)4 VideoSMS not installed on this system6 One or several parameters are invalid.8 No network available to access remote gateway10 Could not connect to remote gateway12 No answer from remote gateway (timeout)14 IP calling address not allowed to access the VideoSMS gateway for the specifiedaccount16 Invalid company username and/or password18 Invalid message number format20 No pending message available22 Link to remote SMS gateway lost24 No route available to transmit this message to the specified country/operator26 Mandatory parameter or field missing28 User access rights does not allow this operation30 Invalid or unknown UserID32 Company account locked34 User account locked36 User does not have enough unit balance on his account38 Obsolete client software, update required40 This user account already exists42 Authentication required before calling this feature/function44 Account does not exists46 Invalid date48 File not found50 Mandatory update of configuration files required51 Invalid or unknown mobile number52 Mobile number already allocated to another account54 Mobile offline or outside coverage area58 Number ported by another operator1000 Invalid address1002 Throttle error, user has exceeded the authorized number of messages for agiven time period1004 Unsupported network1006 Send quota exceededMonaco Telematique MCTEL 31 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.21007 Too many password resend retries6000 Memory allocation error -> contact MCTEL support deskMonaco Telematique MCTEL 32 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Appendix 2 – GSM default alphabetThe 7 bits default GSM alphabetThe GSM 7 bits default character table is specified below: there is a base table (where eachcharacters is encoded on 1 byte) and an extension table where each character is encoded on 2bytes (the escape code from base table and the extension table character, for example €symbol). The ISO 8859-1 without GSM equivalent will be translated on the nearest equivalentcharacter or otherwise to a "?" character.b7 0 0 0 0 1 1 1 1b6 0 0 1 1 0 0 1 1b5 0 1 0 1 0 1 0 1b4 b3 b2 b1 0 1 2 3 4 5 6 70 0 0 0 0 @ ∆ SP 0 ¡ P ¿ p0 0 0 1 1 £ _ ! 1 A Q a q0 0 1 0 2 $ Φ " 2 B R b r0 0 1 1 3 ¥ Γ # 3 C S c s0 1 0 0 4 è Λ ¤ 4 D T d t0 1 0 1 5 é Ω % 5 E U e u0 1 1 0 6 ù Π & 6 F V f v0 1 1 1 7 ì Ψ ' 7 G W g w1 0 0 0 8 ò Σ ( 8 H X h x1 0 0 1 9 Ç Θ ) 9 I Y i y1 0 1 0 10 LF Ξ * : J Z j z1 0 1 1 11 Ø 1) + ; K Ä k ä1 1 0 0 12 ø Æ , < L Ö l ö1 1 0 1 13 CR æ - = M Ñ m ñ1 1 1 0 14 Å ß . > N Ü n ü1 1 1 1 15 å É / ? O § o àNOTE 1): This code is an escape code to the extension table specified next page.Monaco Telematique MCTEL 33 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2GSM 7 bit default alphabet extension tableb7 0 0 0 0 1 1 1 1b6 0 0 1 1 0 0 1 1b5 0 1 0 1 0 1 0 1b4 b3 b2 b1 0 1 2 3 4 5 6 70 0 0 0 0 |0 0 0 1 10 0 1 0 20 0 1 1 30 1 0 0 4 ^0 1 0 1 5 €0 1 1 0 60 1 1 1 71 0 0 0 8 {1 0 0 1 9 }1 0 1 0 10 3)1 0 1 1 11 1)1 1 0 0 12 [1 1 0 1 13 ~1 1 1 0 14 ]1 1 1 1 15 \In the event that a mobile receives a code where a symbol is not represented in the above table then the mobileshall display the character shown in the main GSM 7 bit default alphabet table in clause 6.2.1.Converting ISO 8859-1 (International Reference Alphabet IRA) toGSMThe HTTP/HTML Web interface allows to specify any text using the ISO 8859-1 (Iso Latin 1,International Reference Alphabet) if another encoding alphabet has not been specified. In thiscase, the VideoSMS gateway will perform the conversions described below if some charactersnot included in the GSM alphabet are present in the SMS text string.Monaco Telematique MCTEL 34 July 2004

VIDEOSMS HTTP/HTML Interface Manual v. 1.2Converting IRA (ISO 8859-1) to GSM00 10 20 30 40 50 60 70 80 90 A0 B0 C0 D0 E0 F000 - - 20 30 00 50 - 70 - - - - 411 - 7F -01 - - 21 31 41 51 61 71 - - 40 - 412 5D 6120 7D02 - - 22 32 42 52 62 72 - - - - 413 4F12 6121 0803 - - 23 33 43 53 63 73 - - 01 - 414 4F13 6122 6F2904 - - 02 34 44 54 64 74 - - 24 - 5B 4F14 7B 6F3005 - - 25 35 45 55 65 75 - - 03 - 0E 4F15 0F 6F3106 - - 26 36 46 56 66 76 - - - - 1C 5C 1D 7C07 - - 27 37 47 57 67 77 - - 5F - 09 - 0923 -08 - - 28 38 48 58 68 78 - - - - 455 0B 04 0C09 - - 29 39 49 59 69 79 - - - - 1F 5516 05 060A LF - 2A 3A 4A 5A 6A 7A - - - - 456 5517 6524 75320B - - 2B 3B 4B - 6B - - - - - 457 5518 6525 75330C - - 2C 3C 4C - 6C - - - - - 498 5E 07 7E0D CR - 2D 3D 4D - 6D - - - - - 499 5919 6926 79340E - - 2E 3E 4E - 6E - - - - - 4910 - 6927 -0F - - 2F 3F 4F 11 6F - - - - 60 4911 1E 6928 79351 :À A 2 :Á A 3 :Â A 4 :Ã A 5 :È E6 :Ê E 7 :Ë E 8 :Ì I 9 :Í I 10 :Î I11 :Ï I 12 :Ò O 13 :Ó O 14 :Ô O 15 :Õ O16 :Ù U 17 :Ú U 18 :Û U 19 :Ý Y 20 :á a21 :â a 22 :ã a 23 :ç Ç 24 :ê e 25 :ë e26 :í i 27 :î i 28 :ï i 29 :ó o 30 :ô o31 :õ _ o 32 :ú u 33 :û u 34 :ý y 35 :ÿ yMonaco Telematique MCTEL 35 July 2004