Home

Search the wiki

»

API Documentation


Mobile Payment


Other






PSWinCom Gateway XML MMS API

RSS
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:
  • Telenor Mobil
  • NetCom


Gateway connect information

Endpoints

XML over HTTP(S):http(s)://xml.pswin.com
failover: http(s)://xml2.pswin.com

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

Gateway interfaces: | XML | HTTP | SMTP | SOAP | SFTP BatchLoader
Intouch interfaces: REST | Syncopy

© Copyright Link Mobility ASA.





GuestLogin