This document describes how to use the
XML Interface of the
PSWinCom MMS Gateway. This document is intended for developers
only, and basic knowledge of XML is required. The XML interface for
MMS is very similar to the SMS interface.
A .NET assembly component based on this XML interface is available
to handle both sending and receiving MMS messages. It should be
used to simplify client side implementation when possible.
The XML interface is supported both as a direct TCP socket on port
1111 as well as over HTTP. If using the direct TCP socket, it is
important that your firewall (if any) is open for outbound TCP
connections to the Gateway’s IP address and port number. Also, if
receiving incoming MMS through the Gateway, you will need to open
for incoming TCP from the Gateway’s IP address on the dedicated
port.
To avoid the need for firewall configuration, the XML interface can be
used over HTTP with default port number 80. A SOAP/WebService
interface is also available.
MMS in general and Premium MMS (CPA) are currently supported for
the following operators:
Norway:
Gateway connect information
Endpoints
SSL Certificates
All PSWinCom services are secured using a single
*.pswin.com SSL
Server certificate. The whole certificate chain can be downloaded from the PSWinCom Wiki:
PSWinCom SSL certificates
XML Specifications
The XML communication works in a client-server way, where the
PSWinCom MMS Gateway acts as the server-part when you send
messages and as the client-part when you receive messages.
The DTDs presented below are backward compatible with the DTDs for
sending SMS. That means that you can validate your SMS messages
with the DTDs in this document, but you cannot validate your MMS
XML documents with the older SMS DTDs. They do therefore also carry
the same name as the SMS DTDs.
Send message request
The XML document consists of two major parts: logon-information and
the message-list. The elements of both parts will be explained more in
details in chapter 4.
The DTD for a send MMS request is as follows:
<!-- PSWinCom DTD MMS/SMS Submit-->
<!ELEMENT ID (#PCDATA)>
<!ELEMENT NET (#PCDATA)>
<!ELEMENT AP (#PCDATA)>
<!ELEMENT SD (#PCDATA)>
<!ELEMENT TEXT (#PCDATA)>
<!ELEMENT CLASS (#PCDATA)>
<!ELEMENT OP (#PCDATA)>
<!ELEMENT RCPREQ (#PCDATA)>
<!ELEMENT RCPFMT (#PCDATA)>
<!ELEMENT SND (#PCDATA)>
<!ELEMENT RCV (#PCDATA)>
<!ELEMENT TARIFF (#PCDATA)>
<!ELEMENT MMSFILE (#PCDATA)>
<!ELEMENT CLIENT (#PCDATA)>
<!ELEMENT PW (#PCDATA)>
<!ELEMENT NAME (#PCDATA)>
<!ELEMENT MSG (ID?, NET?, TARIFF?, TEXT, CLASS?, OP?,
RCPREQ?, RCPFRM?, SND?, RCV, MMSFILE?)>
<!ELEMENT QRY (NAME)>
<!ELEMENT MSGLST (MSG+)>
<!ELEMENT QRYLST (QRY+)>
<!ELEMENT SESSION (CLIENT, PW, AP?, SD?, MSGLST?, QRYLST?)>
A sample of a XML document containing an MMS message:
<?xml version="1.0"?>
<!DOCTYPE SESSION SYSTEM "pswincom_submit.dtd">
<SESSION>
<CLIENT>demo</CLIENT>
<PW>password</PW>
<MSGLST>
<MSG>
<ID>1</ID>
<TARIFF>300</TARIFF>
<TEXT>My MMS message subject</TEXT>
<OP>13</OP>
<SND>2077</SND>
<RCV>4793000000</RCV>
<MMSFILE>[base 64 encoded zipped MMS]</MMSFILE>
</MSG>
</MSGLST>
</SESSION>
The sample above shows the required XML document with, but the
content itself (the MMSFILE element) has been left out for simplicity.
See chapter 4 for a detailed description of each element and possible
values.
Supported character set: ISO 8859-Latin1.
Send message response
The Gateway will return a XML document containing status of the
logon request, and, if logon was ok, a status for each message
submitted.
The DTD for a send MMS response is as follows:
<!-- PSWinCom DTD SMS Submit Response-->
<!ELEMENT ID (#PCDATA)>
<!ELEMENT REF (#PCDATA)>
<!ELEMENT LOGON (#PCDATA)>
<!ELEMENT REASON (#PCDATA)>
<!ELEMENT STATUS (#PCDATA)>
<!ELEMENT INFO (#PCDATA)>
<!ELEMENT RESULT (#PCDATA)>
<!ELEMENT MSG (ID, REF?, STATUS, INFO)>
<!ELEMENT MSGLST (MSG+)>
<!ELEMENT QRY (RESULT)>
<!ELEMENT QRYLST (QRY+)>
<!ELEMENT SESSION (LOGON, REASON, MSGLST?, QRYLST?)>
The response XML for the above sending XML document will be
formatted as follows:
<?xml version="1.0"?>
<!DOCTYPE SESSION SYSTEM "pswincom_submit_response.dtd">
<SESSION>
<LOGON>OK</LOGON>
<REASON></REASON>
<MSGLST>
<MSG>
<ID>1</ID>
<STATUS>OK</STATUS>
<INFO></INFO>
</MSG>
</MSGLST>
</SESSION>
Receive message request
The reception of messages is similar to sending, except that the
communication is initiated by the Gateway instead of the customer.
There’s also less parameters and settings available for incoming messages. When setting up your account for incoming messages and
would like to receive them using the XML interface, you must supply
an IP/port-number or URL at your end. You will need to listen on this
port for incoming TCP connections or HTTP POST from the Gateway.
The Gateway will deliver an XML document built on the following DTD:
<!-- PSWinCom DTD SMS/MMS Receive Request-->
<!ELEMENT ID (#PCDATA)>
<!ELEMENT SND (#PCDATA)>
<!ELEMENT RCV (#PCDATA)>
<!ELEMENT TEXT (#PCDATA)>
<!ELEMENT NET (#PCDATA)>
<!ELEMENT ADDRESS (#PCDATA)>
<!ELEMENT MMSFILE (#PCDATA)>
<!ELEMENT MSG (ID, TEXT, SND, RCV, NET?, ADDRESS?,
MMSFILE?)>
<!ELEMENT MSGLST (MSG+)>
Please note that here’s no login information wrapped in a session
element, but only a list of one or more message elements.
A sample XML receive request from the Gateway may be formatted as follows:
<?xml version="1.0"?>
<!DOCTYPE MSGLST SYSTEM "pswincom_receive_request.dtd">
<MSGLST>
<MSG>
<ID>1</ID>
<TEXT>Incoming MMS subject</TEXT>
<SND>4512345678</SND>
<RCV>2077</RCV>
<MMSFILE>[base 64 encoded zipped MMS]</MMSFILE>
</MSG>
</MSGLST>
Receive message response
Upon receiving the incoming messages XML document, the customer
should reply with a confirmation of the reception.
The DTD for the response is as follows:
<!-- PSWinCom DTD SMS Receive Response-->
<!ELEMENT ID (#PCDATA)>
<!ELEMENT STATUS (#PCDATA)>
<!ELEMENT MSG (ID, STATUS)>
<!ELEMENT MSGLST (MSG+)>
A sample confirmation of the above receive request will be as follows:
<?xml version="1.0"?>
<!DOCTYPE MSGLST SYSTEM "pswincom_receive_response.dtd">
<MSGLST>
<MSG>
<ID>1</ID>
<STATUS>OK</STATUS>
</MSG>
</MSGLST>
Receive delivery report request
If the client account has been enabled to forward delivery reports to
the client, then the client may receive the delivery reports pretty much
in the same way as receiving incoming messages. As with receiving
messages, you will need to supply the Gateway with an IP
address/port number or URL at your end. You will need to listen on
this port for incoming TCP connections or HTTP POST from the
Gateway.
The Gateway will deliver an XML document built on the following DTD:
<!-- PSWinCom DTD MMS/SMS Delivery Report Request-->
<!ELEMENT ID (#PCDATA)>
<!ELEMENT REF (#PCDATA)>
<!ELEMENT RCV (#PCDATA)>
<!ELEMENT STATE (#PCDATA)>
<!ELEMENT DELIVERYTIME (#PCDATA)>
<!ELEMENT MSG (ID, REF, RCV, STATE, DELIVERYTIME?)>
<!ELEMENT MSGLST (MSG+)>
Please note that here’s no login information wrapped in a session
element, but only a list of one or more message elements.
A sample XML delivery report request from the Gateway may be formatted as follows:
<?xml version="1.0"?>
<!DOCTYPE MSGLST SYSTEM "pswincom_report_request.dtd">
<MSGLST>
<MSG>
<ID>1</ID>
<REF>984342374</REF>
<RCV>4512345678</RCV>
<STATE>Retrieved</STATE>
<DELIVERYTIME>2006.02.23 15:23:23</DELIVERYTIME>
</MSG>
</MSGLST>
Receive delivery report response
Upon receiving the delivery report XML document, the customer
should reply with a confirmation of the reception.
The DTD for the response is as follows:
<!-- PSWinCom DTD SMS Delivery Report Response-->
<!ELEMENT ID (#PCDATA)>
<!ELEMENT STATUS (#PCDATA)>
<!ELEMENT MSG (ID, STATUS)>
<!ELEMENT MSGLST (MSG+)>
A sample confirmation of the above receive request will be as follows:
<?xml version="1.0"?>
<!DOCTYPE MSGLST SYSTEM "pswincom_report_response.dtd">
<MSGLST>
<MSG>
<ID>1</ID>
<STATUS>OK</STATUS>
</MSG>
</MSGLST>
Elements description
Session Root element
The root element of the XML send message document is the SESSION
element. It embodies both the login information and the list of
messages to send. The SESSION element can have the following childelements:
CLIENT, PW, AP, SD and MSGLST. They are all described in
the following topics:
Logon information
Three elements are accepted as logon information:
| Element |
Req |
Property |
Description |
| CLIENT |
Y |
Username |
Contains the login name assigned
to you by the PSWinCom Gateway
operator. |
| PW |
Y |
Password |
Password assigned to you by the
PSWinCom Gateway operator.
Note: Since the password is
transmitted in clear text it is
advised that you also instruct the
PSWinCom Gateway operator to
perform IP-address filtering for
your account, if you are using a
permanent address or address
range. |
| AP |
N |
AffiliateProgram |
If you are part of an Affiliate-
Program offered by the PSWinCom
Gateway provider, you can use this
element to specify your Affiliate
Program code. |
| SD |
N |
SessionData |
A free text field that can be used to
tag the session with customer
specific data such as the
application name, username,
reference-id etc. The maximum
length is 200 characters. Leave
empty unless required. |
More about the AffiliateProgram parameter:The AP-parameter is used to specify a certain Affiliate Program code.
If you are a software/system developer/integrator and are offering
SMS or MMS enabled software or services for use by your customers,
you can sign up for an Affiliate agreement in order to get a share of
the income your customers are generating to the Gateway provider.
Your customers will sign up for regular accounts on the PSWinCom
SMS/MMS Gateway, but your Affiliate code will be transmitted with
each session to the Gateway, making it possible to track your
customers usage.
You can also specify additional information for internal use/tracking
such as product version, vendor, license etc. This is done by adding up to three additional numeric parameters after the affiliation program
code, separated by comma.
Example:
<AP>MYPROG,1,4,2010</AP>
Where "MYPROG" is your Affiliate Program code, "1" may indicate it's a
enterprise edition of your software, "4" may be your software version
and "2010" may indicate a client number or that it's distributed
through a given partner company. The Gateway just stores these
values and does no processing upon them. You may use one, two, all
three or none of them depending on how fine-grained you want to
separate your customers traffic. You will find these values supplied as
extra-information on your Affiliate Program reports on the Gateway’s
account web.
Please contact the Gateway provider for agreement terms and details.
Note that an Affiliate agreement cannot be used if your SMS/MMS
software or service is solely to be used within your own
company/organization, but only when used by real customers.
The response XML when submitting a message will contain the
following two child elements under the SESSION element:
| Element |
Description |
| LOGON |
Status for logon. Possible values: “OK” or
“FAIL”. |
| REASON |
Optional element describing reason for a
failed login. |
Message list: MSGLST
One or more element of type MSG is contained as subelements/
children of a single MSGLST element.
Message: MSG
This is the main element and contains information about a single
message. Please note that not all possible child elements are valid for
all requests or responses. Read the DTDs carefully before using the
parameters.
Element valid for a Submit MMS request:
| Element |
Req1 |
Property2 |
Description |
| TEXT |
Y |
Subject |
This is the subject of the MMS to send or receive. |
| RCV |
Y |
ReceiverNum |
Number of receiver. |
| SND |
N |
SenderNumb
er |
Number of sender to be displayed
on receiver’s handset. For MMS
messages, this will be fixed to the
CPA account used, currently 2077
or 2180. |
| OP |
N |
N/A |
Specifies the type of operation to
perform for message. For MMS
messages, this is always “13”. |
| CLASS |
N |
N/A |
The GSM message class to use.
This is not relevant for MMS
Messages. |
| ID |
N |
N/A |
Numeric ID, must be unique
within one XML
document/session. The Gateway
will use this ID when returning
the response XML document. If
not set, the Gateway will assign
each message a unique number. |
| TARIFF |
Y |
Tariff |
Specifies the amount to charge
the end-user in units of
cents/”ører”. For example, to
charge the end-user NOK 5,- you
specify “500” as the TARIFF
value. Only valid values must be
used. Valid values are described
in the CPA Agreement from
PSWinCom that is required to use
this property. |
| MMSFILE |
Y |
Data |
The MMS Message content. This is
a base64 encoded ZIP-file
containing the various parts
(images, text, sounds etc) of the
MMS. Currently, the maximum
size in bytes of an MMS
(summarized length of all content
elements) is 300kB. |
| RCPREQ |
N |
RequestRecei
pt |
Set to “Y” (Yes) to indicate that a
delivery report forward is desired
for this message. Note that you
need to request to have this
feature enabled as it is not
default allowed. Contact
support@pswin.com for more
details. |
1 Relevant for sending only.
2 Corresponding property name in the PSWinCom .NET Client
Component.
Elements valid for a Submit MMS request:
| Element |
Req |
Property |
Description |
| ID |
N |
N/A |
Unique ID within one XML document/session.
Autogenerated by Gateway if not
set in Request. |
| REF |
N |
Reference |
If the account is enabled for
delivery report forwarding, and
the RCPREQ element is set to Y,
then this element will contain a
unique reference id for this
message that later can be used
to correlate this message with a
delivery report. This value must
be treated as a string with a
length of at least 36 characters. |
| STATUS |
N |
Status |
Status code indicating whether
processing of a message was
successful or not. Possible
values: OK, FAIL |
| INFO |
N |
FailedReason |
Additional information describing
reason for a failed message. |
Elements valid for a receive MMS request:
| Element |
Req |
Property |
Description |
| ID |
Y |
N/A |
Unique ID within one XML
document/session. |
| TEXT |
Y |
Text |
Subject of the MMS message. |
| RCV |
Y |
ReceiverNumber |
Number that the message was
sent to. This may be an
international formatted number
(with country prefix) or an
operator specific short/long
number (for example 2077) |
| SND |
N |
SenderNumber |
Number of the subscriber that
sent the message. This will be an
internationally formatted number
(with country prefix). |
| ADDRESS |
N |
Address |
Name and Address lookup
information. |
Elements valid for a receive MMS response:
| Element |
Req |
Property |
Description |
| ID |
N |
N/A |
Unique ID within one XML
document/session. Must
correspond to the ID of the
incoming message(s). |
| STATUS |
N |
N/A |
Status code indicating whether
processing of a message was
successful or not. Possible
values: OK, FAIL |
Elements valid for a receive MMS Delivery Report request:
| Element |
Req |
Property |
Description |
| ID |
Y |
N/A |
Unique ID within one XML
document/session. |
| REF |
N |
Reference |
The unique reference value
assigned to the message
that this delivery report
corresponds to. This value
must be treated as a string
with a length of at least 36
characters. |
| RCV |
Y |
ReceiverNumber |
The number of the
subscriber that this delivery
report is related to. |
| STATE |
Y |
State |
Final state as assigned by
the GSM Network or
Gateway. |
| DELIVERYTIME |
N |
DeliveryTime |
The actual time (in local
timezone of the MMSC
used) when the message
was delivered. Only present
for positive delivery reports
(State is RETRIEV). |
Elements valid for a receive MMS Delivery Report response:
| Element |
Req |
Property |
Description |
| ID |
N |
N/A |
Unique ID within one XML
document/session. Must
correspond to the ID of the
incoming delivery report(s). |
| STATUS |
N |
N/A |
Status code indicating whether
processing of a delivery report
was successful or not. Possible
values: OK, FAIL |
Delivery report states
A delivery report indicates the final state of each message, described
with a set of predefined states as follows:
| State |
Description |
| RETRIEV |
MMS was successfully downloaded to the receivers phone.
If the message is a CPA (Premium MMS), this will be the
only state that will result in a charge on the subscribers
account and a pay-out to the content-provider. |
| REJECTE |
The MMS was rejected by the operator or the receiver. |
| EXPIRED |
The MMS expired while waiting to be delivered. |
| FAILED |
The MMS failed to be delivered because no operator
accepted the message or due to invalid content file. |
| BARRED |
The receiver number is barred/blocked/not in use. Do not
retry message, and remove number from any subscriber
list. (Relevant for CPA messages only) |
| BARREDT |
The receiver number is temporarily blocked. May be an
empty pre-paid account. (Relevant for CPA messages only) |
| BARREDC |
The receiver has blocked for Premium (CPA) messages.
(Relevant for CPA messages only) |
| ZERO_BAL |
The receiver has an empty prepaid account. (Relevant for
CPA messages only) |
| INV_NET |
Invalid network. Receiver number is not recognized by
the target operator. |
Name & address lookup format
This is an optional feature on receiving messages. The Address
property on the receive message request may contain detailed
information about the sender, such as name and address. The
information is retrieved by the Gateway which is requesting such data
from a phone directory service. The format is as follows (line break
added for readability):
Firstname;middlename;lastname;address;
ZipCode;City;RegionNumber;CountyNumber
Sample result:
Kari;;Nordmann;Hjemmeveien 46;5211;
BERGEN;12;1201
Additional values may be added at the end in the future. This is a
value added feature that requires an additional agreement with
PSWinCom.
Query list: QRYLST
One or more element of type QRY is contained as subelements/
children of a single QRYLST element.
Query: QRY
This element holds the query definitions. Querying is rather limited as
of the current version, and the specifications are subject to change.
| Element |
Req |
Description |
| NAME |
Y |
Name of the query to execute. Allowed query
names are:
qry_balance - Ask for balance on current
account. |
Communication
Direct TCP socket
The client must establish a TCP/IP connection to the Gateway on the
given host and port number. When connected, no prompt will be given
from the Gateway.
The XML document should be streamed as a continuously stream of
data without delays.
After sending the XML document, the client may choose to disconnect
from the Gateway. Alternatively, the client may wait for the Gateway
to process the logon information and message-list. A XML document
with logon results and status for each message will then be returned
to the client over the connection. After receiving the response XML
document the client should close the connection, as the Gateway will
do so anyway.
It is not possible to send more than one session per connection. It is
recommended to send up to 500 messages in each XML document/
session. If sending thousands of messages continuously (bulk), it is
recommended to send 500 messages in each session and pause for 2
minutes between each session.
HTTP
The XML document may also be put into a HTTP request and
submitted to the Gateway that way. The XML document will be the
exact same, but instead of being streamed over a socket, it is put as
the body of a HTTP request.
A HTTP request may look like this:
POST /sms HTTP/1.0
Host: sms3.pswin.com
Content-type: application/xml
Content-length: 345
<?xml version="1.0"?>
<!DOCTYPE SESSION SYSTEM "pswincom_submit.dtd">
<SESSION>
<CLIENT>demo</CLIENT>
<PW>password</PW>
<MSGLST>
<MSG>
<ID>1</ID>
<TARIFF>300</TARIFF>
<TEXT>My MMS message subject</TEXT>
<OP>13</OP>
<SND>2180</SND>
<RCV>4793000000</RCV>
<MMSFILE>[base 64 encoded MMS]</MMSFILE>
</MSG>
</MSGLST>
</SESSION>
All headers in the sample above must be supplied, or you will get 402
(Bad Request) HTTP response code in return.
The corresponding HTTP response will look something like:
HTTP/1.1 200 Ok
Server: sms3.pswin.com
Content-type: application/xml
Content-length: 156
<?xml version="1.0"?>
<SESSION>
<LOGON>OK</LOGON>
<REASON></REASON>
<MSGLST>
<MSG>
<ID>1</ID>
<STATUS>OK</STATUS>
<INFO></INFO>
</MSG>
</MSGLST>
</SESSION>
HTTP may also be used for receiving MMS and delivery reports. The
XML is then placed as the body of a HTTP request from the Gateway to
a destination URL as specified by the customer.
MMS Content file
MMS is, compared to SMS, a much more content rich communication
technology. However, there are many similarities between how MMS
and SMS is used. For existing SMS Gateway customers, the MMS
Gateway interface will seem familiar in how it is structured. The MMS
Gateway is also an integrated part of the existing PSWinCom SMS
Gateway platform, and shares a common user database and web
administration tool (account web).
To simplify the packaging and transmission of MMS Messages, we
have decided to use a simple ZIP file as the packaging of the MMS
content. This means that all the content files/parts of the MMS must
be zipped together into one zip-file before transmission to the MMS
Gateway. The zip-file should not have any internal directory structure;
all content files must reside in the root directory of the zip file, like
this:
MyZippedMMS.zip contains
Pres.smil
Image.gif
Message.txt
Please note that the filenames within the zip file must not contain any
national/special characters.
How to construct an MMS presentation with text, audio and image
content is beyond the scope of this interface documentation. Most will
use some kind of MMS composer or other software to create the files
required. Refer to http://www.w3.org/AudioVideo/ for more
information about creating mobile content and SMIL files.
When using the XML interface, you must base64 encode your file with
the MMS content, and put the base64 encoded string in the MMSFILE
element. How to do this depends on your development tools and
platform. PSWinCom currently offers a .NET assembly that simplifies
greatly the client side handling. There are also a number of tools and
command line utilities available on the web that can create zip files
and base64 encode them.
Sample HTTP request
PSWinCom_sample_xml_http_post_mms_request.txt