atms PremiumSMS Documentation Info Hotline: Author: Karl Lettner English Version: Gerald Eigenstuhler

Transcription

1 atms PremiumSMS Documentation Info Hotline: Author: Karl Lettner English Version: Gerald Eigenstuhler Version 1.8 Last modified: Page 1

2 Contents: 1 Introduction MO-SMS MT-SMS Interfaces HTTP MO SMS IP-Addresses URL-Parameter for MO-SMS Response Sample HTTP-Requests MT - SMS-Delivery HTTP-Request URL-Parameter for SMS-MT-Delivery Response Examples Error Codes for http-interface MT Delivery Notification/Barring-Check URL-Parameter Security IP-RESTRICTION VPN VPN-Parameters Document History Version Datum Page 2

3 1Introduction For premium services (Value added Services=VAS) our system will process all retrieved SMS before delivering them to you. SMS sent from third party to mobile phones (MT-SMS) are processed by our system and afterwords transmitted thru the custom mobile network provider. We offer some interfaces to the third party to send and retrieve messages. The major interface for this is an http-based interface, which will be described in this document. 1.1MO-SMS Mobile Originated (MO) SMS receive SMS 1.2 MT-SMS Mobile Terminated (MT) SMS deliver SMS Page 3

4 2Interfaces 2.1HTTP We support different interfaces to connect to our system: HTTP-Request (GET or POST) object of this document SMPP 3.3 or 3.4 (Short Message Peer to Peer Logica) UCP 4.0 (Universal Computer Protocol CMG) CIMD I or II (Computer Interface to Message Distribution Nokia) OIS (Open Interface Specification SMS2000 SEMA) Each interface is able to handle both, text and binary messages. The http interface is available for both directions, MO and MT. A high availability cluster on our site handles request from the third party to us. The other direction is also done by http-requests. So the third party has to provide us with at least one URL (two would be better for redundancy issues) we can make the request to MO SMS MO-SMS are transmitted to the third party by HTTP(S)-GET request, using a set of predefined parameters (see section ). In the ordering form you could specify one or more URLs we should use for delivering MO- SMS. If you provide us with two or more URLs we will call the second (third,...), if the first one does not work. Please remember this only makes sense if they are located on different systems. If not specified by you we will use port 80 for the requests. i.e. : Attention: If your server fails, we will check it periodically to see if it is online back again. This check will be done by calling the URL without any parameters. So it is important that your service answers such a call with a header containing HTTP/ OK. The page content should contain only the word Error. Example response to a call without parameters: HTTP/ OK Date: Wed, 22 Dec :00:00 GMT Server: Apache/ (Unix) Debian GNU/Linux PHP/4.3.4 Connection: close Transfer-Encoding: chunked Content-Type: text/html; charset=iso ERROR IP-Addresses If your system is guarded by a firewall you have to configure it in a way, which allows our server to connect to you. IP-Addresses: / / 32 Page 4

5 URL-Parameter for MO-SMS The following parameters are used Parameter- Mandatory Name: Optional Description: Example: UID O Optional if you want a user authentication User123 PW O Optional if you want a password authentication Pwhzd63 PID M Project-ID ANR M Phone number of the orginating mobile phone ZNR M Destination number the SMS was addressed to MSG M Content of the SMS Das+ist+der+Text ID M ID of the SMS SZP O Transmittion-timestamp of the (optional) Format: YYYYMMDDHHMMSS SMSC M Network provider SMS (optional) A_MK A_MK mobilkom austria AG & Co KG A_TM T-Mobile Austria GmbH A_ONE ONE - Connect Austria A_H3G Hutchison 3G Austria GmbH A_YES YESSS! Telekommunikation GmbH CH_SC CH_SR CH_OR D_TM D_VO D_EP D_O2 D_DT D_MC D_TL D_VV D_PH CZ_ET CZ_TM CZ_OS Schweiz Swisscom Schweiz Sunrise Schweiz Orange Deutschland T-Mobile Deutschland GmbH Deutschland Vodafone D2 GmbH Deutschland E-Plus Service GmbH & Co.KG Deutschland O2 GmbH & Co. OHG Deutschland debitel AG Deutschland mobilcom GmbH Deutschland TALKLINE GmbH & Co. KG Deutschland VICTORVOX GmbH Deutschland The PhoneHouse Telecom GmbH Tschechien EuroTel Tschechien T-Mobile Tschechien Oskar Response To check the success of the delivery request we need a defined response from you. In the case of a successfull processing you should return an OK in the response (pure text no html) HTTP/ OK Date: Wed, 22 Dec :00:00 GMT Server: Apache/ (Unix) Debian GNU/Linux PHP/4.3.4 Connection: close Transfer-Encoding: chunked Content-Type: text/html; charset=iso OK Each other response is treated as error Sample HTTP-Requests This example covers a SMS sent from to on at 15:11:15 with message text: This is the text. Our internal id for this SMS is According to the above example data we make the following HTTP-GET Request: UID=User123&PW=Pwhzd63&PID=579901&ANR= &ZNR= &MSG=This+is+the+text&SZP= &ID=256874&SM Page 5

6 SC=A_MK 2.1.2MT - SMS-Delivery To deliver a MT-SMS to us, you have to make an http-request to our server. To send data-sms (ring tones, wap-push,...) there are two options: 1.You can set the parameter TYPE which defines if an sms is sent with (TYPE=16) or without (TYPE=8) user data header. All data has to be hex encoded and is limited to 140Byte (280 characters) 2.By using the parameter DCS you are able to set every supported DCS-Value. In this case you have to use the MSG parameter to set the user data. If a user data header should be used, the parameter UDH must be set. (without the UDH Length byte) The evaluation of the parameters follows the process figured out in the flowchart below: SMS-Delivery No TYPE>0 Yes DCS>0 No TYPE =? Yes TYPE = 4 TYPE = 8 TYPE = 16 evaluated Parameter: DCS = DCS UDH = UDH (if present) UserData = MSG Treated as Text-SMS Flash: DCS = 16 8 Bit without UDH: DCS = 4 UserData = MSG 8 Bit with UDH: DCS = 4 UDH and UD read form MSG Page 6

7 HTTP-Request Delivering a message is done by calling the following URL with a HTTP-GET or HTTP-POST Request. TCP-Port URL-Parameter for SMS-MT-Delivery Parameter- Mandatory Name: Optional Description: Example: UID M User-ID (defined by us) 5799 UPW M User-Password (defined by us) 58er62je PID M Project-ID (defined by us) Identifies the project ZNR M Destination number If this MT was preceded by a MO-SMS our system creates a correlation between the messages based on the destination number. MSG M Message text: Max. length 160 characters (URL-encoded) Das%20ist%20die %20Antwort Or 280 Characters for 8 hex encoded binary messages TYPE O Type of SMS: 16 0=normal SMS (default) 4=Flash Text-SMS 8=8 Bit message 16=8 Bit UDH DCS O DCS of the SMS (see Specification 3GPP TS ) 195 Decimal Value! (binary= decimal=195) UDH O User-Data-Header of the SMS 05040B8423F0 (see Specification 3GPP TS ) BILL O Trigger a charging: 1 If a MT charged Premium (VAS) Number is used for this Project this parameter says if a charging should be done or not. The charging amount must be predefined in our system. 0 = MT-SMS not charged 1 = MT-SMS charged (Default) CHARSET O Characterset ISO (Default) UTF-8 UTF-8 SZP O Transmission timestamp of the SMS: If not set the sms will be transmitted by now. Format: YYYYMMDDHHMMSS (+1 GMT) As alternation you can set a deferral time in minutes min delay (the + sign must be URL-encoded) means sending on :21:15 %2B15 For 15 min delay. Page 7

8 EXP O SMS expires on given date If no value is set, the default from the responsible mobile network provider is used. Format: YYYYMMDDHHMMSS (+1 GMT) DN O Delivery Notification: 0 = no delivery notification 1 = delivery notification requested To relate the delivery notification to the message belonging to it is necessary that you store the message id we give you back in the response of the MT-Request. MEMO O Additional information (i.e..: your internal message id) Format: String 30 characters valid till :21:15 1 my internal id is Page 8

9 Response If the request was successful you will get the following response: 1. Row: OK 2. Row: Row: MsgID: If there was an error in processing your request you will get the following response: 1. Row: ERROR 2. Row: Error code i.e.: 201 (see table on next page) 3. Row: description of the error The response is plain text as the example below shows: HTTP/ OK Date: Wed, 22 Dec :00:00 GMT Server: Apache/ (Unix) Debian GNU/Linux PHP/4.3.4 Connection: close Transfer-Encoding: chunked Content-Type: text/html; charset=iso OK 100 MsgID: In the case of error: HTTP/ OK Date: Wed, 22 Dec :00:00 GMT Server: Apache/ (Unix) Debian GNU/Linux PHP/4.3.4 Connection: close Transfer-Encoding: chunked Content-Type: text/html; charset=iso ERROR 201 user-id missing Page 9

10 Examples Example 1: send sms with no extra delay: PID=579901&ZNR= &MSG=Danke%20f%C3%BCr%20Dein%20SMS Example 2: send sms at :30 and validity about 6 hours: PID=579901&ZNR= &SZP= &EXP= &MSG=Das%20ist%20die%20Antwort Example 3: 8Bit Data-SMS with UserDataHeader (used TYPE = 16): PID=579901&ZNR= &TYPE=16&MSG= A3A5D49 D591BDB1C1A004007F1C A A23020C21449AA1 0610A A81861A A288C A04E A A06186A A A Example 4: 8Bit Daten-SMS with UserDataHeader (used DCS = 4): PID=579901&ZNR= &DCS=4&UDH= &MSG=024A3A5 D49D591BDB1C1A004007F1C A A23020C21449 AA10610A A81861A A288C A04E A A06186A A A Page 10

11 Error Codes for http-interface Error-Code Description: 100 OK 201 userid missing 202 user unknown 211 password missing 212 password wrong 301 project id missing 302 project id wrong 321 invalid value in paramter BILL 401 Desintation number missing 402 Destination number Zielrufnummer falsches Format 403 invalid destination provider 421 message missing 422 message to long 423 no data in message paramete 424 to many data transmitted 501 invalid TYPE value 521 delivery timestamp invalid 531 vality period invalid 999 System-Error Page 11

12 2.1.3MT Delivery Notification/Barring-Check For MT-SMS you can request a delivery notification (DN) [see section ]. Delivery notifications are transmitted by calling a URL thru a HTTP-GET Request. You can provide us with a URL the delivery notification should be sent to. By default the DN is sent to the same URL as used for the MO-SMS delivery. In the case of PremiumSMS it is possible to make a barring-check. If charging is not possible or the barring check is negative we will you provide with an according delivery notification. Barring-checks are not possible to all network providers URL-Parameter Parameter- Mandatory Name: Optional Description: Example: UID O Optional, UserId User123 PW O Optional, password Pwhzd63 TYPE M type of message 1 1 = DeliveryNotification 2 = Charging problem - SMS barred ZNR M Destination number MSGID M MsgID of the SMS [ ] CODE M Result-Code: 11 For DeliveryNotifications 11 = delivered 12 = expired 13 = accepted 14 = deleted 15 = undelivered 16 = unknown 17 = rejected For Barring-Check: 21 = non-billed MSG M Info-Text DELIVRD EXPIRED ACCEPTD DELETED UNDELIV UNKNOWN REJECTD NONBILL DELIVRD Page 12

13 3Security Due to security reasons we restrict access to our servers. To gain access you have to use one of the following possibilities: IP-Restriction VPN 3.1IP-Restriction We will grant access to your official ip addresses in our firewalls. Delivering sms will be possible only from these configured addresses. For using IPrestriction, you need (an) static ip address(es). You can only connect to the default http port (80). All other ports and protocols are closed. To restrict access to your server please configure your firewall/server to allow connections from the following ip addresses/ranges: /32 3.2VPN 3.2.1VPN-Parameters Parameter-Name: mobileworx: Your configuration: Hardware Juniper SSG550 OS-Version 6.0.0r2.0 VPN-Gateway (Tunnel-Endpoint) Encryption Domain (Appl.-Server) /27 IKE-Method Preshared-Key IKE-Mode Main IKE-Preshared-Key Via Phone/SMS IKE-DH-Goup 2 IKE-Encryption 3DES IKE-Hash SHA-1 IKE-Lifetime Sec. = 8 hour. IPSek-PFS IPSek-ESP-Encrypt. IPSek-ESP-Auth. IPSek-Lifetime IPSek-PFS NoPFS 3DES SHA Sek. NoPFS Only official IP-Addresses are possible as values for the Encryption-Domain. The preshared key will be communicated to you by phone or sms. Page 13

14 4Document History Vers Datu m Description: Neue Anlieferungs-Seite für HTTP-GET - Anlieferungs-Seite für HTTP-POST Neuer MT-Parameter BILL - Fehlercode 321 eingefügt - Neue Einteilung der Fehlercodes Neuer M0-Parameter SMSC Neuer MT-Parameter CHATSET - zusätzliche Fehlercodes 403, neue MT-Anlieferungsseite - zusätzliche SMSC-Werte für die MO-Auslieferung Neuer MT-Parameter EXP - zusätzlicher Fehlercode Neuer MT-Parameter DN, DCS, UDH - MT DeliveryNotification/Barring-Check Kapitel Sicherheit geändert - zusätzliche Werte für SMS-Empfang [ ]: CZ_ET, CZ_TM, CZ_OS Anlieferungs-URL geändert [ ] - Adressen für IP-Restriction geändert [ ] - Parameter SZP geändert (+min Verzögerung) [ ] - zusätzlicher Error-Code [ ] - deutsche Netzbetreiber eingefügt für Parameter SMSC [ ] 1.8.eng Translated into englisch (as far as possible) fixxmee: split parameter missing Page 14