SMS/MMS Business Numbers

Transcription

Third Party Interface Manual
Swisscom (Schweiz) AG
CH-3050 Bern
3
Version 4.0
22. June 2015
1/79
Table of Content
1 Introduction .....................................................................................................................................................5
1.1 Summary ................................................................................................................................................................................................. 5
1.2 Scope ........................................................................................................................................................................................................ 5
1.3 Target Readership............................................................................................................................................................................... 5
1.4 Abbreviations ....................................................................................................................................................................................... 5
1.5 Terminology .......................................................................................................................................................................................... 6
1.6 Additional Documents ..................................................................................................................................................................... 6
1.7 Contact Information ......................................................................................................................................................................... 8
1.8 Third Party Interface Manual Release Management.......................................................................................................... 8
2 Service Types ................................................................................................................................................. 10
2.1 Introduction ........................................................................................................................................................................................10
2.1.1 Deliver Service.................................................................................................................................................................................10
2.1.2 Submit Service ...............................................................................................................................................................................10
2.1.3 Services Free of charge ...............................................................................................................................................................11
2.2 Individual Order ................................................................................................................................................................................11
2.2.1 Individual Order via SMS/MMS..............................................................................................................................................11
2.2.1.1 General ..........................................................................................................................................................................................11
2.2.1.2 Process ..........................................................................................................................................................................................12
2.2.2 Individual Order via Mobile Internet...................................................................................................................................13
2.2.2.1 General .........................................................................................................................................................................................13
2.2.2.2 Process .........................................................................................................................................................................................13
2.2.3 Individual Order via Internet ..................................................................................................................................................14
2.2.3.1 General .........................................................................................................................................................................................14
2.2.3.2 Process .........................................................................................................................................................................................14
2.3 Subscription Service ........................................................................................................................................................................15
2.3.1 Subscription Service via SMS/MMS .....................................................................................................................................15
2.3.1.1 How to subscribe to a service via SMS/MMS ...............................................................................................................15
2.3.1.2 Process ..........................................................................................................................................................................................17
2.3.1.3 How to unsubscribe a service via SMS/MMS ..............................................................................................................17
2.3.1.4 How to unsubscribe all services via SMS/MMS (of one Short ID) ......................................................................18
2.3.1.5 Summary Subscription Keywords ....................................................................................................................................18
2.3.2 Subscription Service via Mobile Internet ..........................................................................................................................19
2.3.2.1 How to subscribe to a service via Mobile Internet ....................................................................................................20
2.3.2.2 Process .........................................................................................................................................................................................20
2.3.2.3 How to unsubscribe via Mobile Internet ......................................................................................................................20
2.3.3 Subscription Service via Internet ..........................................................................................................................................21
2.3.3.1 How to subscribe to a service via Internet....................................................................................................................21
2.3.3.2 Process .........................................................................................................................................................................................21
2.3.3.3 How to unsubscribe via Internet ......................................................................................................................................22
2.4 SMS Competitions ...........................................................................................................................................................................22
2.5 Chat Services ......................................................................................................................................................................................22
2.5.1 General ..............................................................................................................................................................................................22
CH-3050 Bern
3
Version 4.0
22. June 2015
2/79
2.5.2 Process ..............................................................................................................................................................................................23
2.6 Packages/Bundles ............................................................................................................................................................................24
2.7 Service Billing .....................................................................................................................................................................................24
2.8 Wap Push Services and SMS with URL ...................................................................................................................................24
2.9 Itemized Bill and Billing Text ......................................................................................................................................................25
2.9.1 Itemized Bill ....................................................................................................................................................................................25
2.9.2 Billing Text ......................................................................................................................................................................................25
2.10 Service Info ........................................................................................................................................................................................26
2.10.1 Summary Service Information .............................................................................................................................................26
2.11 Enabling Platform Generated Info ..........................................................................................................................................27
2.12 Wrong Keyword ..............................................................................................................................................................................27
2.13 Endcustomerauthenticationandauthorization ...............................................................................................................28
3 Technical Concept ......................................................................................................................................... 29
3.1 General Overview .............................................................................................................................................................................29
3.2 Functional Overview .......................................................................................................................................................................29
4 Third Party Interfaces (TPI) ........................................................................................................................... 30
4.1 Overview ...............................................................................................................................................................................................30
4.2 Technical Overview .........................................................................................................................................................................32
4.3 SMS Services .......................................................................................................................................................................................33
4.3.1 SMS Deliver (MB  Third Party) ............................................................................................................................................33
4.3.1.1 SMS Deliver Request (MB  Third Party).......................................................................................................................33
4.3.1.2 SMS Deliver Response (Third Party  MB) ...................................................................................................................35
4.3.1.3 Example in case of SMS Deliver: .......................................................................................................................................38
4.3.2 SMS Submit (Third Party  MB) ...........................................................................................................................................39
4.3.2.1 SMS Submit Request (Third Party  MB) .....................................................................................................................39
4.3.2.2 SMS Submit Response (MB  TP) ...................................................................................................................................42
4.3.2.3 Example JAXM Submit (send an object, WSDL is not needed) ...........................................................................45
4.3.3 SMS Delivery Report (Delivery Notifications) ..................................................................................................................47
4.3.4 Binary Message (only for Nokia Handset) ........................................................................................................................51
4.3.5 Binary SMS (for Handsets which supports EMS) ...........................................................................................................51
4.3.5.1 EMS Message .............................................................................................................................................................................51
4.3.5.2 Unicode encoded SMS ..........................................................................................................................................................53
4.4 MMS Services .....................................................................................................................................................................................54
4.4.1 MMS Deliver (MB  Third Party) ..........................................................................................................................................54
4.4.1.1 MMS Deliver Request (MB  Third Party) .....................................................................................................................54
4.4.1.2 MMS Deliver Response (Third Party  MB) .................................................................................................................57
4.4.1.3 Example in case of MMS Deliver:......................................................................................................................................58
4.4.2 MMS Submit (Third Party  MB) .........................................................................................................................................60
4.4.2.1 MMS Submit Request (Third Party  MB) ...................................................................................................................61
4.4.2.2 MMS Submit Response (MB  Third Party)................................................................................................................63
4.4.2.3 Example JAXM Submit (send an Object, WSDL is not needed) ..........................................................................67
4.4.3 MMS Delivery Reports (Delivery Notifications) ..............................................................................................................70
4.5 API Documentation .........................................................................................................................................................................72
CH-3050 Bern
3
Version 4.0
22. June 2015
3/79
4.5.1 Assumption .....................................................................................................................................................................................72
4.5.2 Installation......................................................................................................................................................................................72
4.5.3 Submit Requests ..........................................................................................................................................................................72
4.5.3.1 SMS Submit Request ..............................................................................................................................................................72
4.5.3.2 MMS Submit Request............................................................................................................................................................73
4.5.4 Deliver Request .............................................................................................................................................................................74
4.5.5 Reports..............................................................................................................................................................................................75
4.6 TPI Developer Documentation ...................................................................................................................................................75
4.6.1 Submit Requests ...........................................................................................................................................................................76
4.6.1.1 SMS Submit Request ...............................................................................................................................................................76
4.6.1.2 MMS Submit Request ............................................................................................................................................................77
4.6.2 Report Servlet ................................................................................................................................................................................77
4.6.3 Deliver Request .............................................................................................................................................................................78
4.6.4 Dispatcher .......................................................................................................................................................................................78
4.6.5 MB-TPI Archive Structure .........................................................................................................................................................79
4.7 Simple Object Access Protocol (SOAP) ....................................................................................................................................81
4.7.1 Overview...........................................................................................................................................................................................81
4.7.2 SOAP Functionality .....................................................................................................................................................................81
4.8 MMS Content.....................................................................................................................................................................................83
4.8.1 Multimedia Message within SOAP (MIME Types) .........................................................................................................83
4.8.2 Transcoding....................................................................................................................................................................................83
CH-3050 Bern
3
Version 4.0
22. June 2015
4/79
1
Introduction
1.1 Summary
Swisscom enables end customers to send dedicated service requests to a Third Party via SMS or MMS. The
Third Party is granted access to the Business Numbers Enabling Platform to deliver the requested service.
This allows the Third Party to send and receive SMS and MMS messages to and from Swisscom customers
(including partners/MVNOs). Where applicable, the end customer can choose between one-time use (single/pull service) and repeated use (packets and subscriptions/push service) of the service. The service is activated by sending an SMS/MMS message with a keyword and, where applicable, additional information to a
specified short number (Short ID). The service can also be ordered via the Third Party’s internet site. A detailed description of the service logic is provided in this technical manual.
1.2 Scope
MMS/SMS Business Numbers offers an interface to Third Parties to the mobile and billing network of
Swisscom. This interface is provided by a system called the Enabling Platform.
This document describes the MMS and SMS service types, the billing concept, and the Enabling Platform interface to the Third Party. A common understanding of the service types is essential to provide a consistency
to the end customer who might not be aware who offers her or him the service. Billing rules are defined to
establish cooperation between the Third Parties and Swisscom customer. Finally the technical description
provides the basis to build up new SMS and MMS services by a Third Party.
1.3 Target Readership




Third Party product managers
Third Party technical staff
Swisscom product managers
Swisscom technical staff
1.4 Abbreviations
CUC
EMS
GSM
IMEI
IrDA
ISO
MB
MIME
MMS
MMSC
Customer Care
Enhanced Message Service
Global System for Mobile communications
International Mobile Equipment Identity
Infrared Data Association
International Standards Organization
Message Broker
Multipurpose Internet Mail Extensions
Multimedia Message Service
Multimedia Message Service Center
CH-3050 Bern
3
Version 4.0
22. June 2015
5/79
MO
MSISDN
MT
MVNO
SIS
SMS
SMSC
SOAP
TAC
TP
TPI
UCP
UDH
WAP
WWW
Mobile Originating
Mobile Station ISDN number
Mobile Terminating
Mobile Virtual Network Operator
Subscriber Information Server
Short Message Service
Short Message Service Center
Simple Object Access Protocol
Type Approval Code
Third Party
Third Party Interface
Universal Computer Protocol
User Data Header
Wireless Apllication Protocol
World Wide Web
1.5 Terminology
Third Party
Short ID
Keyword
Swisscom business customer, connecting to the Enabling Plattform
Short code known to the end customer (MSISDN of a SMS or MMS service)
Trigger element send by the end customer in the text field of an SMS to a Short ID in
order to get the information. In MMS case, text in the subject field is used as keyword.
1.6 Additional Documents
[1]
Java documentation http://java.sun.com/
[2]
Perl Regular Expression Tutorial: http://www.english.uga.edu/humcomp/perl/regex2a.html#2
[3]
Code of conduct: http://www.swisscom.ch/iservclient
[4]
Unicode standard: http://www.unicode.org/
[5]
SOAP / SMIL standard: http://www.w3.org/
[6]
MIME Types: http://www.iana.org/assignments/media-types/
[7]
Enabling Platform Package (MB_TPI_x.x-bxx.zip): http://www.swisscom.ch/iservclient
[8]
Supported MIME types: see Vertragsanhang
[9]
Java JAXM description: http://java.sun.com/xml/jaxm/index.jsp
[10]
MMS_Content_Guidelines_V1.pdf http://www.swisscom.ch/iservclient
[11]
Axis 1.4 http://ws.apache.org/axis/
[12]
Castor Framework http://www.castor.org
[13]
TPI Reference Implementation http://www.swisscom.ch/iservclient
CH-3050 Bern
3
Version 4.0
22. June 2015
6/79
1.7 Contact Information
For administrative questions please contact Swisscom Provider Support:




Phone: 0800 848 900
Fax: +41 (0)31 939 88 43
Email: Provider.Support@swisscom.com
Address:
Name Ihrer Kontaktperson
Enterprise Customers
Waldeggstrasse 51
3050 Bern
For technical support please contact Swisscom Partner Integration:


Email: Partnerintegration@swisscom.com
Internet: www.swisscom.ch/iservclient
Swisscom Helpline:

Phone: 00800 5560 5560 or +4158 262 02 00
1.8 Third Party Interface Manual Release Management
The table summarizes the major differences in this document due to a new document release.
Version
Chapter
2.0
2.1
SMS and MMS
Version based on Message Broker (MB) Version 1.0
Error Messages updated, Example updated, Chapter 3 updated
SMS and MMS
SMS and MMS
SMS and MMS
SMS and MMS
SMS and MMS
Examples adapted, small changes over all
Small changes over all
New traces and examples, small changes over all
Text in service description added
Content definition (SMS Deliver)
Updated Billrates
Diameter Interface Error codes added
SMS and MMS
Delivery Notifications
Updated Billrates
TP should analyze Delivery Notifications for proper statistics
2.8
all
3, 5.2.3.2 and
5.3.2.3
5
all
all
3.1.1
5.2.1.1
3.6
5.2.3.2.1
5.3.2.3.2
3.6
5.2.4
5.3.3
5.2.3 and 5.2.5
SMS
If Nokia Binary Port is used, IsText has also to be set
3.0
3.1
All chapters
4.3.3
SMS and MMS
SMS
General document review and adaptation
Error Messages and Reason Codes from SMSC in Delivery Notifications
added
2.2
2.3
2.4
2.5
2.6
2.7
CH-3050 Bern
3
Description
Version 4.0
22. June 2015
7/79
3.2
2
4.3.3
SMS and MMS
SMS
3.3
2.3.3.1
SMS and MMS
Stop sservices via ”STOP ALL” and not like until now with “STOP”
Error Messages and Reason Codes from SMSC in Delivery Notifications and
service billing added
Adaptation of chapter "Subscription Service via Internet"
3.4
2.3.3.1
MMS
MMS Bulk phase out
3.5
all
SMS and MMS
MWST (Tax Rate) changed from 0.0 / 2.4 / 7.6 to 0.0 / 2.5 / 8.0
3.6
SMS and MMS
Changing / adapt service descriptions
Adding service description for SMS competitions
3.7
2.1.2
2.1.3
2.2.2.2
2.3.2.2
2.4
2.2.3.2
SMS and MMS
Subscription via Internet
3.8
1.7
SMS and MMS
New Hotline number
3.9
3.1
SMS and MMS
Using short id for adult content, http 1.1 standard
4.0
2.12
SMS keyword
Advertising text in the error message of invalid keywords are not allowed
4.3.1.1
SMS Deliver
4.3.3
SMS Deliver Report
SMS Deliver Report: Diameter error removed (they are now within Submit
Response)
4.4.1.1
MMS Deliver
TPI parameter balance-check added, Encrypted MSISDN removed
New SMS/MMS Deliver and Submit Traces added which fits with new MBS
CH-3050 Bern
3
Version 4.0
22. June 2015
8/79
2
Service Types
2.1
Introduction
There are two main service types, Deliver (In) and Submit (Out). In case of a deliver service the initiator (end
customer) is sending a SMS/MMS to a Short ID. In case of a submit service it’s the Third Party which sends a
SMS/MMS towards the end customer. The Third Party has all possibilities to combine Submit and Deliver as
well as SMS and MMS
2.1.1
Deliver Service
The Enabling Platform receives a SMS/MMS and forwards it via the TPI interface (deliver request) to the
Third Party. Afterwards the requested answer is supplied by the Third Party via the TPI interface (submit request).
Enabling
Platform
End Customer
Third Party
Figure 1: Deliver Service
2.1.2
Submit Service
Premium content is supplied by a Third Party via the TPI interface (submit request). The Enabling Platform
generates a SMS/MMS and sends it to the end customer. At the same time a billing record is created so that
the premium service can be charged. A Submit service is therefore used in the case the Third Party initiates
the process.
For billing reasons the Third Party must sent the keyword (service information, e.g. NEWS, PICTURE) in the
billing text field of the reply message to the Enabling Platform.
CH-3050 Bern
3
Version 4.0
22. June 2015
9/79
Enabling
Platform
End Customer
Third Party
Billing System
Figure 2: Submit Service
SMS subscription services may only be sent and invoiced by the Short ID where the end customer has a
(double) opt-in. The transfer of an opt-in and with it the MSISDN customer base of a Short ID to another is
not permitted.
2.1.3
Services Free of charge
Services advertised as "free" or "at no charge" must also be provided free of charge to the end customer.
Merely supplying the first image/video or the first week of service free of charge is not permitted.
2.2
Individual Order
2.2.1
Individual Order via SMS/MMS
2.2.1.1 General
An end customer sends a SMS/MMS to a defined short ID. The text field of the SMS (In case of a MMS, the
text in the subject field is used) contains the keyword (e.g. NEWS) related to the service and defined by the
Third Party. The Enabling Platform receives the SMS/MMS and forwards it via the TPI interface (Deliver Request) to the Third Party. Afterwards the requested answer is supplied by the Third Party via the TPI interface
(Submit Request). The Submit Request includes the content as well as the charging information equal to the
advertised price.
Should the price of an individual order exceed CHF 10, the end customer may only be
charged for this service if, subsequently to placing the initial order, he has expressly stated
that he accepts the offering (this is also known as a “double opt-in”, in accordance with Art.
11a of the Federal Ordinance on the Disclosure of Prices PBV)
Each request from an end customer must receive an appropriate response from the Third Party. This applies
to both invalid and valid keywords (This rule counts for all service types described in this manual).
CH-3050 Bern
3
Version 4.0
22. June 2015
10/79
2.2.1.2 Process
1.
(
( 1b.
1a.
)
)
2.
End Customer
Third Party
Figure 3: Process Individual Order via SMS/MMS
1.
End customer is triggering an order via SMS/MMS (e.g. GAME A)
1a. End customer receives a request for confirmation with additional indication of price and/or age query
required for erotic content via SMS/MMS. This step is absolutely necessary if the price is higher than
CHF 10 and/or confirmation of age must be given for erotic services. Communication must be clear and
the price must always be given first, then an additional confirmation of age request may be made. The
confirmation of age request must not be misused in any way to conceal the price.
1b. End customer confirms acceptance of the price and/or gives confirmation of age via SMS/MMS (e.g.
YES)
2.
Delivery of content and charging (If the download is provided by WAP Push in an intermediate stage,
the charge SMS/MMS can only be triggered once the download has been successfully completed).
CH-3050 Bern
3
Version 4.0
22. June 2015
11/79
2.2.2
Individual Order via Mobile Internet
2.2.2.1 General
We would generally recommend that this is carried out using our Easypay product. Should this not be possible for reasons of transparency (Sunrise and Orange), we allow the process set out to be used, provided the
order is triggered by the customer via SMS/MMS.
An end customer sends a SMS/MMS to a defined short ID. The text field of the SMS/MMS contains the keyword (e.g. NEWS) related to the service and defined by the Third Party. The Enabling Platform receives the
SMS/MMS and forwards it via the TPI interface (Deliver Request) to the Third Party. Afterwards the requested answer is supplied by the Third Party via the TPI interface (Submit Request). The Submit Request includes
the link to a mobile portal, where the end customer can download the requested information. The Third Party sends a SMS/MMS including the charging information equal to the advertised price after download.
2.2.2.2 Process
1.
2.
3.
4.
End Customer
Third Party
Figure 4: Process Individual Order via Mobile Internet
1. End customer is triggering an order via SMS/MMS (e.g. GAME A)
2. The end customer receives a SMS/MMS with a link on a mobile portal.
3. Charges may only be made after the consumer has received the information in accordance with
point 2. and expressly confirmed (“YES”, “OK”, “START” etc) acceptance of the offer on his or her mobile terminal. (PBV Art. 11.a5)
4. Third Party sends a SMS/MMS including the charging information after confirmation and successful
download.
CH-3050 Bern
3
Version 4.0
22. June 2015
12/79
2.2.3
Individual Order via Internet
2.2.3.1 General
It is possible to initiate the order of a service via the internet and to bill and/or deliver the content with
SMS/MMS Business Numbers. In this case it is necessary to clearly indicate the details of the offering (e.g.
price).
The Third Party sends a SMS/MMS including the charging information equal to the advertised price after the
end customer has downloaded the content.
In case the end customer barred (please see chapter 4) from using such services by Swisscom, the Third Party
has to inform the user either via internet or SMS/MMS.
2.2.3.2 Process
1.
2.
3.
4.
End Customer
Third Party
Figure 5: Process Individual Order via Internet
1. End customer makes an order on the internet using his MSISDN for identification (valid as first order/confirmation). At the same time an age query may be made on the internet for erotic services.
2. End Customer receives a SMS/MMS with request for confirmation (“YES”, “OK”, “START” etc). With
erotic services, the Third Party must use SMS/MMS Business Numbers (delivery with a six-digit short
ID) for this purpose for ensuring proper age verification.
3. Charges may only be made, after the consumer has received the information in accordance with
point 2. The acceptance of the offer has to be made with MO-SMS, (“YES”, “OK”, “START” etc). on his
or her mobile terminal. (PBV Art. 11.a5).
4. Afterwards the delivery and charging via SMS/MMS takes place (If the content is provided by WAP
Push in an intermediate stage, the charge SMS/MMS can only be sent once the download has been
successfully completed).
CH-3050 Bern
3
Version 4.0
22. June 2015
13/79
2.3 Subscription Service
2.3.1
Subscription Service via SMS/MMS
2.3.1.1 How to subscribe to a service via SMS/MMS
End customers may also be interested in getting a service on a regular basis. With SMS/MMS Business
Numbers it is possible to subscribe to SMS/MMS subscription services.
An end customer sends a SMS/MMS to a defined short ID. The text field of the SMS/MMS contains the
command START followed by the keyword related to the service and defined by the Third Party (e.g. START
NEWS). After receipt the Third Party makes an entry in its subscription database and sends a confirmation
SMS/MMS to the end customer. This SMS/MMS has to be free of charge (Billrate 81) and must contain the
string START keyword in the billing text field of the reply message to the Enabling Platform (e.g. START
NEWS.
Subscription services may only be charged if, subsequently to placing the initial order, the
end customer has expressly stated that he accepts the offering (this is also known as a “double opt-in”, in accordance with Art. 11b of the Federal Ordinance on the Disclosure of Prices
PBV)
Apart from the billing text and the billrate (charge), the confirmation SMS/MMS must also include the original MO text from end customer in double brackets (<< >>) at the beginning of the message (e.g. <<START
NEWS>> was registered). This behavior has to be performed for cancelling transport fee.
The Third Party will pay transport fee (Billrate 89) if:
-
Billrate 81 is not set
-
MO message does not contain START keyword
-
MT message does not contain << START keyword>> (must match with the MO message)
in brackets at the beginning of the message
Additionally the confirmation SMS/MMS must contain information regarding frequency, Third Party's hotline number, any basic fee and clear instructions on how to cancel the service.
Whenever a subscribed service is due, the Third Party sends a SMS/MMS to the customer. This SMS/MMS includes the charging information equal to the advertised price (assumed download was successful) and must
contain the string ABO keyword in the billing text field of the reply message to the Enabling Platform (e.g.
ABO NEWS).
CH-3050 Bern
3
Version 4.0
22. June 2015
14/79
The Third Party is free to define how the content delivery will be triggered. Most subscription services use
event triggered content delivery. Time and date can also be a criterion to send an SMS/MMS out to an end
customer.
CH-3050 Bern
3
Version 4.0
22. June 2015
15/79
In case of receiving the message from the Enabling Platform that an MSISDN does not belong to a Swisscom (Switzerland) customer (NO_SCMN No Swisscom Subscriber) or is invalid
(Inv. Cust), the Third Party must stop delivering all subscriptions for this MSISDN immediately. If the system shows that the MSISDN has been temporarily blocked (TMP_REJ Temporarily
rejected customer), all subscriptions on this short ID must be stopped if the content can still
not be delivered after 4 weeks. During this period, no more than 1 delivery attempt may be
made per week (This rule counts for all service types described in this manual).
2.3.1.2 Process
1.
2.
3.
4.
End Customer
Third Party
Figure 6: Process Subscription Order via SMS/MMS
1. The order process is triggered via SMS/MMS using START keyword or just with a keyword (if so the
end customer must provide explicit confirmation using START in step 3).
2. End Customer receives a SMS/MMS with request for confirmation with YES (OK) or START and the
following information: pricing information; information on how to cancel the subscription; Third
Party’s hotline number; Information on possible download charges; information on expected number of SMS (in accordance with Art. 11b of the Federal Ordinance on the Disclosure of Prices PBV)
plus confirmation of age request with erotic services
3. Upon receipt of this information, the end customer must expressly confirm his order of the service (a
so called second stage access or double opt-in).
successfully completed). But be aware that the limit of CHF 5.- per minute may not be exceeded.
2.3.1.3 How to unsubscribe a service via SMS/MMS
To cancel an existing service, the command STOP followed by the service keyword has to be sent to the short
ID of the Third Party. On receipt the Third Party deletes the related entry in its subscription database and
sends a confirmation SMS/MMS to the customer. This SMS/MMS has to be free of charge (Billrate 83) and
must contain the string STOP keyword (e.g. STOP NEWS) in the billing text field of the reply message to the
Enabling Platform.
CH-3050 Bern
3
Version 4.0
22. June 2015
16/79
Apart from the billing text and the billrate (charge), the confirmation SMS/MMS must also include the original MO text from end customer in double brackets (<< >>) at the beginning of the message (e.g. <<STOP
NEWS>> was registered and the subscription will be stopped immediately). This behavior has to be performed for cancelling transport fee.
The Third Party will pay transport fee (Billrate 89) if:
-
Billrate 83 is not set
-
MO message does not contain STOP keyword
-
MT message does not contain << STOP keyword>> (must match with the MO message)
in brackets at the beginning of the message
2.3.1.4 How to unsubscribe all services via SMS/MMS (of one Short ID)
To unsubscribe all existing services of a single short ID the command STOP ALL or STOPP ALL without a following keyword must be sent to the Third Party’s short ID. In this case the Third Party must delete all entries
in its subscription database.
After receipt the Third Party deletes all entries of this MSISDN in its subscription database and sends a confirmation SMS/MMS to the customer. This SMS/MMS has to be free of charge (Billrate 83) and must contain
the string STOP ALL in the billing text field of the reply message to the Enabling Platform.
Since it can occur that end customers send STOP or STOPP, the Third Party is free to either delete all entries
in its subscription database or to send back a SMS/MMS containing the information on all services to which
an end customer has subscribed (see also keyword VIEW) as well as how to cancel the subscription.
2.3.1.5 Summary Subscription Keywords
Case
Command
Description
Text of Reply SMS
Billing Text
Subscribe a service via
SMS/MMS
(End customer
sends keyword)
Subscribe a service via
SMS/MMS
(End customer
sends START
keyword)
Keyword
Initiates a subscription of a
service defined by the keyword
Request for confirmation with
START and further necessary
information
keyword
eg:
NEWS
Initiates a subscription of a
Text of MO SMS in double
brackets at the beginning
( e.g. <<START NEWS>>) as
well as request for
confirmation with YES (OK)
and further necessary information
START keyword
eg:
START
NEWS
eg:
NEWS
START
keyword
eg:
START
NEWS
CH-3050 Bern
3
Version 4.0
22. June 2015
Billrate
(Charge)
Billrate 81
Billrate 81
17/79
Send the
subscribed
information
Sends out the subscribedinformation
Subscribed content/
information
ABO
keyword
DefinedbyTP
eg:
ABO NEWS
Unsubscribe a
particular
service via
SMS/MMS
STOP
keyword or
STOPP keyword
Cancels the subscription of a
Text of MO SM/MMS in double
( e.g.<<STOP NEWS>>) as well
as confirmation
STOP
keyword
Billrate 83
Unsubscribe
all services
via SMS/MMS
STOP ALL or
STOPP ALL
Cancels all subscriptions
started under related Short
ID immediately
( e.g. <<STOP ALL>>) as well as
confirmation
STOP ALL
Billrate 83
Unsubscribe
all services
via SMS/MMS
(Option 1)
STOP /
STOPP
Cancels all subscriptions
started under related Short
ID immediately
brackets at the beginning ( e.g.
<<STOP>>) as well as confirmation
STOP ALL
Billrate 83
Unsubscribe
all services
via SMS/MMS
(Option 2)
STOP /
STOPP
Information on all services to
which an end customer has
subscribed and how to cancel them
Information on all services and
how to cancel them
STOP
Info
Billrate 83
eg:
STOP NEWS
Table 1: Summary Subscription
2.3.2
Subscription Service via Mobile Internet
2.3.2.1 How to subscribe to a service via Mobile Internet
We would generally recommend that this is carried out using our Easypay product. Should this not be possible for reasons of transparency (Sunrise and Orange), we allow the process set out to be used, provided the
order is triggered by the customer via SMS/MMS.
2.3.2.2 Process
1.
2.
3.
4.
End Customer
Third Party
Figure 7: Process Subscription Order via Mobile Internet
1. The order process is triggered via SMS/MMS using START keyword or just with a keyword (if so the
end customer must provide explicit confirmation in step 2).
CH-3050 Bern
3
Version 4.0
22. June 2015
18/79
2. The end customer receives a SMS/MMS with a link on a mobile portal with a clearly explained order
procedure as well as the following information provided clearly: pricing information; information on
how to cancel the subscription; Third Party’s hotline number; Information on possible download
charges; information on expected number of SMS (in accordance with Art. 11b of the Federal Ordinance on the Disclosure of Prices PBV) plus confirmation of age request with erotic services. Upon
receipt of this information, the end customer must expressly confirm his order (a so called second
stage access or double opt-in).
3. Charges may only be made after the consumer has received the information in accordance with point
2 and expressly confirmed (“YES”, “OK”, “START” etc) acceptance of the offer on his or her mobile
terminal. A confirmation just by entering the PIN is no longer accepted by law.
4. Afterwards the delivery and charging (Billrate 81) via SMS/MMS takes place. If the content is provided by WAP Push in an intermediate stage, the charge SMS/MMS can only be sent once the download
has been successfully completed. But be aware that the limit of CHF 5.- per minute may not be exceeded.
2.3.2.3 How to unsubscribe via Mobile Internet
To unsubscribe existing services the command STOP or STOPP with a following keyword must be sent to the
Third Party’s short ID.
A Third Party can also offer cancellation possibilities of one or all services over the mobile internet.
After a successful cancellation the Third Party must inform the end customer about the canceled subscription in any case by sending a confirmation SMS/MMS. This SMS/MMS has to be free of charge (Billrate 84)
and must contain the string STOP in the billing text field of the reply message to the Enabling Platform.
2.3.3
Subscription Service via Internet
2.3.3.1 How to subscribe to a service via Internet
It is possible to initiate the order of a subscription service via the internet and to bill and/or deliver the content with SMS/MMS Business Numbers.
In case the end consumer is barred from this service by Swisscom (please see message-state in chapter
4.3.2.2), the Third Party has to inform the user either via internet or SMS/MMS.
2.3.3.2 Process
CH-3050 Bern
3
Version 4.0
22. June 2015
19/79
1.
2.
3.
4.
End Customer
Third Party
Figure 8: Process Subscription Order via Internet
1. End customer makes an order on the internet using his MSISDN for identification (valid as first order/confirmation). For erotic services, the Third Party must set up an information page to notify end
users about the content, in particular about the erotic and/or pornographic nature of the content
provided by the service. End customers may only access the content page once they have been informed in this way. The advance notification page must also contain an appropriate age check. Content previews may not contain any pornographic images.
2. . With erotic services, it’s a must to use SMS/MMS Business Numbers (delivery with a six-digit short
ID) for this purpose for ensuring proper age verification. Furthermore the SMS/MMS contains as
well as the following information provided clearly: pricing information; information on how to cancel the subscription; Third Party’s hotline number; Information on possible download charges; information on expected number of SMS (in accordance with Art. 11b of the Federal Ordinance on the
Disclosure of Prices PBV). This information must be notified clearly and free of charge on the mobile
terminal of the end customer before the activation of the service.
3. Charges may only be made after the consumer has received the information in accordance with
point 2. and expressly confirmed (“YES”, “OK”, “START” etc) acceptance of the offer on his or her
mobile terminal. A confirmation just by entering the PIN is no longer accepted by law.
4. Afterwards the delivery and charging (Billrate 83) via SMS/MMS takes place. If the content is provided by WAP Push in an intermediate stage, the charge SMS/MMS can only be sent once the download has been successfully completed. But be aware that the limit of CHF 5 per minute may not be
exceeded.
2.3.3.3 How to unsubscribe via Internet
To unsubscribe a dedicated service the command STOP keyword/STOPP keyword must be sent to the Third
Party’s short ID. To unsubscribe all existing services the command STOP ALL or STOPP ALL without a following keyword must be sent to the Third Party’s short ID.
A Third Party can also offer cancellation possibilities of one or all services over the internet.
After a successful cancellation the Third Party must inform the end customer about the canceled subscription by sending a confirmation SMS/MMS. This SMS/MMS has to be free of charge (Billrate 83). For further
information please see Table 1: Summary Subscription.
2.4 SMS Competitions
CH-3050 Bern
3
Version 4.0
22. June 2015
20/79
SMS/MMS/WAB/WEB-based competitions allow end customers to participate in games of chance via SMS.
The VAS provider undertakes to comply with the relevant laws, in particular the Swiss Federal Lotteries Act
and the Unfair Competition Act.
In addition "chat-style" competitions, whereby end customers have to answer a series of questions via a
number of chargeable MT (Mobile Terminated) SMS, are not permitted. A maximum of one (1) chargeable
MT SMS is permitted per competition entry. End customers are free to enter a competition several times if
they so wish. To do so, they must automatically activate each additional entry in a conscious and unambiguous manner with an MO (Mobile Originated) SMS to the relevant short ID.
2.5 Chat Services
2.5.1
General
Chat services based on SMS/MMS allow end customers to exchange messages via a central user list, for
which the sharing of telephone numbers (MSISDN) is not necessary. The end customer can therefore use a
pseudonym and remain anonymous to others.
A maximum of one hour after the end customer sends the final SMS, no other SMS message for which the
end customer is required to pay may be sent. The Third Party is required to inform the end customer about
the deactivation of the chat service by sending a free SMS/MMS. If the end customer wishes to continue the
chat, he is required to activate the service by sending a keyword to the appropriate short number.
2.5.2
Process
1.
2.
3.
4.
End Customer
Third Party
Figure 9: Process Chat Order
1. A chat service is activated when the end customer sends a keyword to the appropriate short number
(The illustration shows access via SMS/MMS. However, the same procedure must also be used if activating a chat service via (mobile) internet).
CH-3050 Bern
3
Version 4.0
22. June 2015
21/79
2. End Customer receives a SMS/MMS with request for confirmation with YES or START containing the
following information provided clearly: pricing information including the charges thereby incurred
per SMS/MMS ; information on how to cancel the service; Third Party’s hotline number; Information
on possible download charges; information on expected number of SMS/MMS (in accordance with
Art. 11b of the Federal Ordinance on the Disclosure of Prices PBV) plus confirmation of age request
with erotic services. Upon receipt of this information, the end customer must expressly confirm his
order (a so called second stage access or double opt-in).
3. Upon receipt of this information, the end customer must expressly confirm his order of the service (a
so called second stage access or double opt-in).
successfully completed). But be aware that the limit of CHF 5.- per minute may not be exceeded.
2.6 Packages/Bundles
If the end customer ordered a package (bundle), the Third Party must send a confirmation message. This
confirmation message must contain the keyword for the service ordered, its frequency, the Third Party's hotline number and, if applicable, clear instructions on how and where the individual items of content may be
acquired.
With the first SMS/MMS the whole price is charged to the end customer (in accordance with Art. 11a of the
Federal Ordinance on the Disclosure of Prices PBV). Thereafter the content of the package (bundle) can be
sent to the end customer (or alternatively the end customer is able to obtain the content). If the content is
sent, then the following SMS/MMS must be free of charge for the end customer.
2.7 Service Billing
The Third Party can freely choose the end customer price for services send by SMS or MMS within the contract rules. Billing is only possible via the SMS or MMS submit interface. Within the submit message, the
Third Party must send a billrate (charge) or amount and the corresponding billtext.
For a Deliver Service there is no content billing. Only Submit Services can send the content together with the
billing information.
2.8
Wap Push Services and SMS with URL
The following requirements apply if the Third Party wants to deliver the content ordered by the end customer via Wap Push or via an SMS with URL:
CH-3050 Bern
3
Version 4.0
22. June 2015
22/79
Link and service billing cannot be sent via SMS but must be sent to the end customer in a
separate message.
The Third Party may only bill the content once it has been successfully downloaded by the
end customer.
The link must remain active for the end customer for 24 hours after being sent by the Third
Party. This enables the end customer to access the link several times to fully download the
content in the event of download problems.
2.9
Itemized Bill and Billing Text
2.9.1
Itemized Bill
The itemized bill is a supplementary service offered by Swisscom to its mobile customers. In addition to the
regular bill, on which all charges are listed under the position “Services of other providers” (or similar text in
other languages), the detailed SMS/MMS service charges are listed as well.
Services of other providers
Date/Time
Short ID
Service
Posted
Amount in
CHF
03.04.2008 21:12:21
9248
funInfo GAMES
1
4.90
04.04.2008 18:24:25
9225
eInfo NEWS
1
0.30
05.04.2008 16:15:03
939
funChannel MMS PICTURE
1
0.50
13.04.2008 09:45:67
96345
InfoService WEATHER
1
0.70
Total
6.40
Figure 10: Abridgement of the Itemized Bill
2.9.2
Billing Text
The main part of the itemized/detailed bill is the service text. This text consists of a predefined text set by
the Swisscom billing system and the service details set by the Third Party (see highlighted text in Figure 10).
Due to a limitation of the Enabling Platform we demand the use of content classes (e.g. ringtone instead of ringtone57, picture instead of picture_sunset, START Chat instead of START
Chat eve22, etc.). In case of standard keywords HELP, INFO, INDEX and VIEW we demand the
use of exactly these keywords in the billing text field.
The maximum length of the definable billing text may not exceed 31 characters.
CH-3050 Bern
3
Version 4.0
22. June 2015
23/79
For billing texts relating to services with erotic and pornographic content, we wish to point
out that it is in the interests of the end customer to use a neutral description. Under no circumstances should obvious keywords or text passages from chat sessions be used as billing
texts for such sensitive services.
2.10
Service Info
2.10.1 Summary Service Information
An end customer has the possibility to order various service information. The Third Party has to provide the
standard keywords (HELP, INFO, INDEX and VIEW) under every Short ID
The keywords must function for both upper and lower case letters.
Case
Command
Description
Text of Reply SMS
Billing Text
Get support
HELP
INFO
INFO
Billrate 80
Receive information on how
to use the service
View all subscribed services
INDEX
e.g. hotline number or internet
address
Company name, address,
phone/fax number in Switzerland and e-mail address
Information on how to use the
service
HELP
Receive contact
information
Information on how to use
the services
Contact information of the
Third Party providing this
service
Information on how to use
the service together with details of where and how to
find further information
Information on all services to
which an end customer has
subscribed
Billrate
(Charge)
Billrate 80
INDEX
Billrate 80
All keywords of subscribed services from the corresponding
Third Party
VIEW
Billrate 80
VIEW
Table 2: Summary Service Information
Further information regarding keywords can be found in the Contract Annex 1 and in the document Code of
Conduct [3].
CH-3050 Bern
3
Version 4.0
22. June 2015
24/79
2.11
Enabling Platform Generated Info
In certain cases the Enabling Platform generates an error message for the end customers. An aggregation of
these messages is listed in the monthly statistics.
Case
Command
Third Party is
not available
SIS is not available or end customer is
blocked
Wrong usage of
billrate 81-84
Description
Text of Reply SMS
If MO message can not be
delivered towards Third Party, the enabling platform
generates an auto response
message
If MO message can not be
delivered towards Third Party because end customer is
blocked, the enabling platform generates an auto response message
If Third Party is using billrate
81-84 in a wrong manner,
enabling platform generates
billrate 89
MBS generates text which informs end customer that Third
Party is not available
Billing Text
Billrate
(Charge)
Billrate 40
MBS generates text which informs end customer that he is
not allowed to use this service
Billrate 42
(SMS)
Billrate 45
(MMS)
MBS generates CDR with
adapted billrate
Billrate 89
Table 3: Error messages and Billrates
2.12
Wrong Keyword
In case the end customer sends a wrong keyword, the Third Party must send a SMS with Billrate 42 or a MMS
with Billrate 44 and a text which informs the end customer about the wrong keyword. To prevent a “Ping
Pong” effect (e.g. if a MT message reaches a GSM module, instead of an end customer, the module will answer with an invalid keyword) TP should store all received messages with invalid keywords. If there are a few
SMS from the same MSISDN in a very short time the application should stop to send the wrong keyword notification (answer to the invalid keyword).
Case
Command
Description
Text of Reply SMS
Billing Text
Wrong keyword
Wrong
keyword
If end customer sends a
wrong keyword
Text which informs the end
customer about the wrong
keyword
WRONG
KEYWORD
or ERROR
Billrate
(Charge)
Billrate 42
(SMS)
Billrate 44
(MMS)
Table 4: Wrong keyword
Advertising text in the error message of invalid keywords are not allowed!
2.13
End customer authentication and authorization
CH-3050 Bern
3
Version 4.0
22. June 2015
25/79
SMS/MMS Business Numbers performs user authentication and provides the phone number (MSISDN) of
the end customer to the Third Party. Further it performs authorization checks for credit limit (so called Top
Stop) and age (Age Check). For ensuring proper age verification the Third Party must receive or deliver the
content via a six-digit short ID.
CH-3050 Bern
3
Version 4.0
22. June 2015
26/79
3
Technical Concept
3.1 General Overview
Swisscom offers Third Parties connections to its mobile and billing network via the Enabling Platform. The
Enabling Platform acts as gateway for incoming and outgoing requests (Enabling Platform is an umbrella
term for the whole message transport network which consists of several systems and platforms). Requests
may be transmitted to a Third Party by the so called Third Party Interface (TPI). The protocol used is Multipart
SOAP (SOAP Messages with Attachments) via HTTP/1.1(https XML/SOAP for further information please see
chapter 4 or http://www.w3.org/TR/SOAP-attachments).
Be sure to support http 1.1 (chunked mode) standard in order to receive MO SMS and MO MMS properly.
The application must be fully http 1.1 compliant and whether it may mainly handle variable chunk lengths.
We refer to the chunk mode specification which allow chunk lengths from 1 bit to max the whole message
length chunk.
If you are using the Swisscom “SMS/MMS Business Numbers Referenz API” [13] you are fully compliant with
http 1.1 standard including variable chunk length.
To send adult content, it’s required to use a short-id beginning with 6xxxx. The SMS/MMS BN infrastructure
then checks that the sending will not reach minors, nor recipient with adult blockage.
3.2 Functional Overview
The following table summarizes the functions of the two interfaces.
Function
Interface
https
Receive (SMS or MMS from end customer to TP)
Send (SMS or MMS from TP to end customer)
Define additional parameters SMS / MMS
Binary SMS
Delivery notification
Attachments such as Text, Pictures, Sound, Video
Transcoding of MMS attachments
MSISDN
Billing
Language
Handset Type
SMS
MMS
Deliver
XML/SOAP
Submit
XML/SOAP
Deliver
XML/SOAP
Submit
XML/SOAP






n/a
n/a
n/a
n/a


n/a
n/a


text
n/a
plain
n/a






text
n/a
plain
amount or
charge
n/a
n/a


n/a
plain
n/a


n/a



plain
amount or
charge
n/a
n/a
Table 5: TPI Interface functional overfiew
CH-3050 Bern
3
Version 4.0
22. June 2015
27/79
4
Third Party Interfaces (TPI)
4.1 Overview
Message Broker (MB) supports MMS and SMS submission over SOAP (MMS or SMS are sent from the Third
Party to the handset), as well as MMS and SMS delivery over SOAP (handset owners send MMS or SMS to the
Third Party). This is sketched in the following figure:
Message Broker
Third Party
Deliver
Service Stub
Web Service
Web Service
Service Stub
Submit
Figure 11: Service Delivery over SOAP
Both ways are implemented by the Third Party interface (TPI), in the form of a web service based on SOAP. A
“simple” message based service (JAXM [9]) with no complex type binding and no notion of method call JAXM
is supported. Swisscom delivers a reference implementation [7] for the TPI Interface which makes it easy to
the Third Parties to implement the JAXM Web Service. The data exchange is formatted with XML. The
transport is made over https. This enables to have a synchronous request – response behavior.
The aim of web services is that Third Parties may realize their client programs in any programming language
which are supporting XML/SOAP. For the most common programming languages there are interface compilers which generate a client program code for accessing the web services.
If the Third Parties intend to use Java software as Message Broker client, he can use the provided reference
implementation (MB_TPI_x.x-bxx.zip [7]) to connect to Message Broker.
If the Third Parties use a programming language other than Java, it might be simpler to use the JAXM type
service because the XML structure “on the wire” is somewhat simpler. The supported fields and the general
message flow is for both service types exactly the same.
The interface is basically string based. All values are sent as a string representation over the network. In MB
Strings and its character representation is treated as Unicode (16 bit). Over the TPI interface all strings are
expected to be UTF-8 encoded.
If the Third Parties use https to connect TPI Interface to MBS, it is important that the https request contains
the URL of the MBS and not the IP Address, because the VeriSign certificate checks the received URL.
CH-3050 Bern
3
Version 4.0
22. June 2015
28/79
Example:
https://messagingproxy.swisscom.ch:16100/submit
CH-3050 Bern
3
Version 4.0
22. June 2015
29/79
4.2 Technical Overview
The Enabling Platform consists of Messaging Proxy, Message Broker, SMSC, MMSC and Rating engine. Third
Party is able to connect to Messaging Proxy via a SOAP based TPI Interface. In MT case the Message Broker
splits message and billing information. Messages are forwarded to transport systems, such as SMSC or
MMSC. Billing information is collected in the Rating engine. The Rating engine calculates the revenue share
for Third Parties and sends the whole billing report (end customer billing and Third Party revenue share) towards Billing for complete the whole billing process. In MO case Message Broker receives messages from
SMSC or MMSC and sends it to the right Third Party.
Figure 12: Technical overview
CH-3050 Bern
3
Version 4.0
22. June 2015
30/79
4.3 SMS Services
The request is transmitted as https in a XML/SOAP format to a server at the Third Parties. For each request, a
new connection is opened. The Third Parties may implement any of a range of common techniques (CGI,
servlet, etc.) to service the request.
The MB is able to receive and process SMS Submit Requests from the Third Parties and send them further to
the SMSC. Similarly, it may receive SMS Deliver Request from the SMSC and forward them further to the
Third parties.
For SMS submission, the Third Party sends a SMS Submit Request to the MB, which translates it into a request accepted by SMSC. The latter parses and checks the received request, and replies with a response. MB
translates this response back into a SMS Submit Response and sends it synchronously to the Third Party.
To deliver a SMS to the Third Party, MB receives a message from SMSC and appends a request to a message
queue. MB extracts the message from the queue, translates it into a SMS Deliver Request and sends it to the
Third Party. Therefore the latter must implement a Web Service in order to be able to receive SMS Deliver Request from MB. Upon receipt of a SMS Deliver Request, the Third Party must return a SMS Delivery Response
synchronously.
TPI Interface enables also to receive and to send binary SMS and EMS. You will find information about binary
SMS and EMS (UDH, DCS, Nokia ports etc.) in the next chapters.
The SOAP messages exchanged between MB and Third Party are described in the remaining of this chapter.
However, the interface between MB and SMSC is purely internal and is thus not be detailed in this document.
4.3.1
SMS Deliver (MB  Third Party)
4.3.1.1 SMS Deliver Request (MB  Third Party)
In order to receive SMS Deliver Requests, the Message Broker client (Third Party) must accept https requests
containing one well formed SOAP envelope and zero or more attachments.
Deliver Request
Message Broker
(Part of Enabling Platform)
SOAP (synchronous)
Third Party
Deliver Response
Figure 13: SMS Deliver Request from MB to Third Party
CH-3050 Bern
3
Version 4.0
22. June 2015
31/79
Possible SMS Deliver Request parameters are:
Information Element / SOAP
Tag
Type
Presence
Description
SMS / UCP
Name
transaction-id
String 1
message-type
String 1
Mandatory
Transaction ID created by MB
n/a
Mandatory
Identifies this message as a SMS deliver request
n/a
tpi-version
String 1
Mandatory
Identifies the version of the interface
n/a
linked-id
String 1
Optional
n/a
from
String 1
Identifier that may be used by the VASP in a subsequent
SMS Submit
The address of the SMS originator (MSISDN)
recipient
String 1
Mandatory
OAdC
dcs
String 1
Optional
The address(es) of the intended recipients of the subsequent
processing by the Third Party or the original recipient address(es). It is possible to mark an address to be used only
for informational purposes
The DCS (Data Coding Scheme of binary SMS)
1
Optional
User Data Header (especially for concatenated messages)
UDH
UTC formatted
Mandatory
SCTS
udh
String
Value
2
SMSDeliverRequest
41796598872
Mandatory
AdC
DCS
date-time
Date
language
String 1
de, en, ?, fr, it
Optional
handset-brand
String 1
Optional
handset-model
String 1
e.g. Sony Ericsson
e.g. K750i
The time and date of the submission of the SMS (time
stamp)
The used language (two characters). Or ? (language in SIS
unknown
Handset manufacturer
Optional
Handy model
n/a
String
1
e.g. 356552
Optional
TAC code (part of IMEI) type approval code
n/a
handset-snr
String
1
e.g. 724445
Optional
Handsets serial number
n/a
handser-svn
String 1
HREF Attribut
Filename1
e.g. 05
Optional
Version of handset software
n/a
SOAP attachment (String) 1
Optional
The content of the message
Text
String 1
no, 2.00,
amount ok,
amount low
Optional
Information about Prepaid customer balance
In case of Postpaid MSISDN, you will receive:
“511: Given MSISDN has not been found in PPB. Code:0”
n/a
handset-tac
content 3
balance-check
n/a
n/a
Table 6: SMS Deliver Request parameter
1
Strings are Unicode based and must be UTF-8 encoded. Theoretical length up to 65536 characters if there are no other limitations.
2
Dates can be set in local time. Using the JAXM type service date values shall be sent as UTC values using the format 2003-0505T21:43:15Z or as a local time value using the format 2003-05-05T23:43:15+02:00 which indicates the current offset between local time and UTC in hours and minutes as (local time – UTC).
3
If an MO SMS includes a non 7 bit ascii character (e.g. ô), SMSC uses UCS-2 8 bit encoding (hex) and forwards the MO SMS to MBS.
MBS forwards such UCS-2 messages untouched to Third Party. The charset in SMS delivery request will be set to UTF-16 (instead of
UCS-2)
In case the end customer sends a long SMS (more then one SMS with 160 characters), Third
Party will receive one concatenated SMS. This means the enabling system is collecting together all long SMS parts and the Third Party can receive content with more then 160 characters.
CH-3050 Bern
3
Version 4.0
22. June 2015
32/79
4.3.1.2 SMS Deliver Response (Third Party  MB)
A SMS Deliver Response must be sent by the Third Party in response to a SMS Deliver Request. A response is
either represented by an https response containing one well formed SOAP envelope for the JAXM service [9].
CH-3050 Bern
3
Version 4.0
22. June 2015
33/79
A SMS Deliver Response is defined by the following parameters:
Information Element
Type
transaction-id
String 1
message-type
state
String 1
Integer
state-text
String 1
tpi-version
String 1
service-category
String
Value
Presence
Description
Mandatory
The identification of the Deliver Request and Deliver Response pair
SMSDeliverResponse
Mandatory
Identifies this message as a SMS Deliver Request
See Table 8: Request
states within response
See Table 8: Request
states within response
Mandatory
Status of the completion of the request
Optional
Text description of the status for display purposes, should qualify the
request status
Mandatory
Version of the TPI Interface
Optional
Information supplied by the Third Party which may be included in
charging information. The syntax and semantics of the content of this
information are out of the scope of this specification.
1
Table 7: SMS Deliver Response parameter
1
Possible SMS Request States within response message are:
Status Code
Status Text
Meaning
1000
1100
Success
Partial success
2000
2001
2002
2003
2004
Client error
Operation restricted
Address Error
Address Not Found
Multimedia content refused
2006
LinkedID not found
2007
3000
3001
3002
3003
Message format corrupt
Server Error
Not Possible
Message rejected
Multiple addresses not supported
4000
4001
4002
4003
General service error
Improper identification
Unsupported version
Unsupported operation
4004
Validation error
4005
4006
Service error
Service unavailable
4007
Service denied
This code indicates that the request was executed completely
This code indicates that the request was executed partially but some parts of the request
could not be completed. Lower order digits and the optional details element may indicate
what parts of the request were not completed
Client made an invalid request
The request was refused due to lack of permission to execute the command
The address supplied in the request was not in a recognized
The address supplied in the request could not be located
The server could not parse the MIME content that was attached to the SOAP message and indicated by the content element or the content size or media type was unacceptable
This code is returned when a LinkedID was supplied and the server could not find the related
message
An element value format is inappropriate or incorrect
The server failed to fulfill an apparently valid request
The request could not be carried out because it is not possible.
Server could not complete the service requested
The Server does not support this operation on multiple recipients. The operation may be resubmitted as multiple single recipient operations
The requested service cannot be fulfilled
Identification header of the request does not uniquely identify the client
The version indicated by the interface version element is not supported
The server does not support the request indicated by the MessageType element in the header
of the message
The SOAP and XML structures could not be parsed, mandatory fields are missing, or the message-format is not compatible to the format specified. Details field may specify the parsing
error that caused this status
The operation caused a server failure and should not be resent
This indication may be sent by the server when service is temporarily unavailable, e.g. when
server is busy
The client does not have permission or funds to perform the requested operation
Table 8: Request states within response
CH-3050 Bern
3
Version 4.0
22. June 2015
34/79
4.3.1.3 Example in case of SMS Deliver:
In case of SMS Deliver, the Message Broker issues a SOAP (JAXM [9]) Request as shown in the following table:
POST / deliver HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)
Content-Type: multipart/related; boundary=557e7942
Accept: */*
Accept-charset: utf-8
SOAPAction: SMSDeliverRequest
Via: HTTP/1.0 10.222.38.200:9000
Host: 10.234.31.43:18888
Connection: close
Content-Length: 1075
--557e7942
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-Id: 1
HTTP header
boundary
MIME part header
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<version soapenv:actor="MB" soapenv:mustUnderstand="0" xmlns="">1.0</version>
<request-type soapenv:actor="MB" soapenv:mustUnderstand="0" xmlns="">SMSDELIVER.REQ</request-type>
</soapenv:Header>
<soapenv:Body>
<tns:SMSDeliverRequest xmlns:tns="http://www.swisscom.com/mb/schema">
<transaction-id>143520150615090538027</transaction-id>
<tpi-version>1.4.0-b92</tpi-version>
<from>41791112233</from>
<recipient>90087</recipient>
<date-time>2015-06-15T07:05:37Z</date-time>
<content filename="String" href="0"/>
<message-type>SMSDeliverRequest</message-type>
</tns:SMSDeliverRequest>
</soapenv:Body>
</soapenv:Envelope>
--557e7942
Content-Type: text/plain; charset="utf-8"
Content-Id: <0>
SOAP part
boundary
MIME part header
Test SMS: Hello World!
--557e7942—
attachment
boundary
* Deliver messages are always sent chunked encoded! That’s why there are numbers between the message parts.
CH-3050 Bern
3
Version 4.0
22. June 2015
35/79
The Third Party returns a response in the following form:
HTTP/1.1 200 OK
Connection: close
Server: Jetty(6.1.2)
HTTP header
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"><soapenv:Header><version soapenv:actor="tpi" soapenv:mustUnderstand="0" xsi:type="xsd:string">1.4.0-b92
built on 2014-09-15 @ 11:13:10</version><request-type soapenv:actor="tpi" soapenv:mustUnderstand="0"
xsi:type="xsd:string">SMSDELIVER.RESP</request-type></soapenv:Header><soapenv:Body><tns:SMSDeliverResponse
xmlns:tns="http://www.swisscom.com/mb/schema">
<transaction-id>143520150615090538027</transaction-id>
<state>1000</state>
<state-text>Success</state-text>
<tpi-version>1.4.0-b92 built on 2014-09-15 @ 11:13:10</tpi-version>
<message-type>SMSDeliverResponse</message-type>
</tns:SMSDeliverResponse></soapenv:Body></soapenv:Envelope>
SOAP part
* Deliver Responses can be chunked encoded.
It indicates that the message has been accepted (state = 0) and the recipient is valid. The TransactionID corresponds with the values sent with the request.
4.3.2
SMS Submit (Third Party  MB)
4.3.2.1 SMS Submit Request (Third Party  MB)
In order to send SMS Submit Requests, the Message Broker client (Third Party) must support https requests
containing one well formed SOAP envelope and zero or more attachments.
Submit Request
SOAP (synchronous)
Message Broker
Submit Response
Report (Delivered)
Third Party
SOAP (synchronous)
Response
Figure 14: SMS Submit Request from Third Party to MB
CH-3050 Bern
3
Version 4.0
22. June 2015
36/79
Possible SMS Submit Request parameters are:
Information
Element/
SOAP Tag
Type
Value
Presence
Description
SMSC/
UCP
Name
short-id
Integer
Short ID
Mandatory
n/a
service-name
String 3
Mandatory
username
String 3
Mandatory
password
String 3
Mandatory
Password for authentication
n/a
recipient
String 3
Max. length: 160 Characters
MSISDN in international
Format:
41796598872 or
+41796598872
Together with ServiceName selection parameters for
used service
Together with ShortID selection parameters for used
service
User name for accessing service
Mandatory
AdC
content
HREF Attribut
Filename1
SOAP attachment (String) 4
Optional
The address of the recipient destination(s). There can
be up to 10 MSISDN (service addicted, if a submit contains up to 100 MSISDN, the next submit is only allowed after one second). Every recipient sees only his
MSISDN
The text content of the short message.
SMS or EMS (normally 160 characters but also more is
possible, then MBS will split the message in concatenated SMS, each will have 160 characters).
n/a
n/a
Text
MT SMS from MBS to SMSC consists always of 7 bit
ASCII character according to GSM specifications. Unknown characters will be removed
from
String
222
Mandatory
amount
double
0 to +9999.9999
Optional
charge
Integer
0 to 999
Optional
bill-text
String 3
Max. length: 31 characters
Mandatory
time-of-expiry
earliestdelivery-time
originator-url
report-address
Date 2
Date 2
UTC formatted
UTC formatted
Optional
Optional
String 3
String 3
https://host:port
https://host:port
Optional
Optional
delivery-report
Boolean
true / false
Optional
priority
transaction-id
String 3
String 3
low / normal / high
1–n
Optional
Mandatory
message-type
String 3
SMSSubmitRequest
Mandatory
linked-id
String 3
Optional
service-
String 3
Optional
CH-3050 Bern
3
Version 4.0
22. June 2015
Identification of sender. A string indicating the originating sender (originator). Default value will be the
short ID. Max.11 characters (only 7-bit GSM ASCII)
Amount to be billed to customer. Unit is in CHF.
Either charge or amount must be set. If none is defined, message will be rejected. If both are defined,
message will be rejected. The MB supervisor can define a minimum and maximum amount
Billrate, billing code
Either charge or amount must be set. If none is defined, message will be rejected. If both are defined,
message will be rejected.
The MB supervisor can limit the valid range of charge
values
The value of the field will be printed on the invoice
(billtext)
The desired time of expiry for the message
The earliest desired time of delivery of the Message to
the recipient
Originator's URL, optional information
The URL of the listening Third Party server. Required if
reports requested
Flag indicating if delivery reports are requested
Parameter, function used like in a e-mail
Transaction ID determined by Third Party. The submit
response will have the same transaction ID
Type of the message (e.g. SMSSubmitRequest or
CUCSubmitRequest)
This identifies a correspondence to a previous valid
message delivered to the VASP
Defines the Service category e.g. Sports, News, Adult,
OAdC
n/a
n/a
n/a
VP
DD &&
DDT
n/a
n/a
Dst &&
NT (DN)
n/a
n/a
n/a
n/a
n/a
37/79
Information
Element/
SOAP Tag
Type
Value
Presence
category
tax-rate
Double
8.0
Optional
tpi-version
String 3
rplsm
Integer
numeric value 1-7
Mandatory
Optional
nokia-binaryport
String
alpha, hex coded
Optional
message-class
is-text
Integer
Boolean
Value 0-3
true / false
Default: true
Optional
udh
String
Hex String
Optional
dcs
String
Hex-coded String (2 Bytes).
Example: 08
Optional
Optional
Description
SMSC/
UCP
Name
Chat
Third Party defines the tax rate in % (0, 2.5 or 8.0) for
this content
Defines the version of the used TPI
SMS: Replace Short Message. Values 1 – 7 map to
RPID 65 – 71. A message on the ME with the same RIP
and sender will be replaced
Nokia Binary Port on Handset.
(If this is set, you have also to define parameter istext)
Message Class, UA parameter
n/a
n/a
RPID
Binary
Port
MCLs
Used for sending EMS messages or Nokia binary messages.
Defines, if data is text or transparent data. If true, MT
(message type of the UCP message) is set to 2 or 3
(text)
If false, MT is set to 4 (binary)
If isText is set, the message is treated as EMS message
If isText is not set, the message is not treated as EMS
message
Indicates if content of message is used for EMS.
Used for sending an EMS message.
With this key, the UDH (User Data Header) can be
specified
If isText is not set, UDH is ignored
If UDH is set, the parameter Nokia Binary Port is ignored
Used for sending an EMS message
With this key, the DCS (Data Coding Scheme) can be
specified
If isText is not set, DCS is ignored
If DCS is set, the parameter Nokia Binary Port is ignored
n/a
UDH
DCS
Table 9: SMS Submit Request parameter
1
The attachment must be added as MIME multipart attachment and referenced via Content ID in the contend field. They will be
transported as MIME BodyParts of the https request.
2
Dates can be set in local time. Using the JAXM type service Date values shall be sent as UTC values using the format 2003-0505T21:43:15Z or as a local time value using the format 2003-05-05T23:43:15+02:00 which indicates the current offset between local time and UTC in hours and minutes as (local time – UTC).
3
4
SMS and EMS Text file must be UTF-8 encoded! If charset is missing, the default parameter 'charset="utf-8"' will now be added to the
content-type header of each message part of type 'text/*' of a multipart.
4.3.2.2 SMS Submit Response (MB  TP)
Every request results either in a fault condition (Exception or SOAP fault element) or in a valid response object/SOAP structure. A response is either represented by an https response containing one well formed SOAP
envelope for the JAXM service [9].
CH-3050 Bern
3
Version 4.0
22. June 2015
38/79
A SMS Submit Response is defined by the following parameters:
Information Element/ SOAP
Tag
Type
Value
transaction-id
String
state
Integer
state-text
String 1
message-type
String
see Table 12: Request
states
states
SMSSubmitResponse
message-id
message-state
String
Message
Status
see Table 11: Messagestate parameter in array
Presence
Description
Mandatory
Mandatory
Transaction ID determined by TP. The response will have the same
transaction ID.
Signals success or failure for this request.
Mandatory
An explanation text for request status.
Mandatory
Type of the message (e.g. SMSSubmitResponse or
CUCSubmitResponse)
Identifies this message.
Array of MessageStatus described in the following table. Items corresponding to each addressed recipient.
message-state is not present in case of a failed request (state not
1000)
Mandatory
Optional
Table 10: SMS Submit Response parameter
The message-state is defined by the following parameters (array):
Information Element/
SOAP Tag
message-state
Type
Value
Presence
Description
recipient
String
Mandatory
Identifies one single message
state
Int
Mandatory
Status of the message for this specific recipient
state-text
String 1
MSISDN as it was defined
in the request
see Table 13: Messagestates
Mandatory
Explanation text for Message Status
Table 11: Message-state parameter in array
1
Possible request states within SMS Submit response message are:
State
State-text
Description
1000
2101
2102
2103
2104
2107
2108
2109
2110
2111
2112
2113
2120
2123
2124
2125
Ok
Short ID unknown +[Additional Info, if necessary]
Format error +[Additional Info, if necessary]
Authentication failed +[Additional Info, if necessary]
Value outside allowed limits +[Additional Info, if necessary]
Too large content size. +[Additional Info, if necessary]
No attachment. +[Additional Info, if necessary]
Unsupported MIME type. +[Additional Info, if necessary]
Unknown service. +[Additional Info, if necessary]
Less MSISDN for Bulk Service +[Additional Info, if necessary]
Service type does not match +[Additional Info, if necessary]
MMS Bulk message id +[Additional Info, if necessary]
Billing data error +[Additional Info, if necessary]
Amount out of bound +[Additional Info, if necessary]
Charge out of bound +[Additional Info, if necessary]
Amount format invalid +[Additional Info, if necessary]
Transaction ok
Short ID (ServiceGroup) undefined for this request
Request could not be parsed (e.g. SOAP or TPI format fault)
Unknown username or invalid password
Value exceeded defined max. value
Content size is bigger then allowed
MMS submit contains no attachment
MIME type unknown or not supported
Service is not configured
MMS bulk submit does not contain enough MSISDNs
Service found but provisioned service type does not match
MMS Bulk continuation submit refers to an unknown message ID
General billing error
Amount out of bound
Charge out of bound
Amount format invalid
CH-3050 Bern
3
Version 4.0
22. June 2015
39/79
2126
2127
2130
2135
2150
3101
3102
3103
3104
3150
4101
Charge format invalid +[Additional Info, if necessary]
Tax rate not valid +[Additional Info, if necessary]
Too many recipients +[Additional Info, if necessary]
Invalid client ID +[Additional Info, if necessary]
Plain MSISDN not allowed +[Additional Info, if necessary]
Internal server errors +[Additional Info, if necessary]
DB access error +[Additional Info, if necessary]
IO error +[Additional Info, if necessary]
Server configuration error +[Additional Info, if necessary]
Participating system errors +[Additional Info, if necessary]
Request limit exceeded +[Additional Info, if necessary]
Charge format invalid
Unknown tax rate
Maximum number of recipients exceeded
Client ID could not be decoded
Service does not allow clear-text MSISDNs
An internal server error occured
The system database could not be accessed
The communication with a transport system failed
Server configuration contains an invalid element
A participating system returned a non-recoverable error
A limit on the service or system level was exceeded
Table 12: Request states
The message-state text field is an informative field that gives more information about the reason of the rejection / failure.
Possible message-state and state-text (message/content) within response message:
State
State-text
Description
0
2
4
Ok
Invalid MSISDN Format
NO_SCMN No Swisscom mobile customer
4
4
4
TMP_REJ Temporarily rejected customer
ALL_PREMIUM_SCM all premium services
blocked, set by SCM
ALL_PREMIUM_CUST all premium services
blocked, set on customers demand
ADULT_PREMIUM_SCM adult content services
blocked, set by SCM
ADULT_PREMIUM_CUST adult content services blocked, set on customers demand
REACHED_SCM limit reached, set by SCM
REACHED_CUST limit reached, set on customers demand
ADULT_PREMIUM_AGE age verification not
passed
ADULT_PREMIUM_AGE age infomation not
available
ADULT_PREMIUM_AGE age verification failed
BLOCKED_MSISDN this MSISDN is not allowed
to use this service
ERR_DST Invalid destination
This MSISDN is valid and has no blocking
Format of recipient is invalid
This MSISDN does not belong to a Swisscom customer and must be removed
from any subscription database
This customer is temporarily bared in the Swisscom network
The customer is not allowed to use SMS premium services (activated by
Swisscom)
The customer does not want to use or does not allow the user of the phone to
use SMS premium services
The customer is not allowed to use adult SMS premium services (activated by
Swisscom)
use adult SMS premium services
The customer reached the monthly limit (set by Swisscom)
The customer reached the monthly limit (set by the owner of the subscription)
4
SIS N/A
4
Invalid MSISDN
4
Invalid Customer
4
[Additional Info, if necessary]
4
4
4
4
4
4
4
4
4
Subscriber age <16 years or not passed
Age information not available
Age verification failed
MSISDN, which is not allowed to use this service
The destination is not a standard mobile number (MSISDN) or belongs to a
foreign network
Validation of MSISDN is not possible, because the validation server (SIS) is not
available at the moment and service is set to pessimistic behavior
MSISDN is not valid (amount of digits or invalid number range) or a non
Swisscom customer
This MSISDN does not belong to a Swisscom customer or is inactive and must
be removed from any subscription database
Free configurable message text, for a few errors (e.g. Discovered non numeric
char)
Table 13: Message-states
Example Request State and message-state:
CH-3050 Bern
3
Version 4.0
22. June 2015
40/79
The message-state field contains the recipient, state and state-text information.
<state>1000</state>
(-------------------- Request State)
<state-text>Ok.</state-text> (-------------------- Request State Text)
<message-state recipient="+41791112233" state="0" state-text="ok"/>
<message-state recipient="+41787408343" state="4" state-text=" NO_SCMN No Swisscom mobile customer "/>
<message-state recipient="14DBDFCC9CE40ACB9" state="2" state-text=" Invalid MSISDN Format "/>
The request status text field explains the request status. This field contains informative information only. It should not be used for processing. It provides more detailed information to
assist eventual problem investigation.
In the message-state field there is one entry for each recipient. The structure contains 3 attributes (see Table
11: Message-state parameter).
4.3.2.3 Example JAXM Submit (send an object, WSDL is not needed)
The easiest way to communicate with the Enabling Platform is by using the provided Java client framework.
If the Third Party is unable to use this Java code, one can compose a SOAP Request as follows using any programming language.
POST /submit HTTP/1.1
Content-Type: multipart/related; type="text/xml"; start="<26EA5E833E0C746B2FA8C96592EEDB2B>"; .boundary="---=_Part_0_1489439555.1434351772642"
SOAPAction: ""
User-Agent: Axis/1.4
Host: 10.222.38.200:16100
Expect: 100-continue
Transfer-Encoding: chunked
HTTP header
HTTP/1.1 100 Continue
759
------=_Part_0_1489439555.1434351772642
Content-Id: <26EA5E833E0C746B2FA8C96592EEDB2B>
boundary
MIME part header
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<version soapenv:actor="tpi" soapenv:mustUnderstand="0" xsi:type="soapenc:string"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">1.4.0-b92 built on 2014-09-15 @ 11:13:10</version>
<request-type soapenv:actor="tpi" soapenv:mustUnderstand="0" xsi:type="soapenc:string"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">SMSSUBMIT.REQ</request-type>
</soapenv:Header>
<soapenv:Body>
<tns:SMSSubmitRequest xmlns:tns="http://www.swisscom.com/mb/schema">
CH-3050 Bern
3
Version 4.0
22. June 2015
SOAP part
41/79
<short-id>90087</short-id>
<service-name>SMS-SUB-90087</service-name>
<username>SwisscomBN</username>
<password>ftT45X82</password>
<amount>0.2</amount>
<bill-text>Test SMS Service</bill-text>
<report-address>http://10.234.31.43:18888/report</report-address>
<delivery-report>true</delivery-report>
<transaction-id>tbd</transaction-id>
<content filename="cid:615E30E1E5C908002854EDB821751000.txt"
href="cid:615E30E1E5C908002854EDB821751000"/>
<from>90087</from>
<message-type>SMSSubmitRequest</message-type>
</tns:SMSSubmitRequest>
</soapenv:Body>
</soapenv:Envelope>
------=_Part_0_1489439555.1434351772642
Content-Id: cid:615E30E1E5C908002854EDB821751000
boundary
MIME part header
Hallo, das ist ein Test SMS!
------=_Part_0_1489439555.1434351772642—
attachment
0
boundary
* Submit messages can be transfer-encoding: chunked or content-Length: nnnn
The corresponding response is much simpler without attachments and looks as follows:
HTTP/1.1 200 OK
Content-Type: text/xml
Server: Microsoft-IIS/7.5
Status: 200 OK
X-Powered-By: ASP.NET
Date: Mon, 15 Jun 2015 07:02:52 GMT
Connection: close
Content-Length: 835
HTTP header
<soapenv:Header>
<request-type soapenv:actor="MB" soapenv:mustUnderstand="0" xmlns="">SMSSUBMIT.RESP</request-type>
</soapenv:Header>
<soapenv:Body>
<tns:SMSSubmitResponse xmlns:tns="http://www.swisscom.com/mb/schema">
<state>1000</state>
<state-text>Ok</state-text>
<message-id>129320150615090252702</message-id>
<message-state recipient="41791112233" state="0" state-text="Ok"/>
<message-type>SMSSubmitResponse</message-type>
CH-3050 Bern
3
Version 4.0
22. June 2015
SOAP part
42/79
</tns:SMSSubmitResponse>
</soapenv:Body>
</soapenv:Envelope>
It indicates that the message has been accepted (state = 0) and the recipient is valid. The TransactionID (if
set) corresponds with the values sent with the request.
4.3.3
SMS Delivery Report (Delivery Notifications)
In the case of SMS submissions, Message Broker accepts SOAP invocations based on message (JAXM). Optionally, Message Broker can send Delivery Reports back to the Third Party. They are transmitted as https GET
Request. Therefore, the Message Broker client must be able to accept this kind of requests. This requirement
is sketched in figure below:
Message Broker
http GET
(URL Encoded)
Report
Sender
synchronous
Third Party
Report
Receiver
(MB Client)
http Response
Figure 15: Delivery Reports
Whenever a SMS Report has been requested by a Submit Request, Message Broker will send an appropriate
https GET Request to the provided report address supplying information about the involved message and recipient as well as the type of event in form of URL encoded parameters.
An https GET Request is defined by the following parameters:
Information
Element
Type
Value
Presence
Description
reportType
msgId
String
DELIVERY
Mandatory
Mandatory
Type of report
Identifies this message. The ID is generated by MB
MSISDN as sent with submit request
1 – n (see Table 15: msgState and
msgStateText)
Retrieved
(see Table 15: msgState and
msgStateText)
Mandatory
Identifies involved recipient
Mandatory
Signals status of message
Optional
Explanation text for Message Status. This text is delivered by SMSC
recipient
String 1
String
msgState
Long
msgStateText
String 1
Table 14: https GET request parameter
1
CH-3050 Bern
3
Version 4.0
22. June 2015
43/79
The message is sent as URL encoded https GET Request.Possible msgState and msgStateText within response
message are:
msgState
msgStateText
Description
0
1
2
3
4
5
6
7
Retrieved +[Additional Info, if necessary]
Rejected +[Additional Info, if necessary]
Expired +[Additional Info, if necessary]
Deferred +[Additional Info, if necessary]
Unrecognised +[Additional Info, if necessary]
Indeterminate +[Additional Info, if necessary]
Forwarded +[Additional Info, if necessary]
Unreachable +[Additional Info, if necessary]
Message successful delivered to handset
Message from end customer or system rejected
Message is expired
End customer will start message download later
Handset is not able to recognise the message (e.g. version problem)
Is not known, if message was delivered correctly
End customer has message forwarded without download
End customer not reachable (e.g. network or routing problems)
Table 15: msgState and msgStateText
Notification messages can optionally be sent by Message Broker to inform the Third Party about events in
the SMSC. The notification message is formatted as https GET.
Error messages and reason codes in notifications from SMSC with 3 digits (for more details see UCP EMI
spec.) are shown in msgStateText in brackets []. This error codes are only in SMS Delivery Notifications available because the SMS message flow is “store and forward” (MMS reason codes are shown within MMS
Submit Response message).
Possible SMSC codes within msgStateText in response message are:
SMSC Reason Code
Description
000
Unknown subscriber
001
Service temporary not available
002
003
004
005
006
007
008
009
Illegal error code
010
Network time-out
100
Facility not supported
101
Unknown subscriber
102
Facility not provided
103
Call barred
104
Operation barred
105
SC congestion
106
Facility not supported
107
Absent subscriber
108
Delivery fail
109
Sc congestion
110
Protocol error
111
MS not equipped
112
Unknown SC
113
SC congestion
114
Illegal MS
CH-3050 Bern
3
Version 4.0
22. June 2015
44/79
115
MS not a subscriber
116
Error in MS
117
SMS lower layer not provisioned
118
System fail
119
PLMN system failure
120
HLR system failure
121
VLR system failure
122
Previous VLR system failure
123
Controlling MSC system failure
124
VMSC system failure
125
EIR system failure
126
System failure
127
Unexpected data value
200
Error in address service centre
201
Invalid absolute Validity Period
202
Short message exceeds maximum
203
Unable to Unpack GSM message
204
Unable to convert to IRA ALPHABET
205
Invalid validity period format
206
Invalid destination address
207
Duplicate message submit
208
Invalid message type indicator
Table 17: SMSC error messages and reason codes
CH-3050 Bern
3
Version 4.0
22. June 2015
45/79
Example GET Request (MBS  Third Party):
GET /report?reportType=DELIVERY&msgId=129320150615090252702&recipient=41791112233&msgState=0&msgStateText=Retrieved
HTTP/1.1
accept: */*
accept-charset: utf-8
Via: HTTP/1.0 10.222.38.200:9000
Connection: close
Host: 10.234.31.43:18888
Example Response (Third Party  MBS):
HTTP/1.1 200 OK
Content-Type: text/html; charset=iso-8859-1
Connection: close
<html><body>successful</body></html>
Possible https Responses are:


successful
failed
It is important to analyze the Delivery Notifications. Only these notifications can give you the
overview about successful delivered messages in order to create meaningful statistics.
CH-3050 Bern
3
Version 4.0
22. June 2015
46/79
4.3.4
Binary Message (only for Nokia Handset)
Binary messages may be received or sent over the SMS deliver or submit interfaces. The parameter nokiabinary-port must be present in the TPI parameter field. Binary data is hex-encoded. If the message in content
field is too long for a single message, the Enabling Platform sends it in several parts towards SMSC.
The following ports are common in use:
Description
Port (hexadecimal) of a Nokia handset
Operator Logo
1582
Graphic
1583
Ringtone
1581
Pictures
158A
VCard
E2
Table 18: Nokia binary ports
If the parameter nokia-binary-port is used, you have also to set parameter is-text to FALSE.
The parameter nokia-binary-port allows sending binary messages, such as logos and ringtones to Nokia handsets only. To send binary messages to other handset brands, refer to
next chapter.
4.3.5
Binary SMS (for Handsets which supports EMS)
4.3.5.1 EMS Message
EMS (Enhanced Messaging Service) is a compatible enhancement to SMS. The open EMS standard has been
defined by several mobile phone manufactures due to the success story of ringing tones and logos. EMS
supports formatted text, animation, calendar, business cards, tones and pictures. Single colored pictures
with 16 × 16 or 32 × 32 pixels can be transported and processed in the mobile phone. Computer pictures can
be a multiple of 8 pixels wide and up to 1024 Pixel high whereas the relation width × height may not exceed
1024 pixels. Picture sequences can be composed of 6 single pictures at 32 × 32 pixels or, created in the mobile phone, of 4 pictures at 16 × 16 pixels. Tones can be span three octaves from c to ++b and last as long as
150, 225, 300 or 450 ms. Up to 80 tones are allowed. EMS is a 3GPP standard and includes notation by the
“iMelody” and IrDA (Infrared Data Association) standard.
EMS is transported via SMS and can consist of up to 255 SMS at 140 Bytes each. The binary EMS information
is stored in the UDH (User Data Header) which defines the position and type (tone, picture, animation etc.).
In case of multiple SMS, EMS includes the UDH field the information on how to reconstruct the EMS in the
mobile phone.
CH-3050 Bern
3
Version 4.0
22. June 2015
47/79
If a message is HEX coded and defined by UDH, DCS etc. TP must take care of defining messages because
each handset has another behavior.
CH-3050 Bern
3
Version 4.0
22. June 2015
48/79
4.3.5.2 Unicode encoded SMS
Unicode provides a unique number for every character, no matter what the platform, no matter what the
program, no matter what the language. Unicode is required by modern standards such as XML, Java,
ECMAScript (JavaScript), LDAP, CORBA 3.0, WML, etc., and is the official way to implement ISO/IEC 10646. It is
supported in many operating systems, all modern browsers, and many other products. The emergencies of
the Unicode standard, and the availability of tools supporting it, are among the most significant recent
global software technology trends.
SMS Business Numbers supports EMS and Unicode SMS in order to send:


binary messages to all handset brands
picture and text combined in the same message
To send an EMS message or a Unicode encoded SMS the SMS Submit Request parameters UDH (User Data
Header), DCS (Data Coding Scheme) and IsText must be set in the parameter field in one of the following
combination:



IsText and UDH
IsText and DCS
IsText, UDH and DCS
Because EMS depends on the manufacturer as well as the model of the mobile phone, the
Third Party must inform the end user before selling any EMS.
CH-3050 Bern
3
Version 4.0
22. June 2015
49/79
4.4 MMS Services
The request is transmitted as https in a XML/SOAP format to a server at the Third Party. For each request, a
new connection is opened. The Third Party may implement any of a range of common techniques (CGI,
servlet, etc.) to service the request.
The MB is able to receive and process MMS Submit Requests from the Third Parties and send them further to
the MMSC (if TP has a subscription for this service). Similarly, it may receive MMS Deliver Requests from the
MMSC and forward them further to the Third Parties.
For MMS submission, the Third Party sends a MMS Submit Request to the MB, which translates it into a request accepted by MMSC. The latter parses and checks the received request, and replies with a response. MB
translates this response back into a MMS Submit Response and sends it synchronously to the Third Party.
To deliver a MMS to the Third Party, MB receives a message from MMSC and appends a request to a message queue. MB extracts the message from the queue, translates it into a MMS Deliver Request and sends it
to the Third Party. Therefore the latter must implement a web service in order to be able to receive MMS Deliver Request from MB. Upon receipt of a MMS Deliver Request, the Third Party must return a MMS Delivery
Response synchronously.
The SOAP messages exchanged between MB and Third Party are described in the remaining of this chapter.
However, the interface between MB and MMSC is purely internal and is thus not be detailed in this document.
4.4.1
MMS Deliver (MB  Third Party)
Via the MMS deliver interface is the Third Party able to receive MMS from end customer, which he sent to
Third Parties short ID. Within this MO MMS the content can be one or more supported files (e.g. jpg, smil,
midi, amr, txt, etc.).
The Third Party interface (TPI) is a web service which is based on SOAP. The data exchange is formatted with
XML. The transport is made with https. This enables to have a synchronous request – response behavior.
In case of MO MMS the MB sends a Deliver Request to the Third Party’s TPI Client.
MB can send MMS delivery requests to a Third Party in the form of SOAP messages. Therefore it expects the
MB client to implement a message based web service. On receipt of a MMS Deliver Request, the MB client
must return a MMS Deliver Response. This process is described in the following figure:
4.4.1.1 MMS Deliver Request (MB  Third Party)
In order to receive MMS Deliver Requests, the Message Broker client must accept https requests containing
one well formed SOAP envelope and zero or more attachments
CH-3050 Bern
3
Version 4.0
22. June 2015
50/79
Deliver Request
Message Broker
Third Party
SOAP (synchronous)
Deliver Response
Figure 16: MMS Deliver Request from MB to Third Party
Possible MMS Deliver Request parameters are:
Information
Element /
SOAP Tag
Type
Value
transaction-id
String 1
message-type
String 1
tpi-version
String 1
MMSDeliverRequest
1
Presence
Description
MM7
Name
Mandatory
Mandatory
The identification of Deliver Request and Deliver Response
pair
Identifies this message as a MMS Deliver Request
Mandatory
Identifies the version of the interface
Transaction ID
Message
Type
n.a.
Optional
Identifier that may be used by the Third Party in a subsequent
MMSSubmit
The address of the MMS originator
linked-id
String
from
String 1
recipient
String 1
date-time
Date 2
priority
String 1
subject
String 1
language
String 3
de, en, ?, fr, it
Optional
handset-brand
String 1
handset-model
String 1
e.g. Sony Ericsson
e.g. K750i
handset-tac
String 1
e.g. 356552
handset-snr
String 1
handser-svn
1
41796598872
Mandatory
Mandatory
UTC formatted
Mandatory
Optional
Optional
The address(es) of the intended recipients of the subsequent
processing by the Third Party or the original recipient address(es). It is possible to mark an address to be used only for
informational purposes
The time and date of the submission of the MMS (time
stamp)
The priority (importance) of the message, like used in a normal e-mail
The title of the whole MMS. Max. 40 characters
Linked ID
Sender address
Recipient
address
Date and
time
Priority
Subject
n/a
Optional
The used language (two characters). Or ? (language in SIS unknown)
Handset manufacturer
Optional
Handy model
n/a
Optional
TAC Code (part of IMEI) Type approval code
n/a
e.g. 724445
Optional
Handsets serial number
n/a
e.g. 05
Optional
Version of handset software
n/a
n/a
Madatory
n/a
Optional
Identifies the version of the interface supported by the MMS
Relay/Server
Identifier of the MMS Relay/Server
n/a
Optional
In case of reply-charging when the reply MMS is submitted
within the MM7_deliver.REQ this is the identification of the
original MMS that is replied to
MM7 version
MMS Relay/Server
ID
ReplyChargingID
SOAP attachment (String)
Optional
The content of the multimedia message (in the same format,
as it is received from MMSC)
Content
no, 2.00,
amount ok,
amount low
Optional
Information about Prepaid customer balance
n/a
content
balance-check
String
HREF Attribut
Filename
String 1
n/a
Table 19: MMS Deliver Request parameter
1
CH-3050 Bern
3
Version 4.0
22. June 2015
51/79
2
CH-3050 Bern
3
Version 4.0
22. June 2015
52/79
4.4.1.2 MMS Deliver Response (Third Party  MB)
A MMS Deliver Response must be sent by the Third Party in response to a MMS Deliver Request. A response
is either represented by an https response containing one well formed SOAP envelope for the JAXM service
[9].
A MMS Deliver Response is defined by the following parameters:
Information Element
Type
transaction-id
message-type
state
state-text
tpi-version
service-category
Presence
Description
MM7
Name
String 1
Mandatory
String 1
MMSDeliverResponse
Integer
see Table 21: Possible Request Status in
MMS Deliver Response
see Table 21: PosString 1
sible Request Status in
MMS Deliver Response
Mandatory
The identification of the Deliver Request and Deliver
Response pair
Identifies this message as a MMS Deliver Response
Mandatory
Status of the completion of the request.
Transaction
ID
Message
type
Request
Status
Optional
Text description of the status for display purposes,
should qualify the Request Status
Request
Status text
String 1
Mandatory
Version of the TPI Interface
n/a
Optional
Information supplied by the Third Party which may be
included in charging information. The syntax and semantics of the content of this information are out of
the scope of this specification.
n/a
String
Value
1
Table 20: MMS Deliver Response parameter
1
Possible request states (coming also from MMSC) within response message are:
Status Code
Status Text
Meaning
1000
1100
Success
Partial success
2000
2001
2002
Client error
Operation restricted
Address Error
2003
Address Not Found
2004
Multimedia content refused
This code indicates that the request was executed completely
This code indicates that the request was executed partially but some parts of the request
could not be completed. Lower order digits and the optional Details element may indicate
what parts of the request were not completed.
Client made an invalid request
The request was refused due to lack of permission to execute the command
The address supplied in the request was not in a recognized format or the MMS Relay/Server ascertained that the address was not valid for the network because it was determined not to be serviced by this MMS Relay/Server. When used in response-result, and
multiple recipients were specified in the corresponding push submission, this status code
indicates that at least one address is incorrect.
The address supplied in the request could not be located by the MMS Relay/Server. This
code is returned when an operation is requested on a previously submitted message and
the MMS Relay/Server cannot find the message for the address specified
The server could not parse the MIME content that was attached to the SOAP message and
indicated by the Content element or the content size or media type was unacceptable
CH-3050 Bern
3
Version 4.0
22. June 2015
53/79
Status Code
Status Text
2005
Message ID Not found
2006
2007
3000
3001
3002
3003
4000
4001
4002
4003
4004
4005
4006
4007
Meaning
This code is returned when an operation is requested on a previously submitted message
and the MMS Relay/Server cannot find the message for the message ID specified or when
the Third Party receives a report concerning a previously submitted message and the message ID is not recognized
LinkedID not found
This code is returned when a LinkedID was supplied and the MMS Relay/Server could not
find the related message
Message format corrupt
An element value format is inappropriate or incorrect
Server Error
The server failed to fulfill an apparently valid request
Not Possible
The request could not be carried out because it is not possible. This code is normally used
as a result of a cancel or status query on a message that is no longer available for cancel
or status query. The MMS Relay/Server has recognized the message in question, but it
cannot fulfil the request because the message is already complete or status is no longer
available
Message rejected
Server could not complete the service requested
Multiple addresses not supported The MMS Relay/Server does not support this operation on multiple recipients. The operation may be resubmitted as multiple single recipient operations
General service error
The requested service cannot be fulfilled
Improper identification
Identification header of the request does not uniquely identify the client (either the VASP
or MMS Relay/Server)
Unsupported version
The version indicated by the MM7 Version element is not supported
Unsupported operation
The server does not support the request indicated by the MessageType element in the
header of the message
Validation error
The SOAP and XML structures could not be parsed, mandatory fields are missing, or the
message-format is not compatible to the format specified. Details field may specify the
parsing error that caused this status
Service error
The operation caused a server (either MMS Relay/Server or Third Party) failure and should
not be resent
Service unavailable
This indication may be sent by the server when service is temporarily unavailable, e.g.
when server is busy
Service denied
The client does not have permission or funds to perform the requested operation
Table 21: Possible Request Status in MMS Deliver Response
4.4.1.3 Example in case of MMS Deliver:
In case of MMS Deliver, the Message Broker issues a SOAP (JAXM [9]) Request as shown in the following table:
POST / deliver HTTP/1.1
Content-Type: multipart/related; boundary=557e7989
Accept: */*
Accept-charset: utf-8
SOAPAction: SMSDeliverRequest
Via: HTTP/1.0 10.222.38.200:9000
Host: 10.234.31.43:18888
Connection: close
--557e7989
Content-Id: 3
CH-3050 Bern
3
HTTP header
boundary
MIME part header
Version 4.0
22. June 2015
54/79
<soapenv:Header>
<request-type soapenv:actor="MB" soapenv:mustUnderstand="0" xmlns="">MMSDELIVER.REQ</request-type>
</soapenv:Header>
<soapenv:Body>
<tns:MMSDeliverRequest xmlns:tns="http://www.swisscom.com/mb/schema">
<transaction-id>sQhLezzYw3Grb8mW8ZuJ52@mms.natel.ch</transaction-id>
<tpi-version>1.4.0-b92</tpi-version>
<from>41791112233</from>
<date-time>2015-06-15T07:06:49Z</date-time>
<content filename="0.smil" href="0"/>
<content filename="text_0.txt" href="1"/>
<content filename="IMG_8645.jpg" href="2"/>
<message-type>MMSDeliverRequest</message-type>
<subject>Mdu</subject>
</tns:MMSDeliverRequest>
</soapenv:Body>
</soapenv:Envelope>
--557e7989
Content-Type: application/smil
Content-Transfer-Encoding: 7bit
Content-Id: <0>
SOAP part
boundary
MIME part header
<smil>
<head>
<layout>
<root-layout/>
<region id="Text" top="70%" left="0%" height="30%" width="100%" fit="scroll"/>
<region id="Image" top="0%" left="0%" height="70%" width="100%" fit="meet"/>
</layout>
</head>
<body>
<par dur="10s">
<text src="text_0.txt" region="Text"/>
</par>
<par dur="10s">
<img src="IMG_8645.jpg" region="Image"/>
</par>
</body>
</smil>
--557e7989
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Content-Disposition: Attachment ;Filename="text_0.txt";Charset=us-ascii
Content-Id: <1>
Content-Location: text_0.txt
###### binary data ######
--557e7989-*
Deliver messages are always chunked encoded. That’s why there are numbers between the message parts.
attachment
boundary
MIME part header
attachment
boundary
The Third Party returns a response in the following form:
CH-3050 Bern
3
Version 4.0
22. June 2015
55/79
HTTP/1.1 200 OK
Connection: close
HTTP header
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"><soapenv:Header><version soapenv:actor="tpi" soapenv:mustUnderstand="0" xsi:type="xsd:string">1.4.0-b92
built on 2014-09-15 @ 11:13:10</version><request-type soapenv:actor="tpi" soapenv:mustUnderstand="0"
xsi:type="xsd:string">MMSDELIVER.RESP</request-type></soapenv:Header><soapenv:Body><tns:MMSDeliverResponse
xmlns:tns="http://www.swisscom.com/mb/schema">
<transaction-id>sQhLezzYw3Grb8mW8ZuJ52@mms.natel.ch</transaction-id>
<state>1000</state>
<state-text>Success</state-text>
<message-type>MMSDeliverResponse</message-type>
</tns:MMSDeliverResponse></soapenv:Body></soapenv:Envelope>
SOAP part
* Deliver Responses can be chunked encoded.
It indicates that the message has been accepted (state = 0) and the recipients is valid. The TransactionID corresponds with the values sent with the request.
4.4.2
MMS Submit (Third Party  MB)
The Enabling Platform receives a SMS or MMS user request and forwards it via the SMS or MMS interface to
the Third Party. Content to answer the request is supplied by the Third Party via the MMS interface. The Enabling Platform generates a MMS and sends it back to the end customer. At the same time, a billing record is
created so that the information service can be charged.
MMS Submit is based on MMSC’s MM7 Interface. But it’s not exactly the same. The TPI Interface has additional parameters that are needed for e.g. billing. There are other MM7 parameters within the TPI Interface
missing because the Message Broker will take care of it.
In the case of MMS submissions, Message Broker accepts SOAP invocations based on message (JAXM). Optionally, Message Broker can send Delivery Reports back to the Third Party if this is supported by MMSC. They
are transmitted as https GET Request. Therefore, the Message Broker client must be able to accept this kind
of requests.
CH-3050 Bern
3
Version 4.0
22. June 2015
56/79
4.4.2.1 MMS Submit Request (Third Party  MB)
Submit Request
SOAP (synchronous)
Message Broker
Submit Response
Third Party
Report (Delivered/Read)
HTTP get
Response
Figure 17: MMS Submit Request from Third Party to MB
A request is either represented by an https. Request containing one well formed SOAP envelope and zero or
more attachments for the JAXM service [9].
Possible MMS Submit Request parameters are:
Information
Element /
SOAP Tag
Type
Value
Presence
Description
short-id
Integer
Short ID
Mandatory
VAS ID
service-name
String 3
Mandatory
username
String 3
Mandatory
password
String 3
Mandatory
Password for authentication
n/a
recipient
String 3
Max. length: 160
Characters
Max. length: 160
Characters
Max. length: 160
Characters
MSISDN in international Format:
41796598872 or
+41796598872 or
Client
Together with ServiceName selection parameters for used
service
Together with ShortID selection parameters for used service
User name for accessing service
The address of the to, cc or bcc recipient destination(s).
There can be up to 5 MSISDN (service addicted).
bcc: every recipient sees only his MSISDN. An Attribut
(to,cc,bcc) defines if the MSISDN belongs to the to, cc or
bcc Field
Recipient address
content
HREF Attribut
Filename1
Mandatory/Optional
at least one
of to, cc or
bcc recipient
has to be
present
Optional
MIME-Type. The content type of the MMS content included as attachment. The following types are supported:
Content
SOAP attachment
(String)
MM7 Name
Service Code
n/a
MMS: application/vnc.wap.mms-message
SMIL: application/smil
Image: image/gif
image/jpeg
image/vnd.wap.wbmp
Audio: audio/amr
text/x-imelody
Text: text/plain (Text file must be UTF-8 encoded!) If
charset is missing, the default parameter
'charset="utf-8"' will now be added to the contenttype header of each message part of type 'text/*' of
a multipart
CH-3050 Bern
3
Version 4.0
22. June 2015
57/79
Information
Element /
SOAP Tag
Type
Value
Presence
Description
MM7 Name
Video: video/3gpp
video/mpeg
from
String 3
subject
amount
String 3
Double
charge
Integer
0 to 999
Optional
bill-text
String 3
Mandatory
time-of-expiry
earliestdelivery-time
originator-url
report-address
Date 2
Date 2
Max. length: 31
characters
UTC formatted
UTC formatted
String 3
String 3
https://host:port
https://host:port
Optional
Optional
delivery-report
service-class
Boolean
String 3
true / false
Optional
Optional
priority
transaction-id
String 3
String 3
low / normal / high
1–n
Optional
Mandatory
message-type
String 3
Mandatory
distributionindicator
Boolean
MMSSubmitRequest
true / false
linked-id
String 3
allowadaption
servicecategory
tax-rate
Boolean
tpi-version
n/a
n/a
n/a
String 3
-9999.9999 to
+9999.9999
Double
Mandatory
Optional
Optional
Optional
Optional
Optional
Optional
true / false
String 3
CH-3050 Bern
3
888
Optional
Optional
8.0
Optional
Mandatory
These are examples. All known and allowed MIME types
are possible. (It is possible to send SMIL and Attachments
together within the Content-Field)
Identification of sender. A string indicating the originating
sender (originator). Default value will be the short ID.
Max. 99 characters (only 7-bit GSM ASCII)
The title of the whole message. max. 40 characters
Amount to be billed to customer. Unit is in CHF.
Either charge or amount must be set. If none is defined,
message will be rejected. If both are defined, message will
be rejected.
The Message Broker supervisor can define a minimum and
maximum amount.
Billrate, billing code
Either charge or amount must be set. If none is defined,
message will be rejected. If both are defined, message will
be rejected.
The Message Broker supervisor can limit the valid range of
charge values.
The value of the field will be printed on the invoice.
(billtext)
The desired time of expiry for the message.
The earliest desired time of delivery of the Message to the
recipient.
Originator's URL, optional information
The URL of the listening TP server. Required if reports requested.
Flag indicating if delivery reports are requested
Class of the MMS according MM7. (e.g. advertisement, informational, personal) Used like in an e-mail
MM7 Parameter, function used like in an e-mail
Transaction ID determined by TP. The same transaction ID
will be present in the response
Type of the message
DRM Flag: If set to „false“ the Third Party has indicated
that content of the MM is not intended for redistribution.
If set to „true“ the Third Party has indicated that content
of the MMS can be redistributed
This identifies a correspondence to a previous valid message delivered to the Third Party
Indicates if Third Party allows adaption (transcoding) of
the content (default „true“ = transcode)
Defines the Service category e.g. Sports, News, Adult, Chat,
etc.
Third Party defines the tax rate in % (0, 2.5 or 8.0) for this
content
Defines the version of the used TPI
Version 4.0
22. June 2015
Sender address
Subject
n/a
n/a
n/a
Time of Expiry
Earliest delivery
time
n/a
n/a
Delivery report
Message class
Priority
Transaction ID
Message type
Message Distribution Indicator
Linked ID
Adaptions
n/a
n/a
n/a
MM7 version
VASP ID
Date and time
58/79
Information
Element /
SOAP Tag
Type
Value
Presence
Description
n/a
MM7 Name
Reverse charging
Charged Party
n/a
Table 22: MMS Submit Response parameter
1
The SMIL property and the attachments must be added as MIME multipart attachment and referenced via Content ID in the content
field. They will be transported as MIME BodyParts of the https request.
2
3
4.4.2.2 MMS Submit Response (MB  Third Party)
Every request results either in a fault condition (Exception or SOAP fault element) or in a valid response object/SOAP structure. A response is either represented by an https response containing one well formed SOAP
envelope for the JAXM service [9].
A MMS Submit Response is defined by the following parameters:
Information Element / SOAP
Tag
Type
transaction-id
String
state
Integer
state-text
String 1
message-type
message-id
message-state
String
String
Message
Status
Value
Presence
Description
Mandatory
states
states
Mandatory
Transaction ID determined by Third Party. The same transaction
ID will be present in the response
Signals success or failure for this request.
Mandatory
An explanation text for request status.
MMSSubmitResponse
Mandatory
Mandatory
Optional
Identifies this message
Identifies this message
Array of MessageStatus described in the following table. Items
corresponding to each addressed recipient. Message-state is not
present in case of a failed request (state not 1000)
seeTable 24: Messagestate parameter in array
Table 23: MMS Submit Response parameter
1
CH-3050 Bern
3
Version 4.0
22. June 2015
59/79
In the message-state fields there is one entry for each recipient. The structure contains 3 attributes (see Table 24: Message-state parameter in array).
The message-state is defined by the following parameters (array):
Information Element /
SOAP Tag
message-state
Type
Value
Presence
Description
recipient
String
Mandatory
Identifies one single message
state
Integer
Mandatory
Status of the message for this specific recipient
state-text
String
MSISDN as it was defined
in the request
Mandatory
Explanation text for message status
1
Table 24: Message-state parameter in array
1
Strings are Unicode based and must be UTF-8 encoded. Theoretical length up to 65536 characters if there
are no other limitations.
Possible request states within MMS Submit response message are:
State
State-text
Description
1000
2101
2102
2103
2104
2107
2108
2109
2110
2111
2112
2113
2120
2123
2124
2125
2126
2127
2130
2150
3101
3102
3103
3104
3150
4101
Ok
Short ID unknown +[Additional Info, if necessary]
Format error +[Additional Info, if necessary]
Authentication failed +[Additional Info, if necessary]
Value outside allowed limits +[Additional Info, if necessary]
Too large content size. +[Additional Info, if necessary]
No attachment. +[Additional Info, if necessary]
Unsupported MIME type. +[Additional Info, if necessary]
Unknown service. +[Additional Info, if necessary]
Less MSISDN for Bulk Service +[Additional Info, if necessary]
Service type does not match +[Additional Info, if necessary]
MMS Bulk message id +[Additional Info, if necessary]
Billing data error +[Additional Info, if necessary]
Amount out of bound +[Additional Info, if necessary]
Charge out of bound +[Additional Info, if necessary]
Amount format invalid +[Additional Info, if necessary]
Charge format invalid +[Additional Info, if necessary]
Tax rate not valid +[Additional Info, if necessary]
Too many recipients +[Additional Info, if necessary]
Plain MSISDN not allowed +[Additional Info, if necessary]
Internal server errors +[Additional Info, if necessary]
DB access error +[Additional Info, if necessary]
IO error +[Additional Info, if necessary]
Server configuration error +[Additional Info, if necessary]
Participating system errors +[Additional Info, if necessary]
Request limit exceeded +[Additional Info, if necessary]
Transaction ok
Short ID (ServiceGroup) undefined for this request
Request could not be parsed (e.g. SOAP or TPI format fault)
Unknown username or invalid password
Value exceeded defined max. value
Content size is bigger then allowed
MMS submit contains no attachment
MIME type unknown or not supported
Service is not configured
MMS Bulk submit does not contain enough MSISDNs
Service found but provisioned service type does not match
MMS Bulk continuation submit refers to an unknown message id
General billing error
Amount out of bound
Charge out of bound
Amount format invalid
Charge format invalid
Unknown tax rate
Maximum number of recipients exceeded
Service does not allow clear-text MSISDNs
An internal server error occurred
The system database could not be accessed
The communication with a transport system failed
Server configuration contains an invalid element
A participating system returned a non-recoverable error
A limit on the service or system level was exceeded
Table 25: Request states
The message-state text field is an informative field that gives more information about the reason of the rejection/failure.
CH-3050 Bern
3
Version 4.0
22. June 2015
60/79
Possible message-state and state-text (message, content) within response message:
State
State-Text
Description
0
2
4
Ok
Invalid MSISDN Format
NO_SCMN No Swisscom mobile customer
4
4
4
TMP_REJ Temporarily rejected customer
ALL_PREMIUM_SCM all premium services
blocked, set by SCM
ALL_PREMIUM_CUST all premium services
blocked, set on customers demand
ADULT_PREMIUM_SCM adult content services
blocked, set by SCM
ADULT_PREMIUM_CUST adult content services blocked, set on customers demand
REACHED_SCM limit reached, set by SCM
REACHED_CUST limit reached, set on customers demand
ADULT_PREMIUM_AGE age verification not
passed
ADULT_PREMIUM_AGE age infomation not
available
ADULT_PREMIUM_AGE age verification failed
BLOCKED_MSISDN this MSISDN is not allowed
to use this service
ERR_DST Invalid destination
This MSISDN is valid and has no blocking
Format of Recipient is invalid
This MSISDN does not belong to a Swisscom customer and must be removed
from any subscription database
This customer is temporarily bared in the Swisscom network
The customer is not allowed to use SMS premium services (activated by
Swisscom)
use SMS premium services
The customer is not allowed to use adult SMS premium services (activated by
Swisscom)
use adult SMS premium services
The customer reached the monthly limit (set by Swisscom)
The customer reached the monthly limit (set by the owner of the subscription)
4
SIS N/A
4
Invalid MSISDN
4
Invalid Customer
4
4
DRM_FL DRM Forward Lock is not supported
by customer
DIAMETER_LIM_RE amount limit reached
4
4
4
DIAMETER Invalid Customer
DIAMETER_ERROR error
[Additional Info, if necessary]
4
4
4
4
4
4
4
4
4
Subscriber age <16 years or not passed
Age information not available
Age verification failed
MSISDN, which is not allowed to use this service
The destination is not a standard mobile number (MSISDN) or belongs to a
foreign network
Validation of MSISDN is not possible, because the validation server (SIS) is not
available at the moment and service is set to pessimistic behavior
MSISDN is not valid (amount of digits or invalid number range) or a non
Swisscom customer
This MSISDN does not belong to a Swisscom customer or is inactive and must
be removed from any subscription database
End customers handset does not support DRM Forward Lock (in this section
only for MMS available)
Prepaid Customer has his credit limit reached or no balance on his account (in
this section only for MMS available)
Invalid or unknown prepaid customer (in this section only for MMS available)
All other Diameter errors
Free configurable message text, for a few errors (e.g. Discovered non numeric
char)
Table 26: Message-states
Example message-state:
The message-state field contains the recipient, state and state-text information.
<state xsi:type="xsd:int">1000</state>
(-------------------- Request State)
<state-text xsi:type="xsd:string">Ok.</state-text>
(-------------------- Request State)
<message-state recipient="+41787408343" state="4" state-text=" NO_SCMN No Swisscom mobile customer "/>
<message-state recipient="14DBDFCC9CE40ACB9" state="2" state-text=" Invalid MSISDN Format "/>
CH-3050 Bern
3
Version 4.0
22. June 2015
61/79
The request status text field explains the request status. This field contains informative information only. It should not be used for processing. It provides more detailed information to
assist eventual problem investigation.
4.4.2.3 Example JAXM Submit (send an Object, WSDL is not needed)
The easiest way to communicate with the Enabling Platform is by using the provided Java client framework.
If the Third Party is unable to use this Java code, one can compose a SOAP request as follows using any programming language.
POST /submit HTTP/1.1
Content-Type: multipart/related; type="text/xml"; start="<7A704DDAC885503EDDA34FC8CB131275>"; .boundary="---=_Part_1_175152510.1434453385664"
SOAPAction: ""
User-Agent: Axis/1.4
Host: 10.222.38.200:16100
Expect: 100-continue
Transfer-Encoding: chunked
HTTP header
HTTP/1.1 100 Continue
8de
------=_Part_1_175152510.1434453385664
boundary
Content-Id: <7A704DDAC885503EDDA34FC8CB131275>
MIME part header
<?xml version="1.0" encoding="UTF-8"?><soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<version soapenv:actor="tpi" soapenv:mustUnderstand="0" xsi:type="soapenc:string"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">1.4.0-b92 built on 2014-09-15 @ 11:13:10</version>
<request-type soapenv:actor="tpi" soapenv:mustUnderstand="0" xsi:type="soapenc:string"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">MMSSUBMIT.REQ</request-type>
</soapenv:Header>
<soapenv:Body>
<tns:MMSSubmitRequest xmlns:tns="http://www.swisscom.com/mb/schema">
<short-id>90087</short-id>
<service-name>MMS-SUB-90087</service-name>
<username>SwisscomBN</username>
<password>dm81T5mG</password>
<amount>0.1</amount>
<bill-text>Test MMS</bill-text>
<report-address>http://10.234.31.43:18888/report</report-address>
<delivery-report>true</delivery-report>
<content filename="mms_1140_bild.gif" href="cid:4E81991130DC4000458B9DCFD451A800"/>
<content filename="mms_1140_logo.jpg" href="cid:454124468F468000615702DD7A4DC400"/>
<content filename="mms_1140_text_1.txt" href="cid:2978CD18F96CC0015C6DB079F3C2000"/>
<content filename="mms_1140_text_2.txt" href="cid:558048F80DE17800111459036065B000"/>
<content filename="s.smil" href="cid:14CA1F90C9804C0032D467812FBE8400"/>
<from>90087</from>
CH-3050 Bern
3
Version 4.0
22. June 2015
SOAP part
62/79
<recipient field="bcc">41791112233</recipient>
<message-type>MMSSubmitRequest</message-type>
<read-report>true</read-report>
<subject>MMS mit Smil</subject>
<service-class/>
<distribution-indicator>true</distribution-indicator>
<bulk-indicator/>
</tns:MMSSubmitRequest>
</soapenv:Body>
</soapenv:Envelope>
209c
------=_Part_1_175152510.1434453385664
Content-Type: image/gif
Content-Id: cid:4E81991130DC4000458B9DCFD451A800
boundary
MIME part header
attachment
------=_Part_1_175152510.1434453385664
Content-Type: image/jpg
Content-Id: cid:454124468F468000615702DD7A4DC400
boundary
MIME part header
attachment
------=_Part_1_175152510.1434453385664
Content-Id: <cid:2978CD18F96CC0015C6DB079F3C2000>
boundary
MIME part header
Überraschen Sie Verwandte und Freunde mit einem Ostergruss oder einem Frühlingsbild per MMS. Wir schenken Ihnen 2x
10 Gratis-MMS!
------=_Part_1_175152510.1434453385664
Content-Id: cid:558048F80DE17800111459036065B000
attachment
boundary
MIME part header
Sie können 10 MMS im April und 10 MMS im Mai kostenlos im Inland versenden (ohne Anmeldung).
Falls Sie kein eigenes MMS knipsen möchten, finden Sie eine Auswahl kostenloser Osterbilder unter diesem Link:
http://live.swisscom.ch/
attachment
Nicht genutzte MMS verfallen. Gültig für nationale MMS (exkl. MMS-Mehrwertdienste und Versand an Kunden ausl. Netzbetreiber).
swisscom.ch
------=_Part_1_175152510.1434453385664
Content-Type: application/smil
Content-Id: cid:14CA1F90C9804C0032D467812FBE8400
boundary
MIME part header
<smil><head><layout>
<root-layout background-color="#ffffff" backgroundColor="#ffffff" height="320" width="240"/>
<region fit="meet" height="320" id="logo" left="0" top="0" width="239"/>
<region fit="meet" height="166" id="anim" left="0" top="0" width="240"/>
<region fit="scroll" height="100%" id="text" left="0" top="134" width="100%"/>
CH-3050 Bern
3
Version 4.0
22. June 2015
attachment
63/79
<region fit="scroll" height="100%" id="textend" left="0" top="0" width="100%"/>
</layout>
</head>
<body>
<par dur="4000ms">
<img region="logo" src="mms_1140_LOGO.jpg"/>
</par>
<par dur="8000ms">
<img region="anim" src="mms_1140_BILD.gif"/>
<text region="text" src="mms_1140_TEXT_1.txt"/>
</par>
<par dur="12000ms">
<text region="textend" src="mms_1140_TEXT_2.txt"/>
</par>
</body>
</smil>
------=_Part_1_175152510.1434453385664—
boundary
0
* Submit Messages can be transfer encoding: chunked or content length: nnnn.
The corresponding response is much simpler without attachments and looks as follows:
HTTP/1.1 200 OK
Content-Type: text/xml
Server: Microsoft-IIS/7.5
Status: 200 OK
X-Powered-By: ASP.NET
Date: Tue, 16 Jun 2015 11:16:25 GMT
Connection: close
HTTP header
<soapenv:Header>
<request-type soapenv:actor="MB" soapenv:mustUnderstand="0" xmlns="">MMSSUBMIT.RESP</request-type>
</soapenv:Header>
<soapenv:Body>
<tns:MMSSubmitResponse xmlns:tns="http://www.swisscom.com/mb/schema">
<state>1000</state>
<state-text>Ok</state-text>
<message-id>vQhLezzYw3Grc7EOlnqB10@mms.natel.ch</message-id>
<message-state recipient="41791111111" state="4" state-text="NO_SCMN No Swisscom mobile customer"/>
<message-type>MMSSubmitResponse</message-type>
</tns:MMSSubmitResponse>
</soapenv:Body>
</soapenv:Envelope>
SOAP part
It indicates that the message has been accepted (state = 0), two recipients were valid and one isn’t valid. The
TransactionID (if set) corresponds with the values sent with the request.
CH-3050 Bern
3
Version 4.0
22. June 2015
64/79
4.4.3
MMS Delivery Reports (Delivery Notifications)
In the case of MMS submissions, Message Broker accepts SOAP invocations based on message (JAXM). Optionally, Message Broker can send delivery reports back to the Third Party if this is supported by MMSC. They
are transmitted as https GET Request. Therefore, the Message Broker client must be able to accept this kind
of requests. This requirement is sketched in figure below:
Message Broker
http GET
(URL Encoded)
Report
Sender
synchronous
Third Party
Report
Receiver
(MB Client)
http Response
Figure 18: MMS Delivery Reports
Whenever a report has been requested by a Submit Request, Message Broker will send an appropriate https
GET Request to the provided report address supplying information about the involved message and recipient
as well as the type of event in form of URL encoded parameters.
An https GET Request is defined by the following parameters:
Information
Element
Type
Value
Presence
Description
reportType
String 1
DELIVERY
Mandatory
Type of report
msgId
String 1
Mandatory
Identifies this message. The ID is generated by MMSC
recipient
String 1
Mandatory
Identifies involved recipient
msgState
Long
Mandatory
Signals status of message
msgStateText
String 1
Optional
Explanation text for message status. This text is delivered by MMSC
MSISDN as sent with submit
request
1 –n (see Table 28: msgState
and msgStateText)
Retrieved
(see Table 28: msgState and
msgStateText)
Table 27: https GET parameter
1
The message is sent as URL encoded HTTPS GET request.
Possible msgState and msgStateText values within response message are:
msgState
msgState Text
CH-3050 Bern
3
Description
Version 4.0
22. June 2015
65/79
0
1
2
3
4
5
6
7
Retrieved +[Additional Info, if necessary]
Rejected +[Additional Info, if necessary]
Expired +[Additional Info, if necessary]
Deferred +[Additional Info, if necessary]
Unrecognised +[Additional Info, if necessary]
Indeterminate +[Additional Info, if necessary]
Forwarded +[Additional Info, if necessary]
Unreachable +[Additional Info, if necessary]
Message successful delivered to handset
Message from end customer or system rejected
Message is expired
End customer will start message download later
Handset is not able to recognise the message (e.g. version problem)
Is not known, if message was delivered correctly
End customer has message forwarded without download
End customer not reachable (e.g. network or routing problems)
Table 28: msgState and msgStateText
Example GET Request (MBSThird Party)
GET
/report?reportType=DELIVERY&msgId=vQhLezzYw3Grc7EOlnqB10%40mms.natel.ch&recipient=41791112233&msgState=0&msgStateText=Retr
ieved HTTP/1.1
accept: */*
accept-charset: utf-8
Via: HTTP/1.0 10.222.38.200:9000
Connection: close
Host: 10.234.31.43:18888
Example GET Response (Third Party  MBS)
HTTP/1.1 200 OK
Content-Type: text/html; charset=iso-8859-1
Connection: close
<html><body>successful</body></html>
Possible responses are:
 successful
 failed
It is important to analyze the Delivery Notifications. Only these notifications can give you the
overview about successful delivered messages in order to create meaningful statistics.
CH-3050 Bern
3
Version 4.0
22. June 2015
66/79
4.5 API Documentation
In order to access the MB via the TPI Interface, Third Party needs to adapt their application. To support the
Third Party while implementing the TPI Interface, Swisscom developed a reference implementation [[13]]
which is based on Axis 1.4 [11]. The reference implementation includes a Submit and a Deliver part as well
as the appropriate XSD files. In addition there are console clients for submit request and a batch file for
starting the report/deliver HTTPS server.
4.5.1
Assumption
For using the reference implementation the following assumptions are necessary:

Java 1.5 till 1.7 Runtime environment

Connection to MB configured (firewalls)

Account information (Username, Password, Service Name)

Reference implementation archive
4.5.2
Installation
The installation of the reference implementation is rather simple. The following steps have to be done:

Extract the reference implementation archive. To prevent problems, do not use spaces in the destination path

Set the JAVA_HOME in the batch file "CommonSettings.bat"

Use the "Command Prompt" shortcut to open two DOS prompt windows
4.5.3
Submit Requests
4.5.3.1 SMS Submit Request
SMS Submit Request can be started with the following batch file "SMSSubmit.bat".
If the batch file is started without any parameter, then an example will be printed out:
c:\tpi>SMSSubmit.bat
Usage: SMSSubmit.bat -i 102 -u reto -p pw -f "von reto" -n "reto's service" -l "bill text" -d "dummy id" -r https://localhost:15100/submit/ -t
41791234567 -a ".\content\frankie manning.txt" -v
CH-3050 Bern
3
Version 4.0
22. June 2015
67/79
To show the help screen use the "-–help" switch:
c:\tpi>SMSSubmit.bat –-help
...
Usage: SMSSubmitConsoleClient -r, --url <an url>
-i, --short-id <a short-id>
-n, --service-name <a service-name>
-u, --username <an username>
-p, --password <a password>
-f, --from <a from>
-l, --bill-text <a bill-text enclosed by double quotes>
-d, --transaction-id <a transaction-id>
[[-t, --recipient <to>] [-t, --recipient <to>] ...] or [-t, --recipient <to,to,to, ...> enclosed by double quotes] or [-t, --recipient <recipientfile>]
[[-a, --content <file-location>] [-a, --content <file-location>] ...]
[-s, --subject <a subject enclosed by double quotes>]
[--amount <an amount int value>]
[--charge <a charge float value>]
[--delivery-report]
[--report-address <a report url>]
[--allow-adaption]
[--originator-url <a report url>]
[--service-class <a service class>]
[--priority <a priority>]
[--distribution-indicator]
[--service-category <a service category>]
[--earliest-delivery-time <offset like: +10m or +2h or +4d or -10m>]
[--expiry-time <offset like: +10m or +2h or +4d or -10m>]
[--rplsm]
[--nokia-binary-port <hex string like: 66>]
[--message-class]
[--is-text]
[--udh <hex string like: 06050415820000>]
[--dcs <hex string like: 08 or F5 or F7>]
[-m, --message-type <[Ss]|[Cc]>]
[--obp <adds optional boolean parameters if not set with false>]
[--read-timeout <read timeout in seconds>]
[-x, --xsd-validation <enables xsd validation>]
[-v, --verbose <increases debuglevel>]
[-h, --help <prints this help>]
4.5.3.2 MMS Submit Request
MMS Submit Request can be started with the following batch file: "MMSSubmit.bat". If the batch file is
started without any parameter, then an example will be printed out:
c:\tpi>MMSSubmit.bat
Usage: MMSSubmit.bat -i 102 -u reto -p pw -f "von reto" -n "reto's service" -l "bill text" -d "dummy id" -r https://localhost:15100/submit/ -t
41791234567 -a ".\content\Laurel und Hardy.gif" -a ".\content\frankie manning.txt" -v
CH-3050 Bern
3
Version 4.0
22. June 2015
68/79
c:\tpi>MMSSubmit.bat –-help
...
Usage: MMSSubmitConsoleClient -r, --url <an url>
-i, --short-id <a short-id>
-n, --service-name <a service-name>
-u, --username <an username>
-p, --password <a password>
-f, --from <a from>
-l, --bill-text <a bill-text enclosed by double quotes>
-d, --transaction-id <a transaction-id>
[[-t, --to-recipient <to>] [-t, --to-recipient <to>] ...] or [-t, --to-recipient <to,to,to, ...> enclosed by double quotes] or [-t, --torecipient <recipientfile>]
[[-c, --cc-recipient <cc>] [-c, --cc-recipient <cc>] ...] or [-c, --cc-recipient <cc,cc,cc, ...> enclosed by double quotes] or [-c, --ccrecipient <recipientfile>]
[[-b, --bcc-recipient <bcc>] [-b, --bcc-recipient <bcc>] ...] or [-b, --bcc-recipient <bcc,bcc,bcc, ...> enclosed by double quotes] or
[-b, --bcc-recipient <recipientfile>]
[[-a, --content <file-location>] [-a, --content <file-location>] ...]
[-s, --subject <a subject enclosed by double quotes>]
[--amount <an amount int value>]
[--charge <a charge float value>]
[--delivery-report]
[--report-address <a report url>]
[--allow-adaption]
[--originator-url <a report url>]
[--service-class <a service class>]
[--priority <a priority>]
[--distribution-indicator]
[--service-category <a service category>]
[--earliest-delivery-time <offset like: +10m or +2h or +4d or -10m>]
[--expiry-time <offset like: +10m or +2h or +4d or -10m>]
[-m, --message-type <[Mm>]
[--obp <adds optional boolean parameters if not set with false>]
[--read-timeout <read timeout in seconds>]
[-x, --xsd-validation <enables xsd validation>]
4.5.4
Deliver Request
The Delivery Request can be received by the HTTPS server. The HTTPS server can be started via the following
batch file: "HttpServer.bat". If the batch file is started without any parameter, then an example will be printed out:
c:\tpi>HttpServer.bat
Usage: HttpServer.bat -i localhost -p 15100 -t
.\temp
c:\tpi>HttpServer.bat –-help
...
Usage: MBTPIHttpServer -i, --interface <a valid local host name / local ip address>
-p, --port <a free local port>
CH-3050 Bern
3
Version 4.0
22. June 2015
69/79
-t, --tmpdir <a directory where to store the received attachments>
CH-3050 Bern
3
Version 4.0
22. June 2015
70/79
4.5.5
Reports
The report can be received by the HTTPS server. The HTTPS server can be started via the following batch file:
"HttpServer.bat". If the batch file is started without any parameter, then an example will be printed out:
c:\tpi>HttpServer.bat
Usage: HttpServer.bat -i localhost -p 15100 -t
.\temp
To show the help screen use the "--help" switch:
c:\tpi>HttpServer.bat –-help
...
Usage: MBTPIHttpServer -i, --interface <a valid local host name / local ip address>
-p, --port <a free local port>
-t, --tmpdir <a directory where to store the received attachments>
4.6 TPI Developer Documentation
The TPI was realised as message based SOAP service with multiple attachments. That means, the whole
SOAP Envelope will be delivered to the SOAP Service. This results into more work for the developer to implement the TPI, but he will have a much better control over the client.
The messages are described in the XSD files. Using a generator (like Castor [12]) it is possible generate the
message beans. Only the attachments have to be attached manually to the SOAP Envelope.
The jar files "mbtpi.jar" and "mbtpi-beans.jar" the containing the reference implementation are located in
the directory "dist". The jar file includes the java class and the java source files. The XSD files are included in
the "mbtpi-beans.jar" file.
CH-3050 Bern
3
Version 4.0
22. June 2015
71/79
4.6.1
Submit Requests
4.6.1.1 SMS Submit Request
A SMS Submit Request could be implemented as follows:
SMSSubmit submit = new SMSSubmit();
SMSSubmitRequest smsSubmitRequest = new SMSSubmitRequest();
smsSubmitRequest.setShortId(12345);
smsSubmitRequest.setServiceName("SMS-SUB-12345");
...
try {
SubmitResponse smsSubmitResponse = submit.submit(smsSubmitRequest);
submit.close();
StringBuffer sb = new StringBuffer();
sb.append("\n\n");
sb.append("[").append("State:
")
.append(smsSubmitResponse.getState()).append("]\n");
sb.append("[").append("StateText: ")
.append(smsSubmitResponse.getStateText()).append("]\n");
sb.append("[").append("MessageId: ")
.append(smsSubmitResponse.getMessageId()).append("]\n");
sb.append("[").append("TransactionId: ")
.append(smsSubmitResponse.getTransactionId()).append("]\n");
sb.append("[").append("MessageType: ")
.append(((SMSSubmitResponse) smsSubmitResponse).getMessageType().toString())
.append("]\n");
for (MessageState state: smsSubmitResponse.getMessageState()) {
sb.append(" [").append("State: ").append(state.getState()).append("]\n");
sb.append(" [").append("StateText: ").append(state.getStateText()).append("]\n");
sb.append(" [").append("Recipient: ").append(state.getRecipient()).append("]\n");
}
if (SubmitResponseState.getSubmitResponseStateByStateCode(smsSubmitResponse.getState())
.equals(SubmitResponseState.NO_1000)) {
System.out.println(sb.toString());
} else {
System.err.println(sb.toString());
}
} catch (ServiceException ex) {
System.err.println(ex.getMessage());
System.exit(2);
}
In the class "com.swisscom.mb.tpi.SMSConsoleClient" you can find a complete implemented example of a
SMS Submit Request.
CH-3050 Bern
3
Version 4.0
22. June 2015
72/79
4.6.1.2 MMS Submit Request
A MMS Submit Request can be implemented as follows:
MMSSubmit submit = new MMSSubmit();
MMSSubmitRequest mmsSubmitRequest = new MMSSubmitRequest();
mmsSubmitRequest.setShortId(12345);
mmsSubmitRequest.setServiceName("MMS-SUB-12345");
...
try {
MMSSubmitResponse mmsSubmitResponse = (MMSSubmitResponse) submit.submit(mmsSubmitRequest);
submit.close();
StringBuffer sb = new StringBuffer();
sb.append("\n\n");
sb.append("[").append("State:
")
.append(mmsSubmitResponse.getState()).append("]\n");
sb.append("[").append("StateText: ")
.append(mmsSubmitResponse.getStateText()).append("]\n");
sb.append("[").append("MessageId: ")
.append(mmsSubmitResponse.getMessageId()).append("]\n");
sb.append("[").append("TransactionId: ")
.append(mmsSubmitResponse.getTransactionId()).append("]\n");
sb.append("[").append("MessageType: ")
.append(((MMSSubmitResponse) mmsSubmitResponse).getMessageType().toString())
.append("]\n");
for (MessageState state : mmsSubmitResponse.getMessageState()) {
sb.append(" [").append("State: ").append(state.getState()).append("]\n");
sb.append(" [").append("StateText: ").append(state.getStateText()).append("]\n");
sb.append(" [").append("Recipient: ").append(state.getRecipient()).append("]\n");
}
if (SubmitResponseState.getSubmitResponseStateByStateCode(mmsSubmitResponse.getState())
.equals(SubmitResponseState.NO_1000)) {
System.out.println(sb.toString());
} else {
System.err.println(sb.toString());
}
} catch (ServiceException ex) {
System.err.println(ex.getMessage());
System.exit(2);
}
In the class "com.swisscom.mb.tpi.MMSConsoleClient" you can find a complete implemented example of a
MMS Submit Request.
4.6.2
Report Servlet
Reports Requests can be received through a common HTTPS GET service. In the class
"com.swisscom.mb.tpi.http.servlet.axis.MBReportServlet" you can find an example of a Report Request
Servlet.
A first validation of the report request is done in the servlet. If the Report Request is valid, it will be forwarded to a queue in the static class "com.swisscom.mb.tpi.dispatch.Dispatcher".
CH-3050 Bern
3
Version 4.0
22. June 2015
73/79
4.6.3
Deliver Request
Deliver Requests can be received in two differed ways.

A Servlet which is implements the following interface "javax.xml.messaging.ReqRespListener"
The following class shows an example:
"com.swisscom.mb.tpi.http.servlet.axis.MBDeliverServlet"
The deliver servlet then invokes the SOAP service below.

Implementation of a SOAP Service which can run inside a servlet container like Tomcat. The following class shows an example:
"com.swisscom.mb.tpi.http.servlet.axis.ws.DeliverServiceImpl"
The SOAP Service can be registered via the web service deployment descriptor file "deploy-deliver.wsdd". To
deregister the SOAP Service uses the file "undeploy-deliver.wsdd".
A first validation of the Deliver Request is done in the service implementation. If the Deliver Request is valid,
it will be forwarded to a queue in the static class "com.swisscom.mb.tpi.dispatch.Dispatcher".
4.6.4
Dispatcher
Services which are using Deliver and Report Requests, can register as listener on the static class
"com.swisscom.mb.tpi.dispatch.Dispatcher".
The following interfaces must be implemented:

"com.swisscom.mb.tpi.dispatch.ReportEventListener"

"com.swisscom.mb.tpi.dispatch.DeliverEventListener"
The dispatcher informs all registered listener about incoming Deliver and Report Requests.
CH-3050 Bern
3
Version 4.0
22. June 2015
74/79
4.6.5
MB-TPI Archive Structure
The MB-TPI archive has the following structure:
Figure 19: MB-TPI Archive Structure
Unpacked directory structure:
c:\MB_TPI_1.1-b29
| README.txt
| Command Prompt.lnk
| CommonSettings.bat
| HttpServer.bat
| SMSSubmit.bat
| MMSSubmit.bat
| MBSimHttpServer.bat
| SMSDeliver.bat
| MMSDeliver.bat
|
+---content
|
frankie manning long.txt
|
frankie manning.txt
|
Laurel und Hardy.gif
|
T'ain't What You Do.3gp
|
T'ain't What You Do.amr
+---dist
|
mbtpi.jar
CH-3050 Bern
3
Version 4.0
22. June 2015
75/79
|
mbtpi-beans.jar
|
mbtpi-sim.jar
|
mbtpi-beans-sim.jar
|
+---etc
|
log4j-mbts.properties
|
log4j-mbhttp.properties
|
+---libs
+---libs.apache.commons.http
|
commons-codec-1.3.jar
|
commons-httpclient-3.0.1.jar
|
+---libs.apache.commons.io
|
commons-io-1.3.1.jar
|
+---libs.attachment
|
activation.jar
|
jaxm-api.jar
|
mail.jar
|
+---libs.axis1.4
|
axis.jar
|
commons-discovery-0.2.jar
|
jaxrpc.jar
|
saaj.jar
|
wsdl4j-1.5.1.jar
|
+---libs.castor
|
castor-1.0.3.jar
|
jakarta-oro-2.0.8.jar
|
xercesImpl.jar
|
xml-apis.jar
|
+---libs.jargs
|
jargs.jar
|
+---libs.jetty
|
jetty-6.1.2.jar
|
jetty-util-6.1.2.jar
|
servlet-api-2.5-6.1.2.jar
|
+---libs.logging
|
commons-logging-1.1.jar
|
log4j-1.2.14.jar
|
+---libs.slf4j
|
slf4j-api-1.2.jar
|
slf4j-log4j12-1.2.jar
|
+---temp
+---var
| \---log
\---xsd
deploy-deliver.wsdd
undeploy-deliver.wsdd
Deliver.xsd
Header.xsd
Report.xsd
CH-3050 Bern
3
Version 4.0
22. June 2015
76/79
Submit.xsd
CH-3050 Bern
3
Version 4.0
22. June 2015
77/79
4.7 Simple Object Access Protocol (SOAP)
4.7.1
Overview
Application
SOAP
HTTP
Application Layer Protocol
TCP
IP
Transport Protocol
Figure 20: Overview SOAP
SOAP (Simple Object Access Protocol) is a standardized protocol which allows every application to communicate with another application.




4.7.2
SOAP is a simple, XML-based protocol
with SOAP is it possible to locate every server within the internet
SOAP include implementations of business components and applications
SOAP can be implemented on every platform and operations system
SOAP Functionality
Protocol Header
SOAP Envelope
SOAP Header
SOAP Body
Attachment
Attachment
SOAP Message
Figure 21: Overview SOAP Message
All transactions between Third Party and Enabling Platform have to be wrapped in SOAP messages. This
SOAP message must consist of SOAP Envelope, SOAP Header and SOAP Body. The SOAP message content includes the control information (header inscriptions) in the SOAP Header element (header fields), MMS headers, attachments, request status and MIME content references in the SOAP Body element (body fields).
CH-3050 Bern
3
Version 4.0
22. June 2015
78/79
4.8 MMS Content
4.8.1
Multimedia Message within SOAP (MIME Types)
The MMS itself is included in the MIME body and is via HTTPS body delivered. The detailed content is in the
MIME specification defined.
If a MMS is sent occurs a SOAP HTTPS request message. All possible operations in the MM7- and TPIinterface have an accordant SOAP HTTPS response message. This matters that every side must be able to
handle request and response messages. Every operation is started with a HTTPS post method, which contains the delivery information. As quittance for the post message will the receiver application send a HTTPS
response with the answer of the specific operation.
Best format for Third Party:
 Text = txt
 Picture = gif, jpg, png
 Audio = imy (iMelody), wav, amr, midi
 Video = 3gpp
 Contact-Card = vCard
 Content-Viewer = smil
Best content size:
Device Type
Picture Size
Color
max. Content Size
High end
Mid end
Low end
> 240 x 320 pix
= 240 x 320 pix
< 240 x 320 pix
< 65’536
< 4096
< 256
<= 100kB
<= 100kB
<= 100kB
MMS should always be sent as multimedia message (smil file and attachments). Text files
have to be UTF-8 encoded (OMA Standard for MMS). Those MMS are displayed correctly on
all handsets. If only ISO 8859-1 text files or UTF-8 text files without smil file are sent, it is
possible, that some MMS are not showed properly on different handsets.
Further more detailed information about content formatting you will find in Swisscom’s document
MMS_Content_Guidelines_V1 [10]
4.8.2
Transcoding
The MMSC has the possibility to convert the content according of the end customer’s handset, so that it will
be showed in the best way. This feature can be controlled by the MMS Submit parameter allow adaption
(see chapter 4.4.2.1)
CH-3050 Bern
3
Version 4.0
22. June 2015
79/79

SMS/MMS Business Numbers

Transcription

Similar documents

GET INFO ON YOUR CELLPHONE BY SMS Text your

SavinGreen Mobile Phone Post-‐Paid Auto Roaming (Optus 3G

High Quality SMS Gateways

Subscription Brochure

GATEWAY INTRODUCTION

Going for a walk has never been so exciting!

Qmatic Pharmacy - Customer Flow Management

SPECIFICATIONS SMS Alarm Management SMS Gate

sms gateway - Panacea Mobile

February 19, 2016 - Saint Mary School