Embed Size (px)
Citation preview
GTXMobileMessagingSMSGatewayInterface
SimpleHTTPAPIManual
Revision:50RevisionDate:09.06.1714:43Author:OliverZabel
2
TableofContentsTableofContents..................................................................................................................................2Introduction............................................................................................................................................3
SendingSMS............................................................................................................................................3Targets........................................................................................................................................................................................3Request.......................................................................................................................................................................................3Encoding................................................................................................................................................................................4
RequestExamples..................................................................................................................................................................4Simpletextmessage.........................................................................................................................................................4BinarymessagecontainingaWAP-Push.................................................................................................................4Multi-bytemessagewithUCS-2codeddata(usingBINARYformatandDCS).......................................4Multi-byteUTF-8message(withUCS-2coding)..................................................................................................4
Response....................................................................................................................................................................................5ResponseExamples...............................................................................................................................................................5Successfulsubmission.....................................................................................................................................................5ServiceUnavailable...........................................................................................................................................................5
ReceivingDLRs......................................................................................................................................6RequestParameters..............................................................................................................................................................6Statusdefinitions...................................................................................................................................................................6ExampleDLRcallback..........................................................................................................................................................6
ReceivingSessionReplies..................................................................................................................7RequestParameters..............................................................................................................................................................7Examplesessionreply.........................................................................................................................................................7
ReceivingSMS.........................................................................................................................................8RequestParameters..............................................................................................................................................................8ExampleMOSMS....................................................................................................................................................................8
SampleCode............................................................................................................................................9SendatextSMS.......................................................................................................................................................................9SendaUnicodeSMS............................................................................................................................................................10ProcessaDLRcallback......................................................................................................................................................11Processasessionreplycallback....................................................................................................................................12ProcessaMOSMScallback..............................................................................................................................................12
3
IntroductionTheMobileMessagingSMSGatewayprovidesaneasy-to-useandeasy-to-implementHTTP-GETinterfaceforreceivingandsubmittingmessagesfromandtothegateway.Thismanualwilldescribetheinterfaceandprovidesomeexamplesonhowtousetheinterface.Ifyouhavefurtherquestionsregardingthisinterface,pleasecontactyouraccountmanagerorfileatroubletickettosupport@gtx-messaging.com.
SendingSMS
TargetsYoucanreachtheSMSGatewayunderthefollowingURLusingHTTP:
http://http.gtx-messaging.net/smsc.php
IfyouprefertouseaHTTPSconnectioninstead,pleaseusethisendpoint:
https://http.gtx-messaging.net/smsc.php
RequestThefollowingHTTP-GETorHTTP-POSTparametersshouldbesetwhensendingamessage:Field Mandatory Type Description Exampleuser yes String Yourusername "comp_gold_001"pass yes String Yourpassword "topsecret"from1 optional AlphanumericString,
Numeric,MSISDNTheTPOA/originatorofthemessage
"Company","49171000000","55888"
to yes MSISDN Therecipientofthemessage,internationalformat,no"+"
"491701234567","44751234567"
t optional TEXT|BINARY|UNICODE Typeofthemessage(defaultsto"TEXT")
"TEXT"
text2 optional String Textofthemessage "Hello World"coding3 optional FixedString UseUCS-2coding "ucs2"udh4 optional HEX CustomUDH "0605040B8423F0"data4 optional HEX CustomData "1B0601AE02056..."dcs4 optional Integer CustomDCS "8"1)TheTPOAinthefrom-fieldmaybeoverridden,basedonyourprofile/contract.IncaseyoudonothaveacustomTPOA,thisparametercanbeleftout.Pleasenotethatspecialcharactersarenotallowed.2)Whenusingmulti-bytetext(UTF-8),makesuretosetthet-parameterto"UNICODE",onlymandatorywhenthet-parameteriseither"TEXT"or"UNICODE".PleaseseetheEncodingreferencebelow.3)Onlyapplicablewhenthet-parameterissetto"UNICODE".PleasenotethatUCS-2codingrequiresmorebytespercharacter.Asingle-partmessagecancontainupto70characters,multi-partmessagescancontainupto67characters.4)Onlyapplicablewhenthet-parameterissetto"BINARY".
4
EncodingThegatewayinternallyusesUTF-8encoding.Ifyousubmitmessagesasplaintext(parametert=TEXT,default)thenthegatewaywillassumethatthetextisencodedusingWindows-1252(a.k.a.CP-1252).IfyouwanttosubmitUTF-8textpleasesettheparametert=UNICODE.PleasenotethatspecialUnicodecharacterscanonlybetransmittedusingUCS-2coding.Wikipediaprovidesagoodreference;pleaseseehttp://en.wikipedia.org/wiki/Windows-1252orhttp://en.wikipedia.org/wiki/UTF-8formoreinformation.
RequestExamples
SimpletextmessageTheeasiestwayofusingtheinterface:
http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&from=ACME&to=491701234567&text=Hello+World
BinarymessagecontainingaWAP-PushSendaWAP-Pushmessagetotherecipient(maynotworkonallproducts,pleaseaskyouraccountmanagerfordetailsaboutspecialbinarycontent):
http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&to=491701234567&t=BINARY&udh=0605040B8423F0&data=1B0601AE02056A0045C60C037777772E796F632E636F6D0001034D6F62696C6520456E61626C696E67000101
Multi-bytemessagewithUCS-2codeddata(usingBINARYformatandDCS)Ifyourclientalreadyencodesmulti-bytemessagesusingUCS-2itself,youmaysimplysupplythatcodeddataandsetthenecessaryDCSbyyourself:
http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&to=491701234567&t=BINARY&data=041F044004804204504B&dcs=8
Multi-byteUTF-8message(withUCS-2coding)InthisexamplethetextissubmittedusingUTF-8encoding.Bysettingtheparametercoding=ucs2thegatewayisrequestedtoencodethismessageinUCS-2:
http://http.gtx-messaging.net/smsc.php?user=comp_gold_001&pass=topsecret&from=ACME&to=491701234567&t=UNICODE&text=%D0%9F%D1%80%D0%B8%D0%B2%D0%B5%D1%82&coding=ucs2
5
ResponseTheGatewaywillreturnaresponsecontainingaresultoftheperformedoperation.Iftheoperationwassuccessful,theresultwillcontainamessageIDthatwillbereferredtowhensendingaDLRtothecustomer(seeexamples).Thefollowingerrorcodeswillbereturned:Code Description200 OK Messagesent(includesmessageID)400 Bad Request Malformedorbadrequestsubmitted401 Unauthorized Wrongusername/password408 Blacklist Therecipientisblacklisted(uponrequest)503 Service Unavailable Serviceiscurrentlyunavailable,pleasetryagain
ResponseExamples
SuccessfulsubmissionThesubmittedmessagewassentsuccessfullyandassignedtheinternalmessageID26818021.
HTTP/1.1 200 OK\r\n (HTTP Headers shortened) Content-Length: 17\r\n \r\n 200 OK (26818021)
ServiceUnavailableTheserviceistemporarilyunavailable,pleasetryagainlater.
HTTP/1.1 200 OK\r\n (HTTP Headers shortened)\r\n Content-Length: 23\r\n \r\n 503 Service Unavailable
6
ReceivingDLRsThegatewaywillreturnanasynchronousdeliveryreport(DLR)toyoursiteviaHTTPGET.InordertoreceiveDLRsyourprofilemustsupportDLRsandyoumustprovideGTXwithacallbackURLthatwillsatisfythefollowinginterfacerequirements.TheDLRcallbackreferstothemessageIDthatwaspreviouslyreturnedinresponsetothesubmissionandwillcontainthedestinationMSISDNofthesubmittedmessage.
RequestParametersThefollowingparameterswillbeprovidedtothecallbackURL:Field Mandatory Type Description Exampleid yes Unsigned
LongThemessageIDthisDLRrefersto "21498252"
status yes Integer Thelaststatusofthismessage "8"snr yes MSISDN Thenumberoftherecipient "+491721234567"
StatusdefinitionsThestatuscodesprovidedtothecallbackURLshouldbeinterpretedinthismanner:Status Description1 Deliveredtophone2 Notdeliveredtophone4 QueuedonSMSC8 DeliveredtoSMSC16 NotdeliveredtoSMSC
ExampleDLRcallbackGiventhatyouhaveprovidedyouraccountmanagerwiththecallbackURL:
http://system.company.com/dlr.cgi
AsampleDLRcallbackcouldlooklikethis:
http://system.company.com/dlr.cgi?id=12345678&status=1&snr=%2B491721234567
Thiscallbackreportsthatthemessageidentifiedby12345678wassuccessfullydeliveredtotherecipientsphone.Therecipientnumberis+4916721234567.
7
ReceivingSessionRepliesWhenusinga2wayproduct(e.g.Silver2way)therecipientofthemessagecanreplytoit.Thisreplywillberedirectedtoagiveninterfacetoyoursite.InordertoreceivethesesessionrepliesyoumustprovideGTXwithacallbackURLthatwillsatisfythefollowinginterfacerequirements.ThesessionreplywillrefertotheoriginalmessageIDthatwaspreviouslyreturnedinresponsetothesubmission.Pleaseaskyouraccountmanagerabout2wayproductsformoredetails.
RequestParametersThefollowingparameterswillbeprovidedtothecallbackURL:Field Mandatory Type Description Exampleid yes Unsigned
LongThemessageIDthisreplyrefersto "21498252"
from yes MSISDN Thenumberoftheoriginator(formerrecipient)
"00491717654321"
to yes MSISDN Alwaysthevirtualnumber: "00491710000000"text yes String Themessageofthereply(UTF-8) "Ping back"user yes String Yourusername "comp_gold_001"
ExamplesessionreplyGiventhatyouhaveprovidedyouraccountmanagerwiththecallbackURL:
http://system.company.com/reply.cgi
Asamplesessionreplycallbackcouldlooklikethis:
http://system.company.com/reply.cgi?id=12345678&from=00491721234567&to=00491710000000text=Ping%20back
Thiscallbackreportsthatthereisamessagefromtheuser00491721234567inreplytothemessageidentifiedby12345678.Themessagetextis"Ping back".
8
ReceivingSMSToreceiveSMSonashortcodeoralongnumberyoumustprovideGTXwithacallbackURLthatwillsatisfythefollowinginterfacerequirements.
RequestParametersThefollowingparameterswillbeprovidedtothecallbackURL:Field Mandatory Type Description Exampletimestamp yes UNIXTimestamp Thetimestampofthemessage
(GMT)"1306413940"
from yes MSISDN Thenumberoftheoriginator "00491717654321"to yes MSISDN Therecipientofthemessage "55123"or
"00491715554443"text yes String Themessagesentbythe
originator(UTF-8)"Hello World"
user yes String Yourusername "comp_gold_001"
ExampleMOSMSGiventhatyouhaveprovidedyouraccountmanagerwiththecallbackURL:
http://system.company.com/inbox.cgi
Asamplesessionreplycallbackcouldlooklikethis:
http://system.company.com/inbox.cgi?from=00491721234567&to=55123&text=Hello%20World×tamp=1206415240
Thiscallbackreportsthatthereisamessagefromtheuser00491721234567thatwassenttotheshortcode55123onTue, 25 Mar 2008 at 03:20:40.Thetextofthemessageis"Hello World".
9
SampleCodeThissamplepseudo-codeiswritteninPHPandwillhelptodemonstratehowtheinterfaceisused.Itdoesnotincludeanyerrorhandlingandisnotmeantasarecommendationbutjustforillustrativepurposes.
SendatextSMS
<?php $gw = "http://http.gtx-messaging.net/smsc.php"; $auth = array( 'user' => 'comp_gold_001' , 'pass' => 'topsecret' ); $message = array( 'from' => 'ACME' , 'to' => '491701234567' , 'text' => 'Hello World!' ); $url = $gw."?user=".$auth['user']."&pass=".$auth['pass']; $url .= "&from=".urlencode($message['from'])."&to=".$message['to']; $url .= "&text=".urlencode($message['text']); $cp = curl_init($url); curl_setopt($cp, CURLOPT_HEADER, false); curl_setopt($cp, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($cp); if ($result === false) { // error handling } else { // parse response message } curl_close($cp); ?>
10
SendaUnicodeSMS
<?php // Assuming this file is UTF-8 $gw = "http://http.gtx-messaging.net/smsc.php"; $auth = array( 'user' => 'comp_gold_001' , 'pass' => 'topsecret' ); $message = array( 'from' => 'ACME' , 'to' => '491701234567' , 'text' => 'Привет' , 'coding' => 'ucs2' ); $url = $gw."?user=".$auth['user']."&pass=".$auth['pass']; $url .= "&from=".urlencode($message['from'])."&to=".$message['to']; $url .= "&text=".urlencode($message['text']); $url .= "&t=UNICODE&coding=".$message['coding']; $cp = curl_init($url); curl_setopt($cp, CURLOPT_HEADER, false); curl_setopt($cp, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($cp); if ($result === false) { // error handling } else { // parse response message } curl_close($cp); ?>
11
ProcessaDLRcallbackWeareusingapseudo-classfordatabaseabstraction.
<?php if (isset($_REQUEST['id'], $_REQUEST['status'], $_REQUEST['snr'])) { $db->connect('to', 'my', 'database'); $sql = "UPDATE my_message_table "; $sql .= "SET last_status = ? "; $sql .= "WHERE remote_id = ? "; $sql .= "AND destination = ? "; $sql .= "LIMIT 1"; $statement = $db->prepare($sql); $statement->bindParam($_REQUEST['status']); $statement->bindParam($_REQUEST['id']); $statement->bindParam($_REQUEST['snr']); $statement->execute(); $db->disconnect(); } ?>
12
ProcessasessionreplycallbackWeareusingapseudo-classfordatabaseabstraction.
<?php if (isset($_REQUEST['id'], $_REQUEST['from], $_REQUEST['text'])) { $db->connect('to', 'my', 'database'); $sql = "INSERT INTO my_reply_table "; $sql .= "(message_id, originator, text) "; $sql .= "VALUES (?, ?, ?)"; $statement = $db->prepare($sql); $statement->bindParam($_REQUEST['id']); $statement->bindParam($_REQUEST['from']); $statement->bindParam($_REQUEST['text']); $statement->execute(); $db->disconnect(); } ?>
ProcessaMOSMScallbackWeareusingapseudo-classfordatabaseabstraction.
<?php if (isset($_REQUEST['from], $_REQUEST['to'], $_REQUEST['timestamp'], $_REQUEST['text'])) { $db->connect('to', 'my', 'database'); $sql = "INSERT INTO my_mo_table "; $sql .= "(originator, destination, ts, text) "; $sql .= "VALUES (?, ?, ?, ?)"; $statement = $db->prepare($sql); $statement->bindParam($_REQUEST['from']); $statement->bindParam($_REQUEST['to']); $statement->bindParam(date('Y-m-d H:i:s', $_REQUEST['timestamp'])); $statement->bindParam($_REQUEST['text']); $statement->execute(); $db->disconnect(); } ?>
