Beruflich Dokumente
Kultur Dokumente
HTTPInterfaceUserGuide
Version Date 1.3 11/2009
TableofContents
1 Forewords 1.1 GettingStarted 1.2 NetsizeTechnicalSupport 2 Introduction 2.1 Architecture 2.2 SupportedOperations 3 SendingMTSMS 3.1 Process 3.2 AccountParameters 3.3 mGatewayURLs 3.4 MandatoryParameters 3.5 OptionalParameters 3.6 TheNetsizeTestPage 3.7 VariousMTMessagesSamples 3.8 HTTPResponse 4 ReceivingMOSMS&StatusReports 4.1 Process 4.2 MOSMSParameters 4.3 StatusReportsParameters 4.4 HTTPRequestsSamples 5 SendingWAPPushServiceIndication 5.1 ConnectionParameters 5.2 mGatewayURLs 5.3 TheNetsizeTestForm 5.4 SamplesofHTTPRequest 5.5 ReturnResultPage 3 3 3 4 4 4 5 5 5 5 7 8 12 13 15 17 17 19 24 25 28 28 28 31 32 33
2009Netsize
Forewords
2/35
1 Forewords
Note:ThisdocumentwaspreviouslynamedNMOFastHTTPInterfaceUserGuide. TheHTTPinterfaceisintendedforthedeveloperswhowanttoconnecttomGatewayfor:
MobileTerminated(MT)bulk/PremiumSMSservices MobileOriginated(MO)bulk/PremiumSMSservices.
1.1 GettingStarted
YouwillneedthefollowingfromNetsizetousetheHTTPinterface:
Validlogin/password Endpointname.
IfyourHTTPserverfiltersIPaddresses,youmustcontactyourNetsizetechnicalmanager.Hewillprovide youwiththelistoftheNetsizeIPranges.
1.2 NetsizeTechnicalSupport
Ifyourunintoanyissues,youmayconnecttoNetsizeWebcarehttps://webcare.netsize.comusingyour loginandpassword. Process
1. 2. Youenteryourtechnicalrequest(case)onNetsizeWebcare YourrequestistransmittedtoNetsizesupportteams.Processingtimewilldependon: yourSLA thetypeofrequest thetypeofservice.
2009Netsize
Forewords
3/35
2 Introduction
TheNetsizeHTTPInterfaceletsyoudevelopapplicationstosendandreceiveSMSmessagesviaHTTP. Note:TheNetsizeHTTPinterfacedoesnotenabletosendorreceiveMMSmessages. InordertosendorreceiveMMSmessages,youmustuseNetsizeAPIforMMSorMM7Interface.
2.1 Architecture
TheNetsizeHTTPserverisfullyintegratedintothemGatewaybroker.Ifyouwanttoconnecttothisserver, youneedtouseanHTTPclientapplication.NetsizedevelopsHTTPserversforeachNetsizegateway worldwide.
2.2 SupportedOperations
MTSMS
YoucansendMTSMSin:
GET(allparametersarestoredintheURL)or POST(allparametersarestoredinthebodyoftheHTTPrequest,inplaintextorXMLformat).
Bydefault,Netsizereturnsaresponseinplaintext. YoucanalsoasktoreceiveresponsesinXMLwithshorttagsorXMLwithlongtags.SeeOutputparameter.
MOSMS/SR
YoucanreceiveMOSMSandStatusReportsinGETorPOST.
2009Netsize
Introduction
4/35
3 SendingMTSMS
3.1 Process
InordertosendanMTSMS,youmust:
1. 2. 3.
InordertobuildanHTTPrequesttosendanMTSMS,firstyouneedtosetyourconnectionparameters. Thisincludes:
youraccountparameters theURLoftheNetsizegatewayfromwhichyousendtheMTSMS.
3.2 AccountParameters
NetsizeprovidesyouwithmGatewayaccountstoperformSMStraffic.ForeachmGatewayaccount,Netsize providesyouwiththeparameters:
sEndpointName sLogin sPassword.
3.3 mGatewayURLs
mGatewayaccountsenableyoutosendMTSMSfromaNetsizeURL.NetsizeURLshavethefollowing format: http://xxx.netsizeonline.com:yyyy/Request.aspx xxxxcorrespondingtotheNetsizegatewayprefixandyyyytoconnectionport,usually8080 YouwilluseoneofthefollowingURLs;dependingon:
thetypeoftrafficyouperform(standardSMS/PremiumSMS/MassivePush/WordwidePush) thedestinationcountryofyourMTSMS.
3.3.1.1 Bulk(Standard)SMSTraffic
Country Austria France Belgium Germany Italy Netherlands Spain Sweden Switzerland UK mGatewayURL http://at.netsizeonline.com:8080/Request.aspx http://Fr.netsizeonline.com:8080/Request.aspx http://be.netsizeonline.com:8080/Request.aspx http://de.netsizeonline.com:8080/Request.aspx http://IT.netsizeonline.com:8080/Request.aspx http://NL.netsizeonline.com:8080/Request.aspx http://es.netsizeonline.com:8090/Request.aspx http://se.netsizeonline.com:8080/Request.aspx http://ch.netsizeonline.com:8080/Request.aspx http://uk.netsizeonline.com:8080/Request.aspx
2009Netsize
SendingMTSMS
5/35
3.3.1.2 PremiumSMSTraffic
Country Australia Belgium Denmark Finland France Greece Hungary Morocco Netherlands Norway Portugal Russia SouthAfrica Spain Sweden Switzerland Turkey UnitedKingdom UnitedStates mGatewayURL http://AUP.netsizeonline.com:8080/Request.aspx http://BEP.netsizeonline.com:8080/Request.aspx http://DKP.netsizeonline.com:8080/Request.aspx http://fip.netsizeonline.com:8080/Request.aspx/ http://FIP.netsizeonline.com:8080/Request.aspx http://FRP.netsizeonline.com:8080/Request.aspx http://grp.netsizeonline.com:8080/Request.aspx http://hup.netsizeonline.com:8080/Request.aspx http://map.netsizeonline.com:8080/Request.aspx http://NLP.netsizeonline.com:8080/Request.aspx http://nop.netsizeonline.com:8080/Request.aspx http://ptp.netsizeonline.com:8080/Request.aspx http://rup.netsizeonline.com:8080/Request.aspx http://zap.netsizeonline.com:8080/Request.aspx http://ESP.netsizeonline.com:8080/Request.aspx http://sep.netsizeonline.com:8080/Request.aspx http://chp.netsizeonline.com:8080/Request.aspx http://trp.netsizeonline.com:8080/Request.aspx http://ukrc.netsizeonline.com:8080/Request.aspx http://usp.netsizeonline.com:8080/Request.aspx
3.3.1.3 WorldwidePush
http://WWP.netsizeonline.com:8080/Request.aspx
3.3.1.4 MassivePush
http://hvb.netsizeonline.com:8080/Request.aspx
2009Netsize
SendingMTSMS
6/35
3.4 MandatoryParameters
Thetablebelowcontainsthemandatoryparameterforsubmittingamessage. Parameter
sEndpointName sLogin sPassword sExtensionName
Description
Accountparameter Accountparameter Accountparameter Nameoftheextension
Valueand/orFormat
ProvisionedbyNetsize ProvisionedbyNetsize ProvisionedbyNetsize Mustalwaysbe:AGSMSExt^Netsize ThisfieldmustbeURLencoded
sMessage
Themessagethatwillbesenttothe mobilephone.
Themaximumlengthpermittedis:
2009Netsize
SendingMTSMS
7/35
3.5 OptionalParameters
Thefollowingliststheoptionalparametersforsubmittingamessage.Optionalparametersmaybeproduct oroperatorspecific.
GeneralParameters
Parameter nClassType Description TheSMSmessageClass. SeetheGlossarysectionforfurtherdetails ontheGSMSMSClasses. Valueand/orformat Valu e 0 1 2 3 dDelayDate nNotification DelaysdeliveryoftheSMStothemobile phone ThenotificationlevelrequestedfortheMT message.Notificationisanoperator dependentfeature. Description FlashSMS SMSstoredonmobileequipment. Netsizedefaultvalue SMSstoredontheSIM SMSstoredonterminalequipment Date time Long Data Type Long
Formatis:YYYY/MM/DDhh:mm:ss (forexample,2000/01/31%2012:30:00) Val ue 0 1 2 3 4 5 6 7 Typesofnotificationsreturned Netsizedefaultvalue.Nooperator notificationreturned Onlybufferedmessagenotification Onlydeliverynotification Onlynondeliverynotification Bufferedmessage+deliverynotification Bufferedmessage+nondelivery notification Delivery+nondeliverynotification Allnotifications
sOADC
Definesthesenderaddress.OadCisan Maximumlengthis15charactersanddepends operatordependentfeature.Pleasecontact onoperator yourNetsizeaccountmanagerformore informationonthesupportedOAdC (numericoralphanumeric)oneach operator. Definestheprioritylevelofthemessage 0:Normal.Netsizedefaultvalue 1:High 2:Urgent
Strin g
nPriority
Long
sSmsExtId
dValidityDate
2009Netsize
SendingMTSMS
8/35
deliveredcorrectly.Validitydateisan operatordependentfeature. Output FormatoftheHTTPresponse Netsizedefaultvalueisplaintextifthis parameterisnotprovided.Youcansetthe followingvalues: XML:XMLwithshorttags XMLLongTags:XMLwithlongtags Strin g
AccountSelection/MasterAccountsParameters
Masteraccountsenabletoswitchamongseveralaccountswithoutloggingoffandloggingin. TheSMStrafficisdispatchedbasedupononeorseveralparameters,eachDispatchvaluebeinglinkedtoan mGatewayaccount.ThefollowingparameterscanbeprovisionedbyNetsizefortheCustomerswhowish tosetupamasteraccountconfiguration. Note:CustomersmayasktheirNetsizetechnicalcontacttosetupamasteraccountconfiguration.
Parameter Description Canbeusedifyouwanttolaunchseveralenduser pricesonthesamePremiumSMSshortcode. YouaskNetsizetoconfigureoneDispatchPricevalue perenduserprice. ExampleofconfigurationforaPremiumSMSshort codeinGermanythatproposethreeenduserprices. 3.50:accountwithenduserpriceat3.50Euro 1.50:accountwithenduserpriceat1.50Euro 1.20:accountwithenduserpriceat1.20Euro Warning:InFrance,thevalue1.00isusedtosend PremiumSMSmessageswhateverthepriceoftheshort code.PleaserefertothePremiumMO/MTMessaging UserGuideforFranceforalldetails. Canbeusedtodispatchthetrafficbasingontheshort codevalue,forinstance,ifyouusethesamemaster accountsforseveralshortcodes. Canbeusedtodispatchthetrafficbasingonthe operator. Exampleofconfiguration: 208001:OrangeFrance 208010:SFR 208020:BouyguesTelecom Canbeusedtodispatchthetrafficbasingany parameterchosenbytheCustomer. Exampleofconfiguration: 0:Accountwithprioritynormal 1:AccountwithpriorityHigh 2:AccountwithpriorityUrgent Valueand/or format DataType
sDispatchPrice
String
sDispatchShortCode
Provisionedby Netsize
String
nDispatchOperator
Provisionedby Netsize
Long
sDispatchApplication
Provisionedby Netsize
String
2009Netsize
SendingMTSMS
9/35
Specificparameter(onlyforstandardtrafficinFrance)
Parameter nAppType Description DefinethetypeofapplicationrelatingtotheMT message. OnlyforstandardtrafficinFrance. Valueand/orformat 0:ClosedUserGroup 1:Contentdelivery 2:Directmarketing, NetsizeDefaultValue. 3:Chat DataType Long
BinaryParameters
Thetablebelowcontainstheadditionalparameterstosendabinarymessage.
Parameter Description Identifiestheuseofahexadecimalstringtorepresentthe message. bHexString Warning:Thisparametermustnotbeusedformultipart SMS. Identifiesthetypeofthebinarymessage nBinary bUnicode bTPUDHI sTPPID MustbeusedtosendaUnicodemessage IdentifiestheuseofaUDH(UserDataHeader)ornot ConfigureTPPIDvalueinSMS. MustbeusedformultipartSMSonly.Includesthe messagethatwillbesenttothemobilephone. Warning:Ifused,thisparameterreplacesthesMessage parameter. 1:Wappush 2:Unicode 3:Multiparttext Mustbesetto1 Mustbesetto1 Example:0127 Long Value Mustbesetto1 DataType Boolean
oMessage
Note:ExamplesofbinaryMTrequestsareprovidedintheVariousMTMessagesSamplessection.
2009Netsize
SendingMTSMS
10/35
PremiumSMSParameters
ThetablebelowcontainsoptionalparametersforsubmittingamessagerelatingtoaPremiumSMSservice. Optionalparametersmaybeproductoroperatorspecific. Note:YoumayrefertothePremiumMessagingUserGuidestogettheparametersthatneedtobe implementedineachcountry.
Parameter sRealAlias Description Thealiasoftheserviceasprovisionedby Netsize Channelthroughwhichtheenduserordered theservice Whensupportedbytheoperator,this parameterisusedasaBillingID.Youreceiveit inincomingMOSMS.Uponreceivingsuch information,youmustpostitbackintothe RequestIDfieldoftheMTreply. Providesinformationonthestatusofanend usersubscription Value ProvisionedbyNetsize 0:SMS 1:WAP 2:Web Data Type String
nMediaType
Long
sRequestId
ProvidedviaMOSMSbytheoperator String
nSubscriptionActi on
0:Subscribesendusertoservice 1:Suspendsenduser subscription 2:Renewsendusersubscription 3:Unsubscribeenduserfrom service Long 4:Unsubscribeenduserfromall servicesonshortcode 5:Followup:Marksservice deliveryforanactive subscription Long
nRequestPIN
ForVodafoneGermany,thisparameter enablescustomerstohaveVodafonegenerate andsendaPINcodetotheenduser ForVodafoneGermany,thisparameter triggersabillingvalidationrequest ForTIMItaly,allinoneparameterthat includesinformationregardingthechannel, service,content,priceandcontentprovider. TypeofcontentincludedintheMTmessage ForSFRFrance,IDnumberassignedbythe operatorforanendusersubscription
Long
3.5.1.1 DeprecatedParameters
Thefollowingparametersaredeprecated.YoumayusetheSubscriptionActionparametersinstead.
Parameter bFollowUp bSubscribe bUnsubscribe Description SpecifiesthattheMTmessagecorrespondstoa servicedelivery SpecifiesthattheMTmessagecorrespondstoa subscriptionrequest SpecifiesthattheMTmessagecorrespondsto anunsubscriptionrequest Value Valuemustbesetto1 Valuemustbesetto1 Valuemustbesetto1 Data Type Long Long Long
2009Netsize
SendingMTSMS
11/35
3.6 TheNetsizeTestPage
NetsizetestpagesenabletosendHTTPrequestswithouthavingtobuildthewholeHTTPrequest. URLsformatis:http:www.XX.netsizeonline.com/ServerAccess/ Example:http://msuk.netsize.com/NS_SMS/SendForm.aspx
2009Netsize
SendingMTSMS
12/35
3.7 VariousMTMessagesSamples
ThefollowingsamplescanbeusedinHTTPGETorHTTPPOST.Allvaluesintheseexamplesshouldbe replacedbyyourownvalues.
HTTPGETRequestsEncoding
IfyouuseHTTPGET,allparametersmustbeURLencoded,forexample+33mustbeencodedas%2B33. Character Encodedvalue + %2B # %23 ^ %5E / %2F : %3A
TextSMS
sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &sMessage=Message &nClassType=1 &nNotification=7 &sOADC=OADC &sSmsExtId=ExtId
Text:multipart(longSMS)
Part 1: sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &oMessage=0500031202017468697320697320612076657279206C6F6E67206D657373616765207 468617420 77696C6C20626520656E636F64656420696E746F20322070617274732E2045616368207061727420 77696C6C2 062652073656E742073657061726174656C7920616E64207468652068616E647365742077696C6C 2070617374 207468652074776F20706172747320746F2073686F77206F6E6C79206F6E65 &nClassType=1 &nBinary=3 &bTPUDHI=1 oMessage = [UDH Length = 05][UDH-Information Element [Identifier = 00][Length = 03][Data [ReferenceNumber = 12][NumberOfParts = 02][PartNumberInSequence=01]]][text=this is a very long message that will be encoded into 2 parts. Each part will be sent separately and the handset will past the two parts to show only one] using Windows 1252 Encoding
2009Netsize
SendingMTSMS
13/35
Part 2: sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &oMessage=050003120202206D657373616765 &nClassType=1 &nBinary=3 &bTPUDHI=1 oMessage = [UDHLength = 05][UDH-Information Element [Identifier = 00][Length = 03][Data [ReferenceNumber = 12][NumberOfParts = 02][PartNumberInSequence=02]]][text= message] using Windows 1252 Encoding
WAPPushSMS
sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &sMessage=0605040B8423F08B060403AE81EA02056A0045C60B03687474703A2F2F7777772E6E 657473697A652E636F6D2F001103313233406E657473697A652E636F6D00080AC30720031113154 41110C30420131113010354657374204F54412066726F6D204E657473697A65000101 &nNotification=7 &sOADC=OADC &sSmsExtId=ExtId &nClassType=1 &bHexString=1 &bTPUDHI=1 &nBinary=1
UnicodeSMS
sExtensionName=AGSMSExt^Netsize &sEndpointName=EndpointName &sLogin=Login &sPassword=Password &sTarget=+336XXXXXXXX &sMessage=0445043E0440043E0448043E0301 &nNotification=7 &nClassType=1 &bHexString=1 &bUnicode=1
2009Netsize
SendingMTSMS
14/35
3.8 HTTPResponse
AfterreceivingandinterpretingyourHTTPrequest,NetsizesendsanHTTPresponsemessage. HTTPresponsesinclude: astatusline(returncode+genericmessage) asmanyadditionallinesastargetsincludedintheHTTPrequestmessage(returncode+ticketID+ specificinformationmessageforeachtarget). Explanation MTSMShasbeensuccessfullysenttotheoperatorSMSCandforalltargets.Youcan ignoretherestoftheresponse. MTSMSsendingfailed.InadditiontotheHTTPcodes,youmayreceive: Differentfrom0 theerrorreturncode47ifatleastonemandatoryMTSMSparameterismissing orisinvalid,or, anmGatewayerrorreturncode.ViewthemGatewayErrorCodesdocument.
Returncodevalue 0
PlainText
Bydefault,youreceiveHTTPresponseinplaintext.Formatis: code;message\r\n code;ticket;message\r\ncode;ticket;message\r\n
XMLshorttags
HereisanexampleofXMLshorttagsformattedresponseforamultiplesending(1MTSMSfor2MSISDNs).
<?xml version="1.0" encoding="UTF-8"?> <NMGSMSMTR> <R> <RC>0</RC> <RM>Success</RM> </R> <TL> <T> <C>0</C> <M/> <A>+33600000001</A> <I>987654321</I> </T>
2009Netsize
SendingMTSMS
15/35
XMLLongTags
HereisanexampleofXMLlongtagsformattedresponseforamultiplesending(1MTSMSfor2MSISDNs).
<?xml version="1.0" encoding="UTF-8"?> <NMGSMSMTResponse> <Result> <Code>0</Code> <Message>Success</Message> </Result> <TicketList> <Ticket> <StatusResultCode>0</StatusResultCode> <StatusResultMessage/> <Address>+33600000001</Address> <IdTicket>987654321</IdTicket> </Ticket>
2009Netsize
SendingMTSMS
16/35
4 ReceivingMOSMS&StatusReports
4.1 Process
TheNetsizeHTTPinterfaceenablestodirectlyreceiveMOSMSorSRsonapageofyourWebserver; withouthavingtoconnecttotheNetsizegatewaytoretrieveasynchronousMOSMS/SRs. Indeed,itisNetsizethatcontactsyoutopushMOSMS/SRs. YoucanretrieveMOSMS/SRsonanytypeofWebserverviaascriptpagesuchasASP,CGIorPHP.
StepstoProcessanMOSMSoraStatusReport
1. 2. 3. 4.
4.1.1.1 StoringMOSMS/SRIDs
YoumuststorethissetofvaluesforeachMOSMS/SRthatyoureceive:
MOSMS/SRID,(parameterlabelledP1bydefault) GW PORT forSRonly:Event(SRparameterlabelledP3bydefault).
Thissetofvaluesenablestodetermineuniquemessages(primarykeyfordatabase).
4.1.1.2 AcknowledgingMOSMS/SRs
ForeachMOSMS/SRthatyoureceive,youmust:
returnanHTTPresponse200OK(redirectioncodesoftype3xxareforbidden) sendbackfromyourWebserveranHTMLpageincludinginplaintextstatus=0.
ReceivingMOSMS&StatusReports
17/35
4.1.1.3 NetsizeRetryMechanism
NetsizeimplementsaretrymechanismifyoudonotacknowledgecorrectlyanMOSMS/SR. Consequently,youmuststoreallSMSMO/SRIDstoknowifanSMSMO/SRhasalreadybeenreceivedand avoidprocessingagainanMOSMS/SR. Note:NetsizewilltrytosendtheMO/SRmessageatadecreasinglapse. HerearesomeofthecaseswhereNetsizeHTTPserverwillimplementaretrymechanism: wrongcode disconnection noresponse timeoutexpired yousentbackanotherHTTPcodethan2xx(1xxor3xxor4xxor5xx) theHTTPconnectionwastooslowandNetsizedisconnectedbeforegettingyour acknowledgement youdidnotsendanyHTTPresponse yousenttheHTTPresponseaftertheHTTPservertimeouthadexpired.Netsize defaultHTTPtimeoutissetto20secondstogetanHTTPresult(HTTPcodeand acknowledgment)
2009Netsize
ReceivingMOSMS&StatusReports
18/35
4.2 MOSMSParameters
IntheNetsizeHTTPinterface,MOSMSparametersareidentifiedbylabelsthatyoucancustomize.
MandatoryParameters
ThefollowingparametersarealwaysfoundinMOSMS.
Parameter Alias Aliasprocessed Binary Messagedate Deliverydate Destination address Encryptiontype Firstword GatewayID MessageID Integrationdate Keywordfound Keywordgeneric Label Description P5 P4 P24 P11 P13 P33 P34 P15 P35 P1 P36 P37 P38 AliasfoundintheMOmessage mGatewayaliasorlargeaccount Messageencodingmethod DatewhentheMOSMSwasinsertedintothemGatewaydatabase DeliverydateindicatedbytheSMSC ShortcodefromwhichtheMOSMSisreceived FortheCustomerwhorequestedencryptionofMOcontent,determines whetherthecontentoftheMOisencrypted FirstwordoftheMOmessage IdentifierstheMOreceivinggateway MOmessageticketID DetermineswhetherakeywordwasfoundintheMOSMS. Value:0:Yes;1:no DetermineswhetheragenerickeywordwasfoundintheMOmessage.By generic,wemeanauniversalkeywordrecognizedbyNetsizeforall countries&operators(e.g.CONTACT,HELP,INFO,INDEX,RULE, RENEW,START,STATUS;STOP,TEST,VIEW) Determineswhetheralocalkeywordwasfound KeywordfoundintheMOSMS(e.g.STOP,START,INFO) CustomeraccountcorrespondingtothealiasdeterminedforMOSMS TheShortcodefromwhichthemessagehasbeenreceived AccountlogincorrespondingtothealiasdeterminedforMOSMS MOSMStextwithoutaliasandseparator MOSMStextwithaliasandseparatorNetsizeaddsthealiasiftheenduser didnottypeit. NOTE: IftheenduserisinanMOsession*anddidnottypethealias, parametervalue=<alias><space><P20> Iftheendusertypedthealias<P2>=<P20> TextoftheMOmessage,astypedbytheenduserandreceivedfromthe operator.Parametervalue=<alias><separator><text>or<text>ifthe enduserisinanMOsessionanddidnottypethealias Data Type String String Long Datetime Datetime String Long String Long Long Datetime Boolean Boolean
Messagetyped
P20
String
2009Netsize
ReceivingMOSMS&StatusReports
19/35
MandatoryParameters(continued)
Parameter Message (Unicode hexastring) Message received (Unicode hexastring) Messagetyped (Unicode hexastring) MoContext Label Description P43 ThisparameteristransmittedforMOSMSformattedinUnicode.Itincludes thetextoftheMOmessagewithoutaliasandseparator,encodedin hexastring ThisparameteristransmittedforMOSMSformattedinUnicode.Itincludes thewholeMOtextmessage,asreceivedfromtheoperator,encodedin hexastring ThisparameteristransmittedforMOSMSformattedinUnicode.Itincludes thetextoftheMO,astypedbytheenduserencodedinhexastring. ContextoftheMOSMS.ThisparameterisrelatedtotheMOSession technicaloption.ItenablestorouteMOSMSwithoutalias. Value 0 3 4 10 12 13 14 15 20 22
P44
String
P45
String
P23
Long
Description Regularalias Targetrouting Generickeyword Explicitsession ExplicitsessiontimeoutwithFailedMOaccount Explicitsessionstopcommand Explicitsessionbeginning Explicitsessionbeginningwithstopcommand Implicitsession ImplicitsessiontimeoutwithFailedMOaccount Long Long String Long Long Datetime String String String Long String Long
OperatorMCC OperatorMNC Origin OriginatedMCC OriginatedMNC Receivaldate Second separator Secondword Separator SMSID Gateway Port
MobileCountryCodeoftheoperatorwhosenttheMOtoNetsize MobileNetworkCodeoftheoperatorwhosenttheMOtoNetsize MSISDNofthesender OperatorMobileCountryCode.MaydifferfromparameterP9incaseof roaming OperatorMobileNetworkCode.MaydifferfromparameterP10incaseof roaming DatewhentheNetsizegatewayreceivedtheMOmessagefromtheoperator SecondseparatoroftheMOmessage SecondwordoftheMOmessage SeparatorfoundintheMOmessage MOticketidentifier(uniqueonagateway) DNSnameoftheSMSgateway
PORT PortvaluetoaccesstheSMSgateway
2009Netsize
ReceivingMOSMS&StatusReports
20/35
4.2.1.1 MOSession
MOsessionisatechnicaloption,whichistargetedatNetsizeCustomerswhohavelaunchedtheirservices onasharedshortcode.Thankstothisoption,endusersdonothavetoentertheservicealiaseachtime theysendanMOtothesharedshortcode.Netsizestorestheservicealiasinformationandautomatically addsittotheendusersMOmessageduringthePremiumsession. CustomerswillhavethepossibilitytoactivateImplicitorExplicitMOsessions,dependingonthetypeof servicestheywanttolaunch. InbothcasestheenduserwillnothavetoentertheservicealiastosendanMOtotheshortcode. TheservicealiasisassignedtotheendusersMSISDNwhenhesendshisfirstMOmessage. MOSession Type Target routing Description Note:Targetroutingispossibleonstandarddedicatedshortcodesonly. Implicit Explicit Duringthistypeofsession,iftheendusersendsanMOwithanotheralias,for instancetoorderanotherservice,Netsizeswitcheshisaliasaccordingly. Thesesessionsareactivatedforamaximumperiodof24hours.Thistypeofsession canbeusedforChatservices. Duringthistypeofsession,iftheendusersendsanMOwithanotheralias,Netsize willignorethisnewaliasandwillautomaticallyassociatetheexplicitservicealiasto hisMOmessage. Thesesessionsremainactivateduntiltheendusersendsakeyword,forinstance, STOP,toleavethesession;oruntilthetimeoutNetsizehasdefinedbydefaulthas expired. TheCustomerdeclaresalistofMSISDNsthatwillbeassociatedtohisalias. EachtimeanMOSMSissentfromoneoftheseMSISDNs,Netsizeautomatically routestheMOSMStotheCustomersURL.
Thistypeofsessioncanbeusedforsubscriptionbasedservices. Note:PleaseaskyourNetsizetechnicalcontacttoactivatethisoption.
2009Netsize
ReceivingMOSMS&StatusReports
21/35
OptionalParameters
Parameter Billingplan Concatenate dmessage index Concatenate dmessage length Concatenate dmessage reference ContractID FakeMO Label P26 P49 Description ForPremiumSMSinAustralia,identifieswhetherthe MSISDNisprepaidorpostpaid PositionoftheMOSMSinamultipartMOSMS Value 1=prepaid 2=postpaid Data Type Long Long
P50
NumberofpartsofthemultipartMOSMS
Long
P51
MOSMSmultipartidentifierpositionedbythesending device ForPremiumMTSMSwithSFR(France),identifiesan endusersubscription IdentifiesiftheMOisafakeMO,i.e.,hasnotbeensent byanenduserbutgeneratedbyNetsize ForPremiumSMSwithBouyguesTelecom(France), specifieswhethertheenduserisregisteredtothe IModeoption ForPremiumSMSwithBouyguesTelecom(France), specifiesifthemobilephoneisMMScompatible ForPremiumSMSwithSFR(France),specifiesthelevelof parentalcontrolactivatedonanMSISDN
Long
P31 P52
Providedbyoperator Valuemustbesetto TRUE 0:no 1:yes 0:no 1:yes 0:reinforced 1:regular 2:notactivated 999:dataNOT available
Imodestatus P21
P28 P29
Long Long
RequestID SAC
P14 P27
BillingIDassignedbytheoperatortotheMOSMS ForPremiumSMSwithBouyguesTelecom(France), providesthe2lastdigitsofthemobilephoneType AllocationCode.Itmustbeconcatenatedwiththe parameterTACtogetthecomplete8digitsoftheType AllocationCode. ForPremiumMTSMSwithMobilcom(Germany), specifieswhethertheenduserisauthorizedtoreceive PremiumMTSMSmessages MOrequesttype
Strin g Strin g
P32
Long
P25
Long
TACcode
P22
ForPremiumSMSinFrance,providesdifferent informationdependingonoperators: Operat or Bouygu es Teleco m Description The6firstdigitsofthemobile phoneTypeAllocationCode.It mustbeconcatenatedwiththe parameterSACtogetthe complete8digitsoftheType AllocationCode. A4digitTACIDthatmustbe mappedwithOrangeFranceTAC Length 6digits
Strin g
Orange France
4digits
2009Netsize
ReceivingMOSMS&StatusReports
22/35
codetabletogettherealType AllocationCode.Pleaseaskyour Netsizetechnicalcontacttoget OrangeFranceTACcodetable. SFR ThemobilephoneTypeAllocation 8digits Code Note:TheTypeAllocationCodecorrespondstothe8first digitsoftheIMEInumber.IMEIstandsforInternational MobileEquipmentIdentity.Itisauniquenumberthat identifieseveryGSMmobilephone.
2009Netsize
ReceivingMOSMS&StatusReports
23/35
4.3 StatusReportsParameters
SRparametersareidentifiedbylabels,whichcanbecustomized.ThetablebelowliststheSRparameters.
Parameter Label TicketID ExtID Event P1 P2 P3 Description TheuniqueNetsizeIDfortheMTmessage MTSMSClientID ThestatusoftheMTmessage Code 2 Label RetryFailed Description TheMTSMScouldnotbesenttotheoperatorSMS Cseveraltimes.MgatewaygaveupsendingtheMT SMS.TheMTSMShasbeenroutedtothe undeliveredMTSMSadministrationqueue. TheMTSMShasbeensenttotheoperatorSMSC. Theevent3is: 4 5 6 finalifnooperatornotificationwasrequested Intermediateifafinalnotificationwas requested. Intermediate Final Final Type Final
Senttothe SMSC
Final/ intermediate
P4 P5
P6 GW PORT
2009Netsize
ReceivingMOSMS&StatusReports
24/35
4.4 HTTPRequestsSamples
YoudefinemethodthatshallbeusedbyNetsizetopushMOSMS/SRs:GETorPOST.
GET
Inthismethod,youreceiveanURLincluding: HereisanexampleofURLtransmittedbyNetsizeforanMOSMSintheHTTPGETmethod. http://www.myWebSite.com/Netsize/MO.asp?P1=123456789&P7=%2B33612345678&P3=Hello&GW=fr .netsizeonline.com...... where www.myWebSite.com Netsize/MO.asp MO.asp %2B33612345678 Hello fr.netsizeonline.com ...... Youshouldreceivethemessage"Hello",identifiedbytheID123456789,fromthephonenumber 33612345678,sentthroughtheNetsizeFrenchgateway. is yourWebsite thepathtoaccessthescriptpagewhereMOsand/orSRsareprocessed thescriptpage thesenderphonenumber thetextoftheshortmessage thegatewaywhichhasperformedtheMOPush theotherparametersrelatedtotheMOPush. yourWebsiteaddress, thepathtoaccessthescriptpagewhereMOSMSand/orSRsareprocessed yourscriptpagename; theparametersrelatedtoMOSMSorSRs.
2009Netsize
ReceivingMOSMS&StatusReports
25/35
POSTwithParametersinHTTPBodyinXMLformat
Inthismethod,youdefineyourowntemplateandDTD,whichwillbeusedbyNetsizetotransmitMO SMS/SRs.
4.4.1.1 MOSMS
HereisanexampleoftemplateandDTDthatcanbeusedtotransmitMOSMS. Template <?xmlversion="1.0"encoding="iso88591"?> <MO> <P1>SMSMessageId</P1> <P2>SMSMessageReceived</P2> <P3>SMSMessage</P3> <P4>SMSAliasProcessed</P4> <P5>SMSAlias</P5> <P6>SMSSeparator</P6> <P7>SMSOrigin</P7> <P8>SMSLargeAccountNumber</P8> <P9>SMSOperatorMCC</P9> <P10>SMSOperatorMNC</P10> <P11>SMSDate</P11> <P12>SMSRecvDate</P12> <P13>SMSDelivDate</P13> <P14>SMSRequestId</P14> <P15>SMSFirstWord</P15> <P16>SMSSecondWord</P16> <P17>SMSSeparator2</P17> <P18>SMSOriginatedMCC</P18> <P19>SMSOriginatedMNC</P19> <P20>SMSMessageTyped</P20> <P21>SMSImodeStatus</P21> <P22>SMSTac</P22> <P23>SMSMOContext</P23> <P24>SMSBinary</P24> <P25>SMSSubscriptionAction</P25> <GW>GatewayAddress</GW> <PORT>GatewayPort</PORT> </MO> DTD <!DOCTYPEMO[ <!ELEMENTMO (P1,P2,P3,P4,P5,P6,P7,P8,P9,P10,P11,P12, P13,P14,P15,P16,P17,P18,P19,P20,GW,PORT)> <!ELEMENTP1(#PCDATA)> <!ELEMENTP2(#PCDATA)> <!ELEMENTP3(#PCDATA)> <!ELEMENTP4(#PCDATA)> <!ELEMENTP5(#PCDATA)> <!ELEMENTP6(#PCDATA)> <!ELEMENTP7(#PCDATA)> <!ELEMENTP8(#PCDATA)> <!ELEMENTP9(#PCDATA)> <!ELEMENTP10(#PCDATA)> <!ELEMENTP11(#PCDATA)> <!ELEMENTP12(#PCDATA)> <!ELEMENTP13(#PCDATA)> <!ELEMENTP14(#PCDATA)> <!ELEMENTP15(#PCDATA)> <!ELEMENTP16(#PCDATA)> <!ELEMENTP17(#PCDATA)> <!ELEMENTP18(#PCDATA)> <!ELEMENTP19(#PCDATA)> <!ELEMENTP20(#PCDATA)> <!ELEMENTP21(#PCDATA)> <!ELEMENTP22(#PCDATA)> <!ELEMENTP23(#PCDATA)> <!ELEMENTP24(#PCDATA)> <!ELEMENTP25(#PCDATA)> <!ELEMENTGW(#PCDATA)> <!ELEMENTPORT(#PCDATA)> ]>
2009Netsize
ReceivingMOSMS&StatusReports
26/35
4.4.1.2 StatusReports(SRs)
HereisanexampleoftemplateandDTDthatcanbeusedtotransmitSRs. Template <?xmlversion="1.0"encoding="iso88591"?> <SR> <P1>NotifId</P1> <P2>NotifExtId</P2> <P3>NotifEvent</P3> <P4>NotifReason</P4> <P5>NotifDate</P5> <P6>LOGIN</P6> <GW>GatewayAddress</GW> <PORT>GatewayPort</PORT> </SR> DTD <!DOCTYPESR[ <!ELEMENTSR(P1,P2,P3,P4,P5,P6,GW,PORT)> <!ELEMENTP1(#PCDATA)> <!ELEMENTP2(#PCDATA)> <!ELEMENTP3(#PCDATA)> <!ELEMENTP4(#PCDATA)> <!ELEMENTP5(#PCDATA)> <!ELEMENTP6(#PCDATA)> <!ELEMENTGW(#PCDATA)> <!ELEMENTPORT(#PCDATA)> ]>
2009Netsize
ReceivingMOSMS&StatusReports
27/35
5 SendingWAPPushServiceIndication
ThisappendixexplainshowtousetheNetsizeOTAHTTPInterfacetosendWAPPushServiceIndicationtoa mobilephone.TheNetsizeOTAHTTPInterfaceenablestoformatbinarySMSmessages(nontext messages). Note:WAPPushServiceIndication(SI)isaWAPaddressembeddedwithinaspeciallyformattedSMS. WAPPushSIisdisplayedasanalertmessagetotheenduser.Itgiveshimtheoptionofconnectingdirectly toaparticularURLviathemobilephoneWAPbrowser(ifsupported).
5.1 ConnectionParameters
Parameter Port Note:IfyouwanttosendWAPPushServiceInformationthroughastandard(bulk)SMSaccount,youmust makesurethatyouraccountloginendswith_OTAor$.(Forexample:netsize_OTAorNetsize$) Description Theconnectionportshouldbe38500
5.2 mGatewayURLs
ThetablebelowliststheURLsthatyoucanuse.YoumayusethenearestaccesspointtosendWAPPUSH serviceinformation. Gateway Australia Belgium Germany France Italy Netherlands Spain,Portugal URL http://wwwau.netsizeonline.com/OTAWAPPushSI/Send.asp http://wwwbe.netsizeonline.com/OTAWAPPushSI/Send.asp http://wwwde.netsizeonline.com/OTAWAPPushSI/Send.asp http://wwwfr.netsizeonline.com/OTAWAPPushSI/Send.asp http://wwwit.netsizeonline.com/OTAWAPPushSI/Send.asp http://wwwnl.netsizeonline.com/OTAWAPPushSI/Send.asp http://wwwes.netsizeonline.com/OTAWAPPushSI/Send.asp
2009Netsize
SendingWAPPushServiceIndication
28/35
InputParameters
Parameter sBrokerAddress sBrokerPort sEndpointName sTimeout sLogin sPassword sTarget Description DNSnameorIPaddressofthegatewaytocontact IPportofthegatewaytocontact. AccountParameter Connectiontimeout AccountParameter AccountParameter MSISDNofthemobilephonethatmustreceive themessage. Warning:TheOTAHTTPInterfacesupportsonly oneMSISDNperrequest. sName sUrl sID Textpresentedasthemessagetitleonthemobile phone URLusedtoaccesstheserviceorcontent SIidentifier.EitheryoudefineyourownID(WAP Pushreferenceonthemobilephone)orNetsize willgenerateautomaticallya9characterlongID. Warning:IfyousendanSIIDthatalreadyexists onthehandset,theMTwillbereplacedexceptif yousetthebUseActionparametertoDelete(code 4). bUseAction sAction ActivatestheparameterAction(setvalueon checkbox)anddeactivatesforanyothervalue Specifiestheactionthatshallbetakenwhenthe SIisreceived. Valuesfrom0to3addorupdateaSI.Value4 deleteanexistingSI,whichIDistheIDspecified above. Action SignalNone SignalLow Code 0 1 No No Valueand/orformat ProvisionedbyNetsize ProvisionedbyNetsize ProvisionedbyNetsize Digitalvalueinmilliseconds ProvisionedbyNetsize ProvisionedbyNetsize Mustbeintheinternational format.Ex.+33xxxxxxxxxfor France Required Yes Yes Yes No Yes Yes Yes
Thestringhastostartwith http://orhttps://
Yes Yes No
sCreation
Creationdatetime.ToupdateanexistingSI,you Dateformat:YYYY/MM/DD mustprovideitsIDandacreationdatetimecloser hh:mm:ss thantheoneusedintheexistingSI. Validitydate.SIwillbedeletedwhenthisvalidity dateexpires. ActivatestheSMSnotification(setvalueon checkbox)anddeactivatesforanyothervalue. Dateformat:YYYY/MM/DD hh:mm:ss
sValidity bNotification
No No
Warning:TheparametersDelaydate,SMS_Ext_ID,DISPATCH_PRICE,DISPATCH_OPERATOR, DISPATCH_SHORT_CODEarenotsupportedbytheOTAHTTPinterface.
2009Netsize
SendingWAPPushServiceIndication
29/35
5.2.1.1 WAPPushSizeLimitations
IfyouwanttosendyourWAPPushinasingleMTmessage,youshallconsiderthefollowing: Note:TheparametersIDandACTIONcannotbedeactivated.
Max. usable size without optional parameters ID (9-character default ID) ACTION CREATION DATE VALIDITY DATE Max. usable size with optional parameters 99 112 112 112 112
x x
x x
x x x
x x x x
x
89 89
79
Warning:Usablesize=WAPPushtitle+URL(withoutthehttp://orhttps://part).
2009Netsize
SendingWAPPushServiceIndication
30/35
5.3 TheNetsizeTestForm
Netsizeprovidesyouwithtestforms,whichenableyoutosendHTTPrequests,withouthavingtobuilda wholeHTTPrequest.
2009Netsize
SendingWAPPushServiceIndication
31/35
5.4 SamplesofHTTPRequest
ThefollowingsamplescanbeusedinHTTPGETorHTTPPOST.Theycorrespondtoacustomerwhologsto theFrenchNetsizegatewayandwhohassubscribedtomainoptions.
5.4.1.2 RequestSample
http://wwwfr.netsizeonline.com/OTAWAPPushSI/Send.asp?sBrokerAddress=<fr.netsizeonline.com>& sBrokerPort=38500&sTimeout=5000sLogin=<nsglogin>&sPassword=<nsgpassword>&sEndpoint Name=NSGClientASP%5ENetsize&sTarget=%2B33600000000&sName=Title&sUrl=http://wapserve r.wapsite.com/default.wml&sID=123456@&bUseAction=Checkbox&sAction=2&sCreation=2009%2 F01%2F31+12%3A30%3A00&sValidity=2010%2F01%2F31+12%3A30%3A00&bNotification=Chec kbox&sRequestID=requestID
HTTPPOST
HereisanexampleofHTTPPOSTrequest.
POST /OTA-WAPPushSI/Send.asp HTTP/1.1 Host: fr.netsizeonline.com Content-Type: application/x-www-form-urlencoded sBrokerAddress=<fr.netsizeonline.com>&sBrokerPort=38500&sTimeout=5000sLogin=<nsglogin>&sP assword=<nsgpassword>&sEndpointName=NSGClientASP%5ENetsize&sTarget=%2B33600000000 &sName=Title&sUrl=http://wapserver.wapsite.com/default.wml&sID=123456@&bUseAction=Checkbo x&sAction=2&sCreation=2009%2F01%2F31+12%3A30%3A00&sValidity=2010%2F01%2F31+12%3A 30%3A00&bNotification=Checkbox&sRequestID=<Your Request ID>
2009Netsize
SendingWAPPushServiceIndication
32/35
5.5 ReturnResultPage
AfterreceivingandinterpretingyourHTTPrequest,NetsizesendsanHTTPresponsemessageinplaintext.
ParametersReturned
Tag CODE MESSAGE REASON Type Long String String Description Netsizeerrorcode Theerrormessage(presentedbetweenquotes) Thedescriptionoftheerrormessage(presented betweenquotes),whenavailable NetsizeIDTicket Valueexample 0 "Success" 41959155or1(if MSISDNhasbeen blacklistedbyNetsize)
ID_TICKET
Long
ExampleofReturnResult
CODE = 0 MESSAGE = "Success" REASON = "" ID_TICKET = 41959155
2009Netsize
SendingWAPPushServiceIndication
33/35
Glossary
Term Alias ASCII Definition ASCIIcombinationgeneratedbyNetsize.Analiasisdesignedtospecifytheclientapplication torouteMOSMSmessagesto. ASCII(AmericanStandardCodeforInformationInterchange),isacharacterencodingbased ontheEnglishalphabet.ASCIIcodesrepresenttextincomputers,communications equipment,andotherdevicesthatworkwithtext.Mostmoderncharacterencodingshavea historicalbasisinASCII. Serverwhichreceives,storesandforwardsmessagestoclientapplication.Itstoresthe messageinaqueueuntiltheapplicationisreadytoreceiveit. DCSstandsforDataCodingScheme.TheDCSparameterindicateshowthedataisencoded withinthemessage:whethertheSMSisatextorabinarymessage,andincaseoftext messages,whichalphabetisused. Networkpointthatactsasanentrancetoanothernetwork.Inthenetworkofacompany,a computerserveractingasagatewaynodeisoftenalsoactingasaproxyserverandafirewall server.Gatewaysalsoinvolvetheuseofroutersandswitches. GSMSMSclassesareoptionsfortheterminationofSMSonamobilephone: Class Description 0 1 2 3
Broker DCS
Gateway
Unicode OAdC
Unicodeisanindustrystandardwhosegoalistoprovidethemeansbywhichtextofallforms andlanguagescanbeencodedforusebycomputers. ShortforOriginatingAddressCode.TheOAdCcorrespondstothetelephonenumberofthe SMSsender.CustomersuseOAdCtodisplayspecificdataonthemobilephonescreenoftheir endusers.TheOAdCiscomposedofnumericoralphanumericcharacters. ShortforSecureSocketsLayer.SSLisaprogramlayercreatedtomanagethesecurityof messagetransmissionsinanetworkandtohidetheinformationawebbrowserandaweb serversendtoeachother.Aprotocoldesignedtoenablesecuredcommunicationsacrossthe Internet,providingprivacy,authentication,andmessageintegrity.SSLisusedmostly(butnot exclusively)incommunicationsbetweenWebbrowsersandWebservers. Astatusreport(SR)ornotificationisanoptionwhichletsyougetinformationrelatedtothe deliverystatusoftheMTmessage. ShortforTicketIdentifier.IDNumberattributedbyNetsizetoaMTmessagetoenablethe customertotrackhismessageandtoknowthemessagestatus.
SSL
LegalInformation
TheinformationsuppliedinthisdocumentisNetsizeS.A.solepropertyandcopyright. Itisintendedforstrictlyinformationaluse.Itisnotbindingandmightbesubjecttochangeswithoutnotice. Anyunauthorizeddisclosureshallbeconsideredasunlawful. NetsizeisprotectedbyFrench,EECandinternationalintellectualpropertylaws. Allothertrademarksquotedarethesolepropertyoftheirrespectiveowners. NETSIZES.A. 53,RueRaspail92594LevalloisPerretFrance Tel:+33(0)141275600 Fax:+33(0)141275700 http://www.netsize.com