Dialogic DSI SS7G41 Signaling Server

Transcription

1 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual

2 Copyright and Legal Notice Copyright Dialogic Inc. All Rights Reserved. You may not reproduce this document in whole or in part without permission in writing from Dialogic Inc. at the address provided below. All contents of this document are furnished for informational use only and are subject to change without notice and do not represent a commitment on the part of Dialogic Inc. and its affiliates or subsidiaries ( Dialogic ). Reasonable effort is made to ensure the accuracy of the information contained in the document. However, Dialogic does not warrant the accuracy of this information and cannot accept responsibility for errors, inaccuracies or omissions that may be contained in this document. INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND DIALOGIC, DIALOGIC ASSUMES NO LIABILITY WHATSOEVER, AND DIALOGIC DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF DIALOGIC PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY INTELLECTUAL PROPERTY RIGHT OF A THIRD PARTY. Dialogic products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications. Due to differing national regulations and approval requirements, certain Dialogic products may be suitable for use only in specific countries, and thus may not function properly in other countries. You are responsible for ensuring that your use of such products occurs only in the countries where such use is suitable. For information on specific products, contact Dialogic Inc. at the address indicated below or on the web at It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this document, in marketing collateral produced by or on web pages maintained by Dialogic may infringe one or more patents or other intellectual property rights owned by third parties. Dialogic does not provide any intellectual property licenses with the sale of Dialogic products other than a license to use such product in accordance with intellectual property owned or validly licensed by Dialogic and no such licenses are provided except pursuant to a signed agreement with Dialogic. More detailed information about such intellectual property is available from Dialogic s legal department at 926 Rock Avenue, San Jose, California USA. Dialogic encourages all users of its products to procure all necessary intellectual property licenses required to implement any concepts or applications and does not condone or encourage any intellectual property infringement and disclaims any responsibility related thereto. These intellectual property licenses may differ from country to country and it is the responsibility of those who develop the concepts or applications to be aware of and comply with different national license requirements. Dialogic, Dialogic Pro, Dialogic Blue, Veraz, Brooktrout, Diva, Diva ISDN, Making Innovation Thrive, Video is the New Voice, Diastar, Cantata, TruFax, SwitchKit, SnowShore, Eicon, Eicon Networks, NMS Communications, NMS (stylized), Eiconcard, SIPcontrol, TrustedVideo, Exnet, EXS, Connecting to Growth, Fusion, Vision, PowerMedia, PacketMedia, BorderNet, incloud9, I-Gate, Hi-Gate, NaturalAccess, NaturalCallControl, NaturalConference, NaturalFax and Shiva, among others as well as related logos, are either registered trademarks or trademarks of Dialogic Inc. and its affiliates or subsidiaries. Dialogic's trademarks may be used publicly only with permission from Dialogic. Such permission may only be granted by Dialogic s legal department at 926 Rock Avenue, San Jose, California USA. Any authorized use of Dialogic's trademarks will be subject to full respect of the trademark guidelines published by Dialogic from time to time and any use of Dialogic s trademarks requires proper acknowledgement. The names of actual companies and products mentioned herein are the trademarks of their respective owners. This document discusses one or more open source products, systems and/or releases. Dialogic is not responsible for your decision to use open source in connection with Dialogic products (including without limitation those referred to herein), nor is Dialogic responsible for any present or future effects such usage might have, including without limitation effects on your products, your business, or your intellectual property rights. Publication Date: February 2013 Document Number: U01LGD 2

3 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 Revision History Issue Date Description 4 February 2013 Addition of multiple profiles 3 April 2012 Support for SWS Release added. 2 September 2011 General Availability 1 July 2011 Initial version for Beta release Contents Revision History... 3 Contents Introduction Signaling Service Support Feature Overview Abbreviations Related Information SWS Mode Overview Architecture Overview Signaling Topologies Multiple Network Support Protocol Handling for Multiple Network Contexts Inter-SWS Communications Transaction-Based Applications Management of Local SCCP Sub-Systems Alarms Interfaces Application Interface Configuration Interface Management Interface, Trace, and Diagnostics Network Interfaces Web Services APIs Overview Summary Supported URIs / Methods Payload Structure HTTP Response Codes MAP Services Used Short Message API Sending an SMS Support for Report SM Delivery Receiving an SMS Sending a binary format SMS Receiving a binary format SMS Sending a concatenated binary format SMS Receiving a concatenated binary format SMS Mobile Originated SMS

4 Contents 4.8 Sending Atomic MT-SMS Sending a binary format Atomic MT-SMS Sending Concatenated Atomic MT-SMS Sending Atomic Send Routing Info For SM Sending Atomic Report SM Delivery Sending Atomic Ready For SM Receiving Atomic Send Routing Info For SM Receiving an Alert Service Centre USSD API Mobile Initiated Sessions Client Application Initiated Session Client Application Initiated - USSD Notify Location and Subscriber Polling API Location API Subscriber State API Get IMSI API Profiles and Multiple Network Support Introduction to Profiles Transmit Profiles Receive Profiles Parameter Reference SMS Service SMS Deliver parameters Atomic SMS-MT Service MO-SMS Service SMS Submit parameters Alert Service Centre Service Send Routing Info For SM Service Inform Service Centre parameters Report SM Delivery Status Service USSD Service Location Service Cell Id Parameters Subscriber State Service Get IMSI Service Error Error Code Types Error Code Type internalfailurecodetype Error Code Type maperrorcodetype Error Code Type usererrorcodetype Error Code Type providererrorcodetype MAP User Errors Application Development Guidelines Application Development Frameworks XML Handling HTTP/HTTPS Use of Expect: HTTP 100 Continue Application Examples Java SWS Test Utility

5 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue C# SWS Example Application PHP Example Appendix A. XSD Files A.1 SWS XSD Schema Appendix B. Testing Extensions to the API B.1 Receiving Atomic Send Routing Info For SM B.2 Receiving Ready For SM B.3 Receiving Report SM Delivery B.4 Receiving Location Request B.5 Receiving Subscriber State Request B.6 Transmitting Alert Service Centre Request B.7 Receiving Get IMSI Request Figures Figure 1: Single SWS Figure 2: Signaling Paths in a Dual Resilient Configuration Figure 3: Single SWS Connected to SSP/SCP or STP Figure 4: SWS Dual Configuration with Connections to SSP/SCP Figure 5: SWS Dual Configuration with Connections to STP Figure 6: SWS Dual Configuration with Connections to Mated STP Pair Figure 7: Module IDs for Use with Multiple Network Contexts Figure 8: Interfaces Figure 9. Sending an SMS (Network Diagram) Figure 10: Sending an SMS (Full Message Flow without Report SM Delivery) Figure 11: Sending an SMS (Full Message Flow with Report SM Delivery) Figure 12: Receiving an SMS Figure 13: Sending a concatenated SMS Figure 14: Receiving a concatenated SMS Figure 15: Transmitting an Atomic MT-SMS Figure 16: Transmitting a Concatenated atomic MT-SMS Figure 17: Transmitting a Send Routing Info For SM Figure 18: Transmitting a Report SM Delivery Figure 19: Transmitting a Ready For SM Figure 20: Receiving a Send Routing Info For SM Figure 21: Receiving Alert Service in Auto Mode Figure 22: Receiving Alert Service in Abort Mode Figure 23: Receiving an Alert Service Request in Manual Mode Figure 24: Mobile Originated USSD session Figure 25: Application Originated USSD session Figure 26: Application Originated USSD session with USSD Notify Figure 27: Sending a USSD Notify Figure 28: Requesting a mobile location Figure 29: Requesting a mobile subscriber state Figure 30: Requesting the IMSI from the HLR Figure 31: Java SMS Test Sender Figure 32: C# Test Sender

6 Contents Figure 33: PHP Test Sender Figure 34: Receiving a Send Routing Info For SM Figure 35: Receiving a Ready For SM Figure 36: Receiving a Report SM Delivery Figure 37: Receiving a Location Request Figure 38: Receiving a subscriber state Request Figure 39: Transmitting a Alert Service Centre Figure 40: Receiving a Get IMSI Request

7 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 1 Introduction The Dialogic DSI Signaling Interface for Web-Services (SWS) allows access to SS7 and SIGTRAN signaling functionality via the use of a set of webservices high-level APIs. This document focuses on defining the APIs, offering information about developing new applications and providing details of the sample applications that are used to show the API being implemented. 1.1 Signaling Service Support The services supported are focused on three areas: Short Messaging (SMS) This provides the ability to send SMS messages to mobile devices based on the mobile number with a simple API call. It enables SMS advertisements, SMS information services and many other types of services. The API also supports the reception of SMS messages to enable SMS voting applications or activation of other services via SMS. The normal SMS API call will both perform a routing look-up and send the SMS. If the user requires further control of the separate parts of this procedure then a set of 'atomic' API calls are available to support this. Unstructured Supplementary Service Data (USSD) The Unstructured Supplementary Service Data (USSD) function is part of the GSM mobile specifications and permits arbitrary data to be sent and received by compatible mobile devices for such services as mobile top-up menus and information retrieval (e.g., what is the mobile device's number). The API supports both mobile-originated sessions and application-initiated sessions. Location Based services The SWS allows the application to request the location of a mobile station using the MSISDN number via mobile network access. of the mobile station will be returned in the response, giving its longitude and latitude. 1.2 Feature Overview High Level Application API simplified interface Lowers SS7 / GSM MAP protocol knowledge required Focuses on enabling common services to mobile devices XML / HTTP Web Service API Client systems not restricted in language/os support Wide range of tool support 1.3 Abbreviations ANSI American National Standards Institute 7

8 1 Introduction GPRS ITU-T MAP MTP REST SCCP SMS SWS TCAP TP USSD WS General Packet Radio Service International Telecommunication Union (formerly CCITT) Mobile Application Part Message Transfer Part Representational State Transfer Signaling Connection Control Part Short Message Service Dialogic DSI Signaling Interface for Web-Services Transaction Capabilities Application Part Transfer Protocol Unstructured Supplementary Service Data Web-service 1.4 Related Information Refer to the following for related information: Dialogic DSI Signaling Servers SS7G41 Operators Manual Dialogic DSI Signaling Servers SS7G41 Hardware Manual Dialogic DSI Components Software Environment Programmer s Manual The following manual(s) should be read depending on the protocol options installed on the server: SCCP Programmer s Manual TCAP Programmer s Manual MAP Programmer s Manual SCTP Programmer s Manual M3UA Programmer s Manual M2PA Programmer s Manual MAP GSM specifications 3GPP TS GPP TS GPP This manual is applicable to SS7G41 with SWS Mode Release or later. 8

9 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 2 SWS Mode Overview 2.1 Architecture Overview The Dialogic DSI Signaling Server for Web-Services (SWS) allows client applications to offer services which make use of SMS, USSD and location functionality. The SWS unit connects into SS7 or SIGTRAN networks and provides APIs to allow one or more instance of a client application to control this functionality. The SS7 configuration parameters are specified in a text file contained within each SWS. A complete system requires, in addition to the SWS unit, at least one active client application. The client applications communicate with the SWS using a web-service interface. For a description of the client applicator development APIs. Refer to section 3 Web Services APIs. 9

10 2 SWS Mode Overview Signaling Topologies A single SWS may be used standalone, or two units may be configured in a dual resilient configuration. Each SWS may support one or more application (host) computers. The host computer contains the physical resources controlled by the signaling, such as voice circuits and databases. The SWS extracts SS7 information and conveys it to the application software, which can control the resource accordingly and issue the required responses to the SWS for transport over the SS7 network. The minimal system consists of a single SWS connected to a single host via Ethernet as illustrated below. Dashed lines indicate optional equipment. Figure 1: Single SWS 10

11 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 This system may be scaled up at initial system build time or later to a dual resilient configuration connected to the maximum number of hosts supported. See the figure below: Figure 2: Signaling Paths in a Dual Resilient Configuration The SWS may connect to a number of adjacent signaling points, the maximum number being limited only by the maximum number of link sets supported by the unit. The adjacent SS7 nodes may be Signaling Transfer Points (STPs), Signaling Switching Points (SSPs) or Signaling Control Points (SCPs). The following diagrams indicate possible configurations, although these are not exhaustive. The figure below shows a single SWS connected to an adjacent SSP/SCP and/or STP. Figure 3: Single SWS Connected to SSP/SCP or STP In a dual resilient configuration, the SWS pair share the same SS7 point code. The figure below shows an SWS pair connected to a single adjacent SSP/SCP. 11

12 2 SWS Mode Overview Figure 4: SWS Dual Configuration with Connections to SSP/SCP The SWS pair may also be connected to a single adjacent STP (or combination of SSP and STP) as shown below: Figure 5: SWS Dual Configuration with Connections to STP The figure below shows an SWS pair connected to a mated STP pair. In this configuration, all the links from the first STP must be terminated at SWSA and all the links from the second STP must be terminated at SWSB. 12

13 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 Figure 6: SWS Dual Configuration with Connections to Mated STP Pair 2.2 Multiple Network Support The SS7 Network Context together with a signaling point code uniquely identifies an SS7 node by indicating the specific SS7 network it belongs to. The Network Context may be a unique identifier for a physical SS7 network, for example, to identify an ANSI, ITU, International or National network, or it may be used to subdivide a physical SS7 network into logical sub-networks. The Signaling Server supports up to four Network Contexts where each Network Context is a different network or different independent local point code within the same network. Selection of which Network context to use is made when configuring an SWS Profile. In the configuration commands or MMI commands, Network Contexts are designated NC0, NC1, NC2 or NC Protocol Handling for Multiple Network Contexts The figure below shows the use of multiple Network Contexts from an application perspective and provides examples of the module IDs for the various application layers. 13

14 2 SWS Mode Overview Figure 7: Module IDs for Use with Multiple Network Contexts 14

15 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Inter-SWS Communications In a dual resilient configuration (one unit nominated as SWSA, the other as SWSB), two physically independent communication channels exist between the two units. Control information is exchanged over the Ethernet. Signaling messages are exchanged (when necessary) over an inter-sws SS7 link set, which must be configured for correct dual resilient operation. The preferred route for messages transmitted from an SWS is over the links connecting that unit to the appropriate adjacent point code (a point code that is either the final destination or a route to the final destination). If no signaling link to an appropriate adjacent point code is available, the transmit traffic is passed to the other SWS via the inter-sws link set. If the inter-sws link set fails, transmit messages fall back to being passed over the Ethernet. If the inter-sws link set fails (causing the Ethernet link to be used for transmitted messages), message loss may occur at the point where the preferred route fails. The SS7 network is free to deliver received messages to either SWS. Special processing at the User Part level ensures that any message received for a call or transaction being handled by the other unit is routed over the Ethernet. The inter-sws link set is configured in the same manner as normal link sets, for details, refer to Configuration in the Dialogic DSI Signaling Servers SS7G41 Operators Manual. The inter-sws link set may consist of one or more signaling links configured on one or more signaling ports (T1/E1), distributed between one or more signaling boards. Resilience on the Inter SWS link set may be achieved by configuring two links in the inter-sws link set, each on a separate signaling board. The inter-sws link may also be conveyed over M2PA or M3UA avoiding the requirement for a TDM link and cabling between the units Transaction-Based Applications Applications that need to exchange non-circuit related information over the SS7 network (such as for the control of a Mobile Telephone Network or for an Intelligent Network application) do so by exchanging information between sub-systems using the services of SCCP. A sub-system is an entity that exchanges data with other entities by using SCCP. The SWS provides the capability to configure local sub-systems and routing to remote resources. The intelligent functionality of each local sub-system is provided by the user application running on one or more host computers Management of Local SCCP Sub-Systems The SWS system automatically brings local SCCP sub-systems into service, no application interaction is required. 15

16 2 SWS Mode Overview Alarms The Dialogic DSI Signaling Server products are able to detect a number of events or alarm conditions relating to either the hardware or the operation of the protocols. Each alarm condition is assigned a severity/class (3=Critical, 4=Major, 5=Minor) and a category and ID, which give more detail about the alarm. There are a number of mechanisms described below, by which these conditions can be communicated to management systems, and ultimately to the system operator. See Alarm Listing in the Dialogic DSI Signaling Servers SS7G41 Operators Manual for a list of alarm types, and their reporting parameters. Active alarms are indicated on the front panel of the Signaling Server with three LEDs identifying severity; CRT, MJR, MNR. Active alarms may be indicated remotely from the Signaling Server when the alarm relay outputs are connected to a remote management system. Alarm events (occurrence and clearing, class, category and ID) may be reported via Management messages to the host application thus permitting remote monitoring and/or logging. Alarm events may be reported to an SNMP manager. SNMP support is described in SNMP in the Dialogic DSI Signaling Servers SS7G41 Operators Manual. A system operator can obtain a listing of the current alarm status (CLA, CATEGORY, ID and TITLE) using the ALLIP management terminal command described in ALLIP in the Dialogic DSI Signaling Servers SS7G41 Operators Manual. Test Critical, Major, or Minor may be activated using the ALTEI management command and cleared using the ALTEE management command. 2.3 Interfaces The SWS offers a number of interfaces, which are described below: 16

17 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 Application Manager Web Services Application Management Terminal (MMI) Web Browser App OA&M Web Services APP API Telnet OA&M Dialogic DSI Signaling Interface for Web Services Figure 8: Interfaces Application Interface This interface allows client systems to make use of the high-level servicespecific API to simplify access to signaling services in the mobile network. This is done via a web-service API, as detailed Web Services APIs Configuration Interface The SWS can configure many aspects of system operation and signaling functionality. Such configuration is performed for the SS7 stack via a static configuration file on the SWS system. The control of the high-level API and API service specific functionality is provided via a Web-services based interface, which can be controlled in a browser. 17

18 2 SWS Mode Overview Note: System configuration ins described in detail in the Dialogic DSI Signaling Servers SS7G41 Operators Manual Management Interface, Trace, and Diagnostics The SWS can provide tracing and diagnostic information from modules in the system. This can include tracing at different levels of the protocol stack. The Man-Machine Interface (MMI) can also be used to provide status and statistics from the system. Tracing of the Web-service API can be achieved via tools such as Wireshark run on the client system Network Interfaces Internal to the SWS system, the high-level API makes use of other layers of the SS7 stack such as MAP, TCAP and SCCP. The SWS will also connect to the signaling network via the TDM SS7 MTP3 module or SIGTRAN modules such as M3UA or M2PA. 18

19 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 3 Web Services APIs 3.1 Overview The web-services interface uses HTTP with an XML payload using a REST architecture. This makes it suitable for implementation on a large number of client systems using different OSs, languages and frameworks. The diagram below shows an example usage of the SWS with the network elements and message flow. 1 2 MSC/VLR BSS Mobile Client Application 8 DSI SWS HLR Network A 5 6 MSC/VLR Mobile BSS HLR Network B Figure 9. Sending an SMS (Network Diagram) 1 SMS Request (HTTP PUT) 2 Send Routing Info for SM Request 3 Routing Response 4, 5 Forward Short Message (MT) 6, 7 Forward Short Message Response (MT) 8 SMS Response (HTTP PUT Response 204 No Content) 19

20 3 Web Services APIs 3.2 Summary Supported URIs / Methods All URIs are preceded by the domain and root /dialogicwebservice/signaling or /dialogicwebservice/signaling/profile/<profile_name> (only the initial message should contain the profile). See Section 7 - Profiles and Multiple Network Support for further details on profile support. If the profile resource is absent then this is equivalent as using the profile for the service with ID that matches 0. URL Method Action /<msisdn>/sms PUT Requests an SMS be transmitted /<msisdn>/sms POST Requests an SMS be transmitted and maintain a dialog open for further SMS to the same mobile. /<msisdn>/sms/<sessionid> PUT Continuation of an SMS to be transmitted /sms GET Receive new SMS /sms/<sessionid> GET Continuation of receiving an SMS /<msisdn>/smsmo PUT Requests a mobile originated SMS be transmitted /smsmp GET Receive a new mobile originated SMS /<msisdn>/location GET Requests location information /ussd POST Requests setup of a new application initiated USSD session and a session id is returned. /ussd GET Receive new mobile initiated USSD session. A session id is returned. /ussd PUT Sends USSD data to mobile without creating a session using a USSD Notify /ussd/<sessionid> PUT Sends data, response contains user reply /ussd/<sessionid > DELETE Ends or aborts a session /<msisdn>/sriforsm GET Requests a Send Routing Info For Short Message to be transmitted /alertsc GET Requests a new service centre alert /<msisdn>/readyforsm PUT Requests a new Ready For SM to be transmitted /<msisdn>/smsmt PUT Requests an atomic mobile terminated SMS to be transmitted /<msisdn>/reportsmdeliver PUT Requests a report SM Deliver to be transmitted All others ANY Return Status 404: Not Found 20

21 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 Example: To send an SMS to the mobile number , call an HTTP PUT with the URI: To send an SMS to the mobile number using profile TX_SMS_0, call an HTTP PUT with the URI: /sms Note: The MSISDN should include the country code but should not include a + or other leading dial prefix Payload Structure The payload is XML encoded with the following general form. This includes a version identifier used to aid compatibility between schema versions. The encoding scheme expected in requests and used by the SWS is UTF-8. <?xml version="1.0" encoding= UTF-8?> <primitive_type version= n > <parameter1> </parameter1> <parameter2> </parameter2> </primitive_type> HTTP Response Codes The following set of HTTP response codes are used Response Code HTTP Meaning Used when 200 OK Request was processed successfully; the result of the request is contained within the XML body of the response 201 Created Session created 204 No Content Request was successful; no additional content required 400 Bad Request The request could not be parsed 401 Unauthorized A required authentication method was not used 403 Forbidden Invalid resource requested 404 Not Found An invalid method was requested 500 Internal Server Error The requested method could not be performed due to an error detected at the server 504 Gateway Timeout Service timed-out at the server 21

22 3 Web Services APIs 3.3 MAP Services Used The SWS system makes use of a number of GSM MAP Services implemented in the underlying SS7/SIGTRAN stack. The table below summarizes these services used. API Call Method MAP Services Used /<msisdn>/sms PUT SendRoutingInfoForSM ForwardSM ReportSMDelivery Notes ReportSMDelivery is only sent if configured. /<msisdn>/sms POST SendRoutingInfoForSM ForwardSM /<msisdn>/sms/<sessionid> PUT ForwardSM ReportSMDelivery ReportSMDelivery is only sent if configured. /sms GET ForwardSM /sms/<sessionid> GET ForwardSM /<msisdn>/smsmo PUT ForwardSM MO /smsmo GET ForwardSM MO /<msisdn>/location GET AnyTime Interrogation /ussd POST USSD Request /ussd GET ProcessUnstructred USSD Request /ussd PUT USSD Notify /ussd/<sessionid> PUT USSD Request / Notify /ussd/<sessionid > DELETE TCAP-End /<msisdn>/sriforsm GET SendRoutingInfoForSM InformSC InformSC is processed if received from the network in response to the send routing info request /alertsc GET AlertSerivceCentre /<msisdn>/readyforsm PUT ReadyForSM NoteSubscriberPresent ReadyForSM is sent by default, but if configured NoteSubscriberPresent can be sent instead (Version 1 Operation) /<msisdn>/smsmt PUT ForwardSM /<msisdn>/reportsmdeliver PUT ReportSMDelivery 22

23 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 4 Short Message API The SMS API has two methods, one for permitting the transmission of an SMS message to a mobile device and the second for reception of a message by the SWS system. URL Method Action /<msisdn>/sms PUT Requests an SMS be transmitted /<msisdn>/sms POST Requests an SMS be transmitted and maintain a dialog open for further SMS to the same mobile. /<msisdn>/sms/<sessionid> PUT Continuation of an SMS to be transmitted /sms GET Receive new SMS /sms/<sessionid> GET Continuation of receiving an SMS /<msisdn>/smsmo PUT Requests a mobile originated SMS be transmitted /smsmp GET Receive a new mobile originated SMS /<msisdn>/sriforsm GET Requests a Send Routing Info For Short Message to be transmitted /alertsc GET Requests a new service centre alert /<msisdn>/readyforsm PUT Requests a new Ready For SM to be transmitted /<msisdn>/smsmt PUT Requests an atomic mobile terminated SMS to be transmitted /<msisdn>/reportsmdeliver PUT Requests a report SM Deliver to be transmitted 4.1 Sending an SMS To send an SMS message to a mobile device use the mobile number in the URI and an HTTP PUT as shown in Figure 10: Sending an SMS (Full Message Flow without Report SM Delivery): 23

24 4 Short Message API Client SWS HLR VLR/MSC Mobile PUT Send Routing Info for SM Send Routing Infor for SM - Reponse Foward Short Message Forward Short Message - Reponse Figure 10: Sending an SMS (Full Message Flow without Report SM Delivery) When sending the SMS in step 1, the payload XML should have the form shown below. See Chapter 10, XSD Files for the supporting XSD schema. MT-FORWARD-SHORT-MESSAGE-TX-REQ <?xml version="1.0" encoding="utf-8"?> <! - Example SMS sent --> <sms version="1"> <message encodingscheme="0" language="en-gb">hello</message> <dest noa="1" np="1"> </dest> <orig noa="1" np="1"> </orig> </sms> In the response there will be an appropriate response code, as shown in section HTTP Response Codes. Note: The 204 No Content response code is the expected response to a successfully sent SMS message. If the error code is returned, it will take the following form: 24

25 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 <?xml version="1.0" encoding="utf-8"?> <!-- Example Error Code --> <error> <code type= MapUserError >SystemFailure</code> <text>tx-mo-sms(fsm) System Failure</text> </error> Support for Report SM Delivery It is possible to set the SWS system to send an automatic report SM Delivery to the HLR via the configuration option Automatic ReportSMDelivery on the Web MMI. This optional can be found under System Administration -> MAP Services -> SMS -> Configuration. It can also be set using the equivalent MMI command MASMS and the RDEL parameter. Client SWS HLR VLR/MSC Mobile PUT Send Routing Info for SM Send Routing Infor for SM - Reponse Foward Short Message Forward Short Message - Reponse Report SM Delivery OK Report SM Delivery - Reponse Figure 11: Sending an SMS (Full Message Flow with Report SM Delivery) 25

26 4 Short Message API 4.2 Receiving an SMS To collect the next outstanding SMS message received by the SWS use a HTTP GET with a URI of the form as shown below in Figure 12: Receiving an SMS HTTP GET Client SWS Mobile GET OK Forward Short Message Foward Short Message - Response Figure 12: Receiving an SMS The response should include a 200 OK for success. In other cases an appropriate response code will be used as shown in section HTTP Response Codes. The returned response will have XML payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example SMS received --> <sms version="1"> <message">goodbye</message> <orig ton="international" np="isdn"> </orig> <imsi> </imsi> </sms> Alternatively an HTTP response code, error codes and text will be returned. 26

27 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Sending a binary format SMS In order to support services requiring more control over the SMS and the format it is sent in the API also supports direct control over the SMS-Deliver short message transfer protocol data unit as defined in the GSM specifications such as 3GPP TS version Release 9. In order to send using this format the message element should be replaced with the smsdeliver element. This element is a compound parameter made up of the TP sub-parameters defined to match those in the SMS Deliver structure in the GSM specifications. The TP-UD parameter contains the Unit Data of the SMS encoded as Base 64. The other elements of the smsdeliver element control the formatting and additional data relating to the SMS payload. An example of this format is shown below. These elements are specified in more detail in section <?xml version="1.0" encoding="utf-8"?> <sms version="1"> <dest ton="subscriber" npi="isdn"> </dest> <smsdeliver> <mms>false</mms> <rp>false</rp> <udhi>false</udhi> <udl>57</udl> <sri>true</sri> <dcs>0</dcs> <pid>4</pid> <scts>eubgahfyaa==</scts> <ud>zle83aal4fn6g0r+s99y0dxnb4xbztolnh675+uxvuyvy0fhchqenqfhafczv Gan6S4=</ud> </smsdeliver> </sms> 27

28 4 Short Message API 4.4 Receiving a binary format SMS The SWS can also receive messages in a binary SMS format. The SMS Service Options section of the SMS Configuration Tab of the web management interface contains a control which selects the handling of nonsimple text SMS. The control has the following meaning Receive only SMS text: All SMS which can be returned using the simple message format will be sent in that format. All other SMS will be sent as binary SMS format. Receive SMS network headers All SMS will be returned as binary format using the smsdeliver element. The parameters and meanings are the same as for the sending of binary format SMS. <?xml version="1.0" encoding="utf-8"?> <sms version="1"> <orig ton="international" npi="isdn"> /orig> <imsi> </imsi> <smsdeliver> <mms>false</mms> <rp>false</rp> <udhi>false</udhi> <udl>57</udl> <sri>true</sri> <dcs>0</dcs> <pid>4</pid> <scts>eubgahjlaa==</scts> <ud>zle83aal4fn6g0r+s99y0dxnb4xbztolnh675+uxvuyvy0fhchqenqfhafczv Gan6S4=</ud> </smsdeliver> </sms> 28

29 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Sending a concatenated binary format SMS Figure 13: Sending a concatenated SMS In order to send a user concatenated message the user must be making use of the binary message format as discussed in section 4.3. In order to request additional messages to be sent in the same dialog the client application should set the mms (More Messages to Sent) parameter to true. When the SWS responds to the initial SMS being sent it will then include a session identifier which can be used to link later SMS requests to the first. The last message in the dialog should be sent with the mms parameter set to false. The URIs used for a two concatenated SMS would be as follows: HTTP POST HTTP PUT sionid> For example: 29

30 4 Short Message API HTTP POST ms HTTP PUT ms/5 Note: The MMS (More Messages to Send) field in the SMS-Deliver TP parameter takes the value of 1 in the encoded message sent over the SS7 link or SIGTRAN association if there are no more messages to send. A value of 0 indicates there are more messages to send. The SWS API uses a value of true when there are more messages and false when there are no more messages to send. 4.6 Receiving a concatenated binary format SMS Client SWS Mobile GET (sms) OK GET (sms/<sessionid>) Forward Short Message (More Messages) Foward Short Message - Response OK Forward Short Message (No More Messages) Foward Short Message - Response Figure 14: Receiving a concatenated SMS Receiving a concatenated SMS takes a similar approach to that of sending a concatenated SMS in that a session id is returned in order to allow related concatenated SMS to be returned together and collected from the SWS. The URIs used for receiving two concatenated SMS would be as follows: HTTP GET HTTP GET For example: 30

31 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 HTTP GET HTTP GET Mobile Originated SMS Transmitting or Receiving Mobile Originated SMS must be performed using the binary format (see sections 4.3 and 4.4). In order to send a mobile originated SMS the user must use the SMS-Submit short message transfer protocol data unit as defined in the GSM specifications such as 3GPP TS version Release 9. The following is an example of this format. These elements are specified in more detail in Section 8.1 SMS Service. Example HTTP PUT msmo <?xml version="1.0" encoding="utf-8"?> <sms version="1"> <orig ton="international" npi="isdn"> /orig> <msc ton="international" npi="isdn"> /msc> <destsrvctr ton="unknown" npi="isdn"> /destsrvctr> <dest ton="international" npi="isdn"> /dest> <smssubmit> <rd>false</rd> <rp>false</rp> <udhi>false</udhi> <udl>57</udl> <srr>true</srr> <mr>2</mr> <dcs>0</dcs> <pid>4</pid> <tprel>20</tprel> <ud>zle83aal4fn6g0r+s99y0dxnb4xbztolnh675+uxvuyvy0fhchqenqfhafczv Gan6S4=</ud> </smssubmit> </sms> 31

32 4 Short Message API Receiving an MO-SMS is similar to receiving a binary message as discussed in section 4.4 Receiving a binary format SMS. HTTP GET <?xml version="1.0" encoding="utf-8"?> <sms version="1"> <orig ton="international" npi="isdn"> /orig> <msc ton="international" npi="isdn"> /msc> <destsrvctr ton="unknown" npi="isdn"> /destsrvctr> <dest ton="international" npi="isdn"> /dest> <smssubmit> <rd>false</rd> <rp>false</rp> <udhi>false</udhi> <udl>57</udl> <srr>true</srr> <mr>2</mr> <dcs>0</dcs> <pid>4</pid> <tprel>20</tprel> <ud>zle83aal4fn6g0r+s99y0dxnb4xbztolnh675+uxvuyvy0fhchqenqfhafczv Gan6S4=</ud> </smssubmi 4.8 Sending Atomic MT-SMS To send an SMS message to a mobile device use the mobile number in the URI and an HTTP PUT as shown below in Figure 15: Transmitting an Atomic MT-SMS: 32

33 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 Client SWS HLR VLR/MSC Mobile PUT Foward Short Message OK Forward Short Message - Reponse Figure 15: Transmitting an Atomic MT-SMS HTTP PUT msmt The payload XML should have the form shown below. See Appendix A.1 for the supporting XSD schema. MT-FORWARD-SHORT-MESSAGE-TX-REQ <?xml version="1.0" encoding="utf-8"?> <! - Example SMS sent --> <smsmt version="1"> <message>hello</message> <imsi> </imsi> <msc ton="international" np="isdn"> </msc> <orig ton="international" np="isdn"> </orig> </smsmt> In the response there will be an appropriate response code, as shown in section The 204 No Content response code is the expected response to a successfully sent SMS message. If an error response code is returned, it will have payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example Error Code --> <error> <code type= MapUserError >SystemFailure</code> <text>error Text</text> </error> 33

34 4 Short Message API 4.9 Sending a binary format Atomic MT-SMS In order to send a user concatenated message the user must be making use of the binary message format as discussed in section 4.3. An example of this format is shown below. These elements are specified in more detail in section <?xml version="1.0" encoding="utf-8"?> <smsmt version="1"> <imsi> </imsi> <msc ton="international" np="isdn"> </msc> <smsdeliver> <mms>false</mms> <rp>false</rp> <udhi>false</udhi> <udl>57</udl> <sri>true</sri> <dcs>0</dcs> <pid>4</pid> <scts>eubgahfyaa==</scts> <ud>zle83aal4fn6g0r+s99y0dxnb4xbztolnh675+uxvuyvy0fhchqenqfhafczv Gan6S4=</ud> </smsdeliver> </sms> 34

35 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Sending Concatenated Atomic MT-SMS Client SWS HLR VLR/MSC Mobile POST (smsmt) Foward Short Message OK Forward Short Message - Reponse PUT (smsmt/sessionid) Foward Short Message OK Forward Short Message - Reponse Figure 16: Transmitting a Concatenated atomic MT-SMS In order to send a user concatenated message the user must be making use of the binary message format as discussed in section 4.3. In order to request additional messages to be sent in the same dialog the client application should set the mms (More Messages to Sent) parameter to true. When the SWS responds to the initial SMS being sent it will then include a session identifier which can be used to link later SMS requests to the first. The last message in the dialog should be sent with the mms parameter set to false. The URIs used for a two concatenated SMS would be as follows: HTTP POST HTTP PUT essionid> 35

36 4 Short Message API For example: HTTP POST msmt HTTP PUT msmt/ Sending Atomic Send Routing Info For SM A client can request that a Send Routing Info For SM be used sent to the HLR. This uses a HTTP PUT request and similar XML payload to the other SMS APIs. See the Figure 27: Sending a USSD Notify below: Client SWS HLR PUT Send Routing Info for SM OK Send Routing Infor for SM - Reponse Figure 17: Transmitting a Send Routing Info For SM HTTP PUT rsm The payload is optional depending on whether the default Type of Number or the Numbering Plan needs to be overridden or any optional fields are required, if so then the XML should have the form shown below. See Appendix A.1 for the supporting XSD schema. SEND-ROUTING-FOR-SM-TX-REQ <?xml version="1.0" encoding="utf-8"?> <! - Example SRI sent --> <sriforsm version="1"> <msisdn ton="international" np="isdn"> </msisdn> </sriforsm > The response should include a 200 OK for success. In other cases an appropriate response code will be used as shown in section

37 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 The returned response will have XML payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example SMS received --> <sriforsm version="1"> <imsi> </imsi> <msc ton="international" np="isdn"> </msc> </sriforsm> 4.12 Sending Atomic Report SM Delivery A client can request that to transmit a Report SM Delivery to be used sent to the HLR. This uses a HTTP PUT request and similar XML payload to the other SMS APIs. See the Figure 27: Sending a USSD Notify below: Client SWS HLR PUT Report SM Delivery OK Report SM Delivery - Response Figure 18: Transmitting a Report SM Delivery HTTP PUT tsmdeliver The payload is required and the XML should have the form shown below. See Appendix A.1 for the supporting XSD schema. 37

38 4 Short Message API REPORT-SM-DELVIER-TX-REQ <?xml version="1.0" encoding="utf-8"?> <! - Example SRI sent --> <reportsmdeliver version="1"> <msisdn ton="international" np="isdn"> </msisdn> <deliveryoutcome>successfultransfer</deliveryoutcome> </reportsmdeliver> The 204 No Content response code is the expected response to a successfully sent Report SM Delivery message, unless the HLR returns a Stored MSISDN in which case a 200-OK will be returned containing the MSISDN. If an error response code is returned, it will have payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example Error Code --> <error> <code type= MapUserError >SystemFailure</code> <text>error Text</text> </error> 4.13 Sending Atomic Ready For SM A client can request that to transmit a Ready For SM (Note Subscriber Present MAP Version 1) to be used sent to the HLR. This uses a HTTP PUT request and similar XML payload to the other SMS APIs. See the Figure 27: Sending a USSD Notify below: Client SWS HLR PUT Ready For Sm OK Ready For Sm - Response Figure 19: Transmitting a Ready For SM The payload is required and the XML should have the form shown below. See Appendix A.1 for the supporting XSD schema. 38

39 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 READY-FOR-SM-TX-REQ <?xml version="1.0" encoding="utf-8"?> <! - Example SRI sent --> <readyforsm version="1"> <imsi> </imsi> <alertreason>mspresent</alertreason> <hlraddr ton="international" np="isdn"> </ hlraddr > </readyforsm> The 204 No Content response code is the expected response to a successfully sent Report SM Delivery message. If an error response code is returned, it will have payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example Error Code --> <error> <code type= MapUserError >SystemFailure</code> <text>error Text</text> </error> 4.14 Receiving Atomic Send Routing Info For SM A client can request to receive a Send Routing Info For SM. This uses a HTTP GET request to receive the request, to respond to the request the HTTP Put request is used Client SWS SMSC GET OK Send Routing Info for SM PUT Send Routing Info for SM - Response OK 39

40 4 Short Message API Figure 20: Receiving a Send Routing Info For SM HTTP GET This will retrieve the first available Send Routing Info For SM, there is no payload associated with the initial request The response should include a 200 OK for success. In other cases an appropriate response code will be used as shown in section The returned response will have XML payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example SMS received --> <sriforsm version="1"> <msisdn ton="international" np="isdn"> </msisdn> <sessionid>4</sessionid> </sriforsm> The Client then should return the response to the Send Routing Info request using a PUT request and specifying the sessionid that the request is associated with. HTTP PUT If the request is successfully acknowledged then a payload containing the required data shall be included with the HTTP request The returned response will have XML payload of the following form: <?xml version="1.0" encoding="utf-8"?> <!-- Example SMS received --> <sriforsm version="1"> <imsi> </imsi> <msc ton="international" np="isdn"> </msc> <sessionid>4</sessionid? </sriforsm> If the request is negatively acknowledged then the payload will contain the relevant error code 40

41 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 <?xml version="1.0" encoding="utf-8"?> <!-- Example Error Code --> <error> <code type= MapUserError >SystemFailure</code> <text>error Text</text> </error> 4.15 Receiving an Alert Service Centre SWS for alert service centre can be configured in the following options: MAN - The Client will request alert service centre requests from the network. If no requests are received then an error is returned to the HLR AUTO - SWS will automatically send back the successful response to the Alert Service Centre Request from the HLR with no interaction from the user. ABORT - SWS will automatically abort all Alert Service Centre Requests from the HLR. The message sequence below shows the Auto mode. Figure 21: Receiving Alert Service in Auto Mode The message sequence below shows the Abort mode. 41

42 4 Short Message API Figure 22: Receiving Alert Service in Abort Mode In the Manual Mode the user must request an Alert Service Centre from the HLR using the HTTP GET request. The 200-OK will contain the contains of the Alert Service Centre request received from the HLR and will acknowledge the Alert Service Centre request back to the HLR. The Manual Mode is shown in the figure below: Figure 23: Receiving an Alert Service Request in Manual Mode The response should include a 200 OK for success. In other cases an appropriate response code will be used as shown Section HTTP Response Codes. The returned response will have XML payload of the following form: 42

43 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 <?xml version="1.0" encoding="utf-8"?> <!-- Example SMS received --> <alertsc version="1"> <msisdn ton="international" np="isdn"> </orig> </alertsc> 43

44 5 USSD API 5 USSD API This API allows USSD sessions to be locally initiated or initiated by the mobile device. URL Method Action /ussd POST Requests setup of a new application initiated USSD session and send data to the mobile /ussd GET Receives new ussd session. A session id is returned /ussd PUT Sends USSD data to mobile without creating a session using a USSD Notify /ussd/<sessionid> PUT Sends data, response contains user reply /ussd/<sessionid > GET Receives data /ussd/<sessionid > DELETE Ends session 5.1 Mobile Initiated Sessions Figure 24: Mobile Originated USSD session below shows a Mobile Originated USSD session: Client Application SWS Mobile GET OK Process USSD Request PUT USSD Request OK USSD Request - Result PUT + Close Indicator Process USSD Request - Result No Content Figure 24: Mobile Originated USSD session A client requests the next outstanding new mobile initiated session by calling GET on /ussd. 44

45 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 HTTP GET <?xml version="1.0" encoding="utf-8"?> <ussd version="1"> <msisdn> </msisdn> <alertingpattern>1</alertingpattern> <ussdstring datacodingscheme="1">text Here</ussdString> <sessionid> </sessionid> </ussd> A session id is returned. Subsequent data sent to that mobile for the same session uses PUT on /ussd/<sessionid> HTTP PUT The response to the PUT contains the response from the mobile device. Data can be sent back and forth using further PUT and PUT responses. The session is ended by using the close indication in the PUT. A DELETE can be used to force the session to end at any time. HTTP DELETE 45

46 5 USSD API 5.2 Client Application Initiated Session The figure below shows an Application Originated USSD session (Figure 25: Application Originated USSD session): Client SWS Mobile POST USSD Request Created or OK USSD Request - Result PUT USSD Request OK USSD Request - Result DELETE No Content END Figure 25: Application Originated USSD session A client should request the start of a new client application initiated session by calling POST on /ussd. HTTP POST A session id will be returned together with the response from the mobile device. Subsequent data sent to that mobile for the same session uses PUT on /ussd/<sessionid> 46

47 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 The figure below shows an Application Originated USSD session (Figure 26: Application Originated USSD session with USSD Notify): Client SWS Mobile POST USSD Request Created or OK USSD Request - Result PUT (Notify) USSD Notify OK USSD Notify Response DELETE No Content END : Figure 26: Application Originated USSD session with USSD Notify This session is similar to the previous example but is ended by a USSD Notify. A client requests a Notify by setting a Notify element in the XML payload sent. HTTP PUT Client Application Initiated - USSD Notify A client can request that a USSD Notification be used to send data to a mobile. This uses a HTTP PUT request and similar XML payload to the other USSD APIs. See the Figure 27: Sending a USSD Notify below: Client SWS Mobile PUT USSD Notify OK USSD Notify Response 47

48 5 USSD API Figure 27: Sending a USSD Notify HTTP PUT As a session does not need to be maintained, a session id is not required. 48

49 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 6 Location and Subscriber Polling API 6.1 Location API All URIs are precluded by the domain and root /dialogicwebservices/signaling URL Method Action /<msisdn>/location GET Requests location information Figure 28: Requesting a mobile location below shows a client requesting a mobile location: Client SWS Mobile GET ATI - Request OK ATI - Response Figure 28: Requesting a mobile location A client requests the location of the mobile device by calling GET on /<msisdn>/location. HTTP GET The XML payload returned will include the longitude and latitude. <?xml version="1.0" encoding="utf-8"?> <!-- --> <location version="1"> <msisdn ton="international" np="isdn> </msisdn> <latitude> </latitude> <longitude> </longitude> </location> 49

50 6 Location and Subscriber Polling API 6.2 Subscriber State API All URIs are precluded by the domain and root /dialogicwebservices/signaling URL Method Action /<msisdn>/subscriberstate GET Requests subscriber state information Figure 29: Requesting a mobile subscriber state below shows a client requesting a mobile subscriber state: Client SWS Mobile GET ATI - Request OK ATI - Response Figure 29: Requesting a mobile subscriber state A client requests the location of the mobile device by calling GET on /<msisdn>/subscriberstate. HTTP GET e The XML payload returned will include the current subscriber state <?xml version="1.0" encoding="utf-8"?> <!-- --> <subscriberstate version="1"> <state state="assumedidle"/> </subscriberstate> 50

51 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Get IMSI API All URIs are precluded by the domain and root /dialogicwebservices/signaling URL Method Action /<msisdn>/getimsi GET Requests imsi from the HLR The figure below shows the Client requesting the IMSI from the HLR using the MSISDN of the mobile (Figure 29: Requesting a mobile subscriber state Client SWS HLR GET Send IMSI - Request OK Send IMSI - Response Figure 30: Requesting the IMSI from the HLR A client requests the imsi of the mobile device by calling GET on /<msisdn>/getimsi. HTTP GET timsi The XML payload returned will include the imsi of the mobile station <?xml version="1.0" encoding="utf-8"?> <!-- --> <getimsi version="1"> <imsi> </imsi> </getimsi> 51

52 7 Profiles and Multiple Network Support 7 Profiles and Multiple Network Support 7.1 Introduction to Profiles Profiles are used across the SWS Web Service API to select specific information required to send network traffic or create criteria for receiving network requests. It is possible to have up to 100 profiles in total for all services. The creation of profiles is performed using the Web or Command line MMI. 7.2 Transmit Profiles Profiles allow the user to specify information that will be used in outbound network requests. This information will include the GT address that initiates the request (SCCP calling party number), the network context and specific service information (such as default numbering plans). The user on creating a request can specify the profile that will be used to generate the network request. Types of transmit profiles:- Tx MT-SMS services using this profile include o o o o Combined MT-SMS Atomic Send Routing Info for SM Atomic MT-SMS Atomic Report SM Delivery Tx MO-SMS services using this profile include o MO-SMS requests Ready For SM services using this profile include o Ready for SM Requests USSD services using this profile include o USSD Subscriber - services using this profile include o o o Location Service Get Subscriber State Get IMSI HLR Tx services using this profile include o Alert Service Centre 52

53 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Receive Profiles Profiles used for the reception of data, the received data from the network must match the criteria specified in the profile for it to match. This information will normally include the Service Centre Address that the network request was sent to. When a user requests to receive data matching a profile, only requests that match the requirements will be returned to the user. A user can create profiles that can receive all network requests for a particular service for the same network context or for all network contexts. If an incoming network requests matches a specific profile completely and also a generalized profile then it can only be received using the specific profile. Types of receive profiles:- Rx MT-SMS services using this profile include o Rx Atomic MT-SMS Tx MO-SMS services using this profile include o o Rx MO-SMS Rx Alert Service Centre USSD services using this profile include o USSD Mobile Initiated HLR RX services using this profile include o o o o o o Rx Location Request Rx Subscriber Request Rx Get IMSI Rx Send Routing Info for SM Rx Report SM Delivery Status Rx Ready For SM 53

54 8 Parameter Reference 8 Parameter Reference The following sections indicate the parameters used by each service and their respective meanings. The Group values in the tables have the following meaning: Group T C E A Meaning Top level element structure in XML payload Compound XML element with sub-elements XML Element Attribute of the indicated element The Req and Rsp values in the tables have the following meaning: Req/Rsp M O C Meaning Parameter is mandatory Parameter is optional Parameter is conditionally required. The conditions under which it is needed are indicated. All of the three services (SMS, Location and USSD) may return error indications stored in an Error XML payload, as defined in section SMS Service Parameter Group Req Rsp Details Sms T M M Top level element for SMS request/responses Version A O O Attribute of sms Set to 1 Dest E O n/a Destination Mobile Subscriber ISDN Number Identifies the mobile number of the device that the SMS is to be sent. Ton A O O Attribute of dest Type of number Npi A O O Attribute of dest Numbering Plan Indicator Imsi E n/a M International Mobile Subscriber Identity The IMSI Is a unique identifier of the SIM in the mobile device. Message E O C 1 UTF-8 Encoded text string Orig E O O Origination Mobile Subscriber ISDN Number Identifies the mobile number of the device from which the SMS is sent from. Ton A O O Attribute of orig Type of number Npi A O O Attribute of orig Numbering Plan Indicator 54

55 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 sessionid E M for existing session O Identifies the sms session being handled. This is returned in the first response to a GET or PUT where multiple concatenated messages are required to be sent or received smsdeliver E C 1 O Compound parameter with sub-elements shown in section SMS Deliver parameters. This used to specify SMS messages which cannot be supported by the simple message format, for example binary or concatenated messages. Note 1 - Either message or smsdeliver should be present SMS Deliver parameters Parameter Group Req Rsp Details mms E M M TP-MMS flag as specified in Boolean, true means more messages are to send. rp E M M TP-RP flag as specified in Boolean, true means Reply path exists udhi E M M TP-UDHI flag as specified in Boolean, true means TP-UD contains a header sri E M M TP-SRI flag as specified in Boolean, true means a status report is requested pid E M M TP-PID as specified in Protocol Identifier Value between representing the protocol used. dcs E M M TP-DCS as specified in Data coding scheme Value between representing the protocol used. scts E M M TP-SCTS as specified in This is the service centre time stamp encoded as Base64. udl E M M TP-UDL as specified in This is the length of the unit data parameter specified in ud E M M TP-UD as specified in If the ud parameter is encoded in GSM 7-bit default alphabet then this represents the number of septets used. If the ud parameter is encoded in GSM 7-bit default alphabet AND the udhi is set the then this represents the number of septets used in the user data header plus the user data field. If the ud parameter is encoded using 8-bit data then the udl should indicate the number of octets used. If the ud parameter is encoded using 8-bit data and the udhi is set then the udl should indicate the number of octets used in the header plus the user data field. Contains the SMS user data encoded as Base64 55

56 8 Parameter Reference 8.2 Atomic SMS-MT Service Parameter Group Req Rsp Details smsmt T M M Top level element for SMS-MT request/responses version A O O Attribute of sms Set to 1 msc E O n/a Mobile Switching Centre ISDN Number Identifies the MSC that the destination mobile is currently located on. yon A O O Attribute of msc Type of number npi A O O Attribute of msc Numbering Plan Indicator imsi E n/a M International Mobile Subscriber Identity The IMSI Is a unique identifier of the SIM in the mobile device. Message E O C 1 UTF-8 Encoded text string Orig E O O Origination Mobile Subscriber ISDN Number Identifies the mobile number of the device from which the SMS is sent from. Ton A O O Attribute of orig Type of number Npi A O O Attribute oforig Numbering Plan Indicator sessionid E M for existing session O Identifies the sms session being handled. This is returned in the first response to a GET or PUT where multiple concatenated messages are required to be sent or received smsdeliver E C 1 O Compound parameter with sub-elements shown in section SMS Deliver parameters. This used to specify SMS messages which cannot be supported by the simple message format, for example binary or concatenated messages. Note 1 - Either message or smsdeliver should be present 8.3 MO-SMS Service Parameter Group Req Rsp Details SmsMo T M M Top level element for SMS-MO request/responses Version A O O Attribute of sms Set to 1 Dest E O M Destination Mobile Subscriber ISDN Number Identifies the destination mobile address for the SMS Ton A O O Attribute of dest Type of number Npi A O O Attribute of dest Numbering Plan Indicator orig E O M Origination Mobile Subscriber ISDN Number Identifies the originating mobile address of the SMS 56

57 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 ton A O O Attribute of orig Type of number npi A O O Attribute of orig Numbering Plan Indicator destsrvctr E M O SMS Service Centre that SMS is to be sent to ton A O O Attribute of destsrvctr Type of number npi A O O Attribute of destsrvctr Numbering Plan Indicator Msc E M O MSC ISDN Number ton A O O Attribute of msc The MSC Address that the SMS-MO originated from Type of number npi A O O Attribute of msc Numbering Plan Indicator smssubmit E C 1 O Compound parameter with sub-elements shown in section SMS Submit parameters. This used to specify SMS messages which cannot be supported by the simple message format, for example binary or concatenated messages. Note 1 - Either message or smsdeliver should be present SMS Submit parameters Parameter Group Req Rsp Details rd E M M TP-Reject-Duplicates flag as specified in Boolean, true means reject duplicates is set. rp E M M TP-RP flag as specified in Boolean, true means Reply path exists udhi E M M TP-UDHI flag as specified in Boolean, true means TP-UD contains a header srr E M M TP-Status-Report-Request flag as specified in Boolean, true means a status report is requested pid E M M TP-PID as specified in Protocol Identifier Value between representing the protocol used. dcs E M M TP-DCS as specified in Data coding scheme Value between representing the protocol used. mr E M M TP-Message-Reference as specified in Value between vprel E O O TP-Validity-Period (Relative Format) as specified in Value between vpabs E O O TP-Validity-Period (Absolute Format) as specified in Base 64 encoded. 57

58 8 Parameter Reference vpenc E O O TP-Validity-Period (Absolute Format) as specified in Base 64 encoded. udl E M M TP-UDL as specified in This is the length of the unit data parameter specified in ud E M M TP-UD as specified in If the ud parameter is encoded in GSM 7-bit default alphabet then this represents the number of septets used. If the ud parameter is encoded in GSM 7-bit default alphabet AND the udhi is set the then this represents the number of septets used in the user data header plus the user data field. If the ud parameter is encoded using 8-bit data then the udl should indicate the number of octets used. If the ud parameter is encoded using 8-bit data and the udhi is set then the udl should indicate the number of octets used in the header plus the user data field. Contains the SMS user data encoded as Base Alert Service Centre Service Parameter Group Req Rsp Details AlertSC T M M Top level element for AlertSC request/responses Version A O O Attribute of sms Set to 1 msisdn E n/a M Mobile Subscriber ISDN Number Identifies the mobile address received in the alert Service Centre ton A n/a O Attribute of msisdn Type of number npi A n/a O Attribute of msisdn Numbering Plan Indicator 8.5 Send Routing Info For SM Service Parameter Group Req Rsp Details AlertSC T M M Top level element for Send Routing Info For SM request/responses Version A O O Attribute of sriforsm Set to 1 msisdn E M n/a Mobile Subscriber ISDN Number ton A O n/a Attribute of msisdn Identifies the mobile address that the routing information is required for Type of number npi A O n/a Attribute of msisdn Numbering Plan Indicator SmRpPri E O n/a Indicates whether SMS delivery will be attempted even when a service centre address is contained in the Message Waiting Data file in the HLR Specified in

59 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 gprssupportindicator E O n/a If the SMS-GMSC supports of receiving two numbers for HLR Specified in For future expansion smrpmti E O n/a RP-Message Type Indicator of the Short Message Specified in smrpsmea E O n/a Originating SME-Address of the Short Message Entity Specified in ton A O n/a Attribute of smrpsmea Type of number npi A O n/a Attribute of smrpsmea Numbering Plan Indicator smdeliverynotintended E O n/a This parameter indicates whether the delivery of a short message is not intended. Specified in msc E n/a M Mobile Switching Centre ISDN Number ton A n/a M Attribute of smrpsmea MSC address that the terminating mobile is located at Type of number npi A n/a M Attribute of smrpsmea Numbering Plan Indicator imsi E n/a O International Mobile Subscriber Identity The IMSI Is a unique identifier of the SIM in the mobile device. lmsi E n/a O Mobile local identity specified by residing VLR gprsnodeindicator E n/a O Present if SGSN is the primary location of the mobile. Reserved for future expansion sgsnnum E n/a O SGSN Address for GPRS Mobiles. Reserved for future expansion ton A n/a M Attribute of sgsnnum Type of number npi A n/a M Attribute of sgsnnum Numbering Plan Indicator informsc E n/a O Compound parameter with sub-elements shown in section Inform Service Centre parameters. This used to specify contents received in the optional Inform Service Centre Inform Service Centre parameters Parameter Group Req Rsp Details storedmsisdn E n/a O MSISDN stored in the HLR of the requested mobile ton A n/a M Attribute of storedmsisdn Type of number npi A n/a M Attribute of storedmsisdn Numbering Plan Indicator 59

60 8 Parameter Reference mnrf E n/a O Mobile Station Not Reachable flag if present mcef E n/a O Memory Capacity Exceeded flag if present mnrg E n/a O Mobile Station Not Reachable for GPRS flag if present Reserved for future expansion srvctrsetinhlr E n/a O Service Centre already set in the HLR absentsubdiagsm E n/a O The reason that the subscriber is absent Values specified addabsentsubdiagsm E n/a O The reason that the subscriber is absent for GPRS Values specified Reserved for future expansion 8.6 Report SM Delivery Status Service Parameter Group Req Rsp Details reportsmdeliver T M M Top level element for Report SM Delivery request/responses bersion A O O Attribute of sms Set to 1 msisdn E M n/a Mobile Subscriber ISDN Number ton A O n/a Attribute of msisdn Identifies the mobile address received in the alert Service Centre Type of number npi A O n/a Attribute of msisdn Numbering Plan Indicator deliveryoutcome E M n/a Indicates the status of the mobile terminated SM delivery absentsubdiagsm E O n/a Absent subscriber Diagnostic Values specified gprssupportind E O n/a GPRS Support Ind, SMS-GMSC supports handling of two delivery Outcomes gprsdeliveryoutcome E O n/a Indicates the status of the mobile terminated SM delivery for GPRS gprsabsentsubdiagsm E O n/a Absent subscriber Diagnostic for GPRS Values specified imssupportind E O n/a IMS Support Ind, SMS-GMSC supports handling of two delivery Outcomes imsdeliveryoutcome E O n/a Indicates the status of the mobile terminated SM delivery for IMS imsabsentsubdiagsm E O n/a Absent subscriber Diagnostic for IMS Values specified storedmsisdn E n/a O MSISDN stored in the HLR of the requested mobile Ton A n/a O Attribute of storedmsisdn Type of number Npi A n/a O Attribute of storedmsisdn Numbering Plan Indicator 60

61 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue USSD Service Parameter Group Req Rsp Details Ussd T M M Top level element for USSD request/responses Version A O O Attribute of ussd Set to 1 alertingpattern E O O Optional parameter to set a network specific alerting indication. Values are a single character representing a single byte value. Close E C 2 C 2 Set element to indicate a request to close session. For example, in a PUT request, that should close the session on completion. This prevents the need for an unnecessary DELETE request. Msisdn E M for new session M for new session Mobile Subscriber ISDN Number Identifies the mobile number of the device being located. Ton A O M Attribute of msisdn Type of Number Npi A O M Attribute of msisdn Numbering Plan Indicator sessionid E O M for existing session Identifies the ussd session being handled. Typically this is returned in the first response to a GET on /ussd. Timeout E n/a n/a For future use. ussdstring E M M 3 Represents the text send or received in a USSD message Imsi E n/a C4 International Mobile Subscriber Identity The IMSI Is a unique identifier of the SIM in the mobile device. datacodingscheme A O O USSD coding scheme to be used as defined in the CBD Data Scheme in 3GPP Values supported: 0-15 Default Alphabet with Language 16,17 Default Alphabet/UCS2 64, 65, 66 General Data Coding Notify E O O Sends a USSD Notify to the network instead of a USSD Request Note 2 Required to request a session to be closed after processing action. Will be present in responses to indicate session has been closed. Note 3 Passed up if available. Note 4 If a USSD-REQ or USSD-NOT is requested from the API is the first message in a session and the ussdstring is greater than 166 characters then the SWS send two messages. The first will perform the dialogue initiation before transmitting the USSD string in a later message. This is to permit the longer string to fit into an MSU size limit of 272 characters allowing for the GT addresses (including MSISDN) are of the maximum size. 61

62 8 Parameter Reference 8.8 Location Service Parameter Group Req Rsp Details location T M M Top level element for location responses version A n/a O Attribute of location Set to 1 latitude E n/a O Location latitude position in real valued degrees (-180 to +180) longitude E n/a O Location longitude position in real valued degrees (-90 to +90) msisdn E n/a O Mobile Subscriber ISDN Number ton A n/a O Attribute of msisdn Identifies the mobile number of the device being located. Type of Number npi A n/a O Attribute of msisdn Numbering Plan Indicator cellid C n/a O Cell Id of the location geodeticinformation C n/a O Location returned in the geodetic format geographicalinfomationgprs C n/a O Location returned in the geographical format for a GPRS enabled phone geographicalinformation C n/a O Location returned in the geographical format Cell Id Parameters Parameter Group Req Rsp Details mcc E M n/a Mobile Country Code as specified in section mnc E M n/a Mobile Network Code as specified in section lac E M n/a Location Area Code as specified in section ci E O n/a Cell Identity as specified in section

63 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Subscriber State Service Parameter Group Req Rsp Details SubscriberState T M M Top level element for location responses Version A n/a O Attribute of location Set to 1 Msisdn E M n/a Mobile Subscriber ISDN Number Identifies the mobile number of the device being located. State E n/a M Subscriber State of the Mobile Subscriber state A n/a M Subscriber state Not Reachable E n/a O Not reachable reason for the mobile subscriber 63

64 8 Parameter Reference 8.10 Get IMSI Service Parameter Group Req Rsp Details GetImsi T M M Top level element for Get IMSI responses Version A n/a O Attribute of location Set to 1 Msisdn E M n/a Mobile Subscriber ISDN Number Identifies the mobile number of the device being located. Imsi E n/a M International Mobile Subscriber Identity The IMSI Is a unique identifier of the SIM in the mobile device. 64

65 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue Error Parameter Group Rsp Details error T M Top level element for error information Contains details of error code A M Error code type A M Attribute of the error code, defines the group of error codes (e.g. MAP User Error or Internal System Error text E M Contains details of error Error Code Types Error Code Types internalfailure mapusererror usererror mapprovidererror nodatawaiting absmandparam invalidsession invalidparamlen servnotsupported sessionterminated localtimeout parseerror Error Code Type internalfailurecodetype Error Code noresources invalidgctfmt insufficientrpnd Error Code Type maperrorcodetype Error Code unknownsubscriber 65

66 8 Parameter Reference unknownmsc unidentifiedsubscriber absentsubscribersm unknownequipment roamingnotallowed illegalsubscriber bearerservicenotprovisioned teleservicenotprovisioned illegalequipment callbarred forwardingviolation cugreject illegalssoperation sserrorstatus ssnotavailable sssubscriptionviolation ssincompatibility facilitynotsupported ongoinggroupcall nohandovernumberavailable subsequenthandoverfailure absentsubscriber incompatibleterminal shorttermdenial longtermdenial subscriberbusyformtsms smdeliveryfailure messagewaitinglistfull systemfailure datamissing unexpecteddatavalue pwregistrationfailure negativepwcheck noroamingnumberavailable tracingbufferfull targetcelloutsidegroupcallarea numberofpwattemptsviolation numberchanged 66

67 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 busysubscriber nosubscriberreply forwardingfailed ornotallowed atinotallowed nogroupcallnumberavailable resourcelimitation unauthorizedrequestingnetwork unauthorizedlcsclient positionmethodfailure unknownorunreachablelcsclient mmeventnotsupported atsinotallowed atmnotallowed informationnotavailable unknownalphabet ussdbusy Unknown Error Code Type usererrorcodetype Error Code appidabsent appidinvalid appnotactive invalidstate Error Code Type providererrorcodetype Error Code appidabsent appidinvalid appnotactive invalidstate MAP User Errors Error Code Unknown Subscriber Unknown MSC 67

68 8 Parameter Reference Error Code Unidentified Subscriber Absent Subscriber SM Unknown Equipment Roaming Not Allowed Illegal Subscriber Bearer Service Not Provisioned Teleservice Not Provisioned Illegal Equipment Call Barred Forwarding Violation CUG_Reject Illegal SS Operation SS Error Status SS Not Available SS Subscription Violation SS Incompatibility Facility Not Supported PW Registration Failure Negative PW Check NO Handover Number Available Subsequent Handover Failure Absent Subscriber Subscriber Busy for MT SMS SM Delivery Failure message_waiting_list_full system_failure data_missing unexpected_data_value resource_limitation initiating_release no_roaming_number_available tracing_buffer_full number_of_pw_attempts_violation number_changed busy_subscriber no_subscriber_reply forwarding_failed 68

69 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 Error Code or_not_allowed ATI_not_allowed unauthorised_requesting_network unauthorised_lcs_client position_method_failure unknown_or_unreachable_lcs_client mm_event_not_supported atsi_not_allowed atm_not_allowed information_not_available unknown_alphabet ussd_busy 69

70 9 Application Development Guidelines 9 Application Development Guidelines 9.1 Application Development Frameworks The web-services APIs make use of HTTP with XML payloads and are constructed to follow RESTful principals. This allows many different development environments and frameworks to be used. The following environments have been used to create the example applications: Language Java Development Environment NetBeans 6.9 IDE C# Microsoft Visual Studio 2005 PHP Various Other development environments are available and should provide facilities suitable for use with the SWS APIs. 9.2 XML Handling In order to support auto-generated handling and validation of XML, supporting XSD schema files are provided (See Appendix A.1). This schema can be used with supporting XML handling libraries such as JAXB in Java. 9.3 HTTP/HTTPS The URIs and port numbers used in this document assume use of HTTP for the RESTful interface running at the default port number of 81. The port numbers for HTTP and HTTPS are configurable. Please verify that the correct values are being used on the specific system. A secure API connection to the SWS system can be created by enabling SSL. This will mean a corresponding change to the URIs and Port numbers used. When enabled, the default port for the RESTful interface over HTTPS is 442. The method by which SSL/HTTPS is enabled and certificates accepted is system and platform dependent. 9.4 Use of Expect: HTTP 100 Continue The SWS platform does not respond to requests requiring HTTP 100 Continue responses. The default behavior of some web-service frameworks (e.g. C#/.NET) may be to expect the 100 Continue response. The use of the HTTP 100 Continue is inefficient and inappropriate for the APIs being used. This should be disabled for correct behavior. For example: HttpWebRequest request = WebRequest.Create(uri) as HttpWebRequest; request.servicepoint.expect100continue = false; 70

71 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue 4 10 Application Examples A number of example applications are available for different environments to show different aspects of the system and provide different sets of test functionality Java SWS Test Utility The SMS test sender application makes use of the Jersey API support for RESTful web-services in Java. It also makes use of the JAXB support for conversion of data to and from XML based on the supplied XSD schema files. The user interface makes use of the Swing framework (Figure 31: Java SMS Test Sender). Figure 31: Java SMS Test Sender The application can be used by entering the server IP address, destination number and message to send. The Advanced tab allows the encoding scheme, type of number and numbering plan identifier settings to be changed if necessary. 71

72 10 Application Examples 10.2 C# SWS Example Application This application makes use of a simple GUI and C# components to allow testing of the API with an SWS server and is shown in Figure 32: C# Test Sender. Figure 32: C# Test Sender 72

73 Dialogic DSI SS7G41 Signaling Server SWS Developers Manual Issue PHP Example A simple application written in PHP. It gives an example of a scripted language and is shown below in Figure 33: PHP Test Sender. Figure 33: PHP Test Sender 73