This document describes how to use the XML Interface of the
PSWinCom SMS Gateway
. This document is intended for developers
only, and basic knowledge of XML is required.
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 SMS through the gateway, you will need to open
for incoming TCP from the Gateway’s IP address on the dedicated
To avoid the need for firewall configuration, the XML interface can be
used over HTTP with default port number 80. Alternatively, one can
use the HTTP interface (non XML) to submit messages using a HTTP
POST or GET operation with message parameters supplied. Please
refer to the document HTTP interface
for more information regarding
the HTTP interface.
XML may also be posted to the gateway as mail using SMTP. Please
see the document SMTP Interface
for more information regarding
Gateway connect information
Load-balanced Bulk Endpoints
These endpoint support BULK only (no CPA, GAS or MMS).
But are load-balanced across gateways, so will give better failover and overall performance.
Raw TCP SOCKET Endpoints - Only use if unable to use HTTP(s) as transport, was created to support older industrial devices.
Legacy CPA/GAS Endpoints - WILL BE TERMINATED Q4 2016Only for legacy software. All new connections should be made towards the regular endpoints
Firewall rules for Mobile Originated and Delivery Reports requests¶
the PSWinCom Gateway may come from the following IP Adresses: 184.108.40.206, 220.127.116.11 or 18.104.22.168.
Ports: 80, 443 or 1112
All PSWinCom services are secured using a single *.pswin.com
Server certificate. The whole certificate chain can be downloaded from the PSWinCom Wiki: PSWinCom SSL certificates
The XML communication works in a client-server way, where the
PSWinCom SMS Gateway acts as the server-part when you send
messages and as the client-part when you receive messages.
For details on the specific XML formats, see:
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 and MSGLST. They are all described in the
|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.|
|SD||Y||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. Must be the same value for all messages in a request when submitting multiple messages in the same request. The maximum length is 200 characters. Leave empty unless required. If you need aggregated reports based on Session Data values, please contact support to get this enabled.|
The response XML when submitting a message will contain the
following two child elements under the SESSION element:
|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.
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
Element valid for a Submit SMS request:
||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.
||The message text, either as plain text or as
hex-encoded data depending on message type. For
plain text messages, the message length
should not exceed 160 characters unless you
would like to use concatenated SMS
messages. Text messages exceeding 160
characters will be split up into a maximum of
6 SMS messages, each of 134 characters.
Thus, the maximum length is 6*134=804
characters. This is done automatically by the
SMS Gateway. Text messages of more than
804 characters will be truncated. Please note that only characters defined in the default GSM-7 character set is allowed for the default text message type
||Number of receiver.
Must be specified including the
international prefix, but without any
leading “+” or “00”.
At least 9 digits.
||Number of sender to be displayed on
receiver’s handset. Numeric with no “+” or
space, max 15 digits. Alphanumeric up to 11
characters can also be used. Please note that
no special/national characters are allowed for
alphanumeric sendernumber. Only the
characters a-z, A-Z, 0-9 and !”#%&’()*+ -
./?><; are allowed.
||Set to “Y” (Yes) to indicate that a delivery
report forward is desired for this message.
||Specifies the type of operation to perform for
message. This property is set to indicate use
of logos and ringtones. For possible values see Message types.
||The GSM message class to use. To send a
plain text message as a Flash message
(displayed directly on the terminal), set this
parameter to 0 (zero). Otherwise skip this
||Specifies the number of minutes this message
will be valid. The time is counted from the
moment the message has been received and
stored on PSWinCom Gateway. Set to 0 or
empty to use default value.
||Premium SMS messages may have an
additional description associated with itself. This value will be shown on the subscribers
phone bill to help identify the service
purchased. Please note that not all operators
support this property, and it may be
restrictions to how it is formatted. Pelase
consult PSWinCom technical support if you
intend to use this feature. Others should set it
||You may specify an age limit when sending
Premium SMS messages. If you set this
property to a value larger than 0 (zero), then
the value will be matched against the age of
the subscriber. The subscriber must then be
at least the given age in order to receive the
message. The operators usually accept 16 and 18.
The Gateway will pick the most appropriate age
limit it the operator cannot accept the given age limit.
AgeLimit is given as 17. The operator only accepts 0, 16 or 18. Gateway sends 16 to operator.
AgeLimit is given as 22. The operator only accepts 0, 16 or 18. Gateway sends 18 to operator.
It is recommended that you only use 16 or 18.
||Integer with allowed value 1-7 that indicates a
set of messages that can replace each other.
This parameter can be used to specify that the
message should replace a previous message
with the same set-number as given for this
parameter in the Inbox of the handset. See
chapter 12 for more details.
||String representing a date and time when the
Gateway should try to deliver the message.
If this parameter is present the message will
be considered to be a deferred message that
will be queued for future delivery instead of
immediately being forwarded to operator.
The format is as follows:
20th of June 2008 at 14:32 should be specified
Deliverytime is always in CET. Maximum delay
of message is currently one week (7 days).
The Gateway account must be provisioned to
use this feature.
Elements valid for a submit SMS response:
|ID||N||Unique ID within one XML document/session. Autogenerated by Gateway if not set in Request.|
|REF||N||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 code indicating whether processing of a message was successful or not. Possible values: OK, FAIL|
|INFO||N||Additional information describing reason for a failed message.|
Elements valid for a receive SMS request:
||Unique ID within one XML document/session.
||The message text received.
||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)
||Number of the subscriber that sent the message.
This will be an internationally formatted number
(with country prefix).
||Name and Address lookup information. See Name and address lookup format.
||When position lookup is enabled for keyword/accessnumber this will be populated with a Position structure.
||Additional data about the message, see: XML MO Metadata
Elements valid for a receive SMS response:
||Unique ID within one XML document/session. Must
correspond to the ID of the incoming message(s).
||Status code indicating whether processing of a
message was successful or not. Possible values:
Elements valid for a receive SMS Delivery Report request:
||Unique ID within one XML document/session.
||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.
||The number of the subscriber that this
delivery report is related to.
||Final state as assigned by the GSM Network
||The actual time (in local timezone of the
SMSC used) when the message was
delivered. Only present for positive delivery
reports (State is DELIVRD).
Elements valid for a receive SMS Delivery Report response:
|ID||N||Unique ID within one XML document/session. Must correspond to the ID of the incoming delivery report(s).|
|STATUS||N||Status code indicating whether processing of a delivery report was successful or not. Possible values: OK, FAIL.|
Delivery report states
Only the value DELIVRD should be considered a positive delivery acknowledgement.
For full list of possible delivery states, see: Delivery Report Status
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):
Additional values may be added at the end in the future. This is a
value added feature that requires an additional agreement with
Encoding / Character set
Reqests will be treated as Latin1 (ISO-8859-1) if no charset is defined in the Content-Type header. You can however specify any character set registered with IANA
. Only UTF-8 and ISO-8859-1 support is guaranteed.
Example of header with UTF-8 charset:
Content-Type: text/xml; charset=UTF-8
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.
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 / HTTP/1.0
And the corresponding HTTP response:
HTTP/1.1 200 OK
HTTP may also be used for receiving SMS 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.
Retry scheme for incoming messages
Incoming messages (messages received from a subscriber) and
delivery reports can be forwarded to the client using the XML
interface. The Gateway will try to deliver the message/report up to 5
times if the receiver doesn’t reply properly. The delay between each
delivery attempt will be as follow:
|Attempt no||Delay (since latter attempt)|
|2||5 minutes later|
|3||10 minutes later|
|4||60 minutes later|
|5||120 minutes later|
If a message or delivery reports is received repeatedly, then the client
is probably not replying correctly back to the Gateway within
The customer may request a backup/failover destination to be
configured as a secondary delivery destination. This destination will
then be tried for each delivery attempt if the main destination doesn’t
Unicode is a 16bit character set that can represent virtually any
character or sign and is required for Arabic and Chinese characters
amongst others. The PSWinCom SMS Gateway can be used to submit
messages using Unicode (UCS2). A brief instruction of how to do this
To send Unicode messages, set the OP (Operation Type) element to
the value 9 to indicate Unicode:
Since each Unicode character is 16 bits (opposed to the usual 7 or 8
bit), and many characters are not displayable or possible to enter on
many computers, the message must be hex-coded. Each Unicode
character is encoded into a 4-digit hex-value. Example: Unicode letter
A has the value of 0x0041 and is written as “0041”. All other elements
are used as for other messages. Please note that it is not possible to
use Unicode characters as alphanumeric sender number even if the OP
element is set to 9 – Unicode.
To send a message containing the characters “ABC” in Unicode, the
following element-values are required:
Due to the size of each Unicode character, a Unicode SMS can only
contain 70 Unicode characters.
Unicode character table: http://unicode-table.com/
This example uses a simple .aspx page and the PSWinCom .Net SDK client to handle MO and DR requests.