The XML interface is supported both as a direct TCP socket on port
1111 as well as over HTTP. We recomend using HTTP.
Gateway endpoints
XML examples
Example of a XML request sent by HTTP POST:
POST / HTTP/1.0
Host: xml.pswin.com
Content-type: text/xml
Content-length: 245
<?xml version="1.0"?>
<SESSION>
<CLIENT>demo1</CLIENT>
<PW>demo1</PW>
<MSGLST>
<MSG>
<ID>1</ID>
<TEXT>Test message</TEXT>
<SND>4711111111</SND>
<RCV>4712345678</RCV>
</MSG>
</MSGLST>
</SESSION>
For an example with a dtd on the specific XML formats, see:
XML 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 and MSGLST. They are all described in the
following topics:
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. |
| 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:
| 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.
Send SMS request
| Element |
Req |
Description |
| ID |
N |
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. |
| TEXT |
N |
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
16 SMS messages, each of 134 characters.
Thus, the maximum length is 16*134=2144
characters. This is done automatically by the
SMS Gateway. Text messages of more than
2144 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 |
| RCV |
Y |
Number of receiver.
Must be specified including the
international prefix, but without any
leading “+” or “00”.
At least 9 digits. |
| SND |
N |
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. |
| OP |
N |
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.
|
| CLASS |
N |
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
element. |
| TTL |
N |
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. |
| REPLACE |
N |
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. |
| DELIVERYTIME |
N |
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:
YYYYMMDDHHmm
Sample:
20th of June 2008 at 14:32 should be specified
as: 200806201432
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. |
| TARIFF |
N |
See: CPA-Goods-and-Services |
| SERVICECODE |
N |
See: CPA-Goods-and-Services |
| AGELIMIT |
N |
See: CPA-Goods-and-Services |
| CPATAG |
N |
See: CPA-Goods-and-Services |
Send SMS response
| Element | Req | Description |
|---|
| ID | N | Unique ID within one XML document/session. Autogenerated by Gateway if not set in Request. |
| REF | N | Unique reference ID autogenerated by the gateway. The ID can later be used to correlate the 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. |
Receive SMS request
| Element |
Req |
Description |
| ID |
Y |
Unique ID within one XML document/session. |
| TEXT |
Y |
The message text received. |
| RCV |
Y |
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 |
Number of the subscriber that sent the message.
This will be an internationally formatted number
(with country prefix). |
| ADDRESS |
N |
Name and Address lookup information. See Name and address lookup format. |
| POSITION |
N |
When position lookup is enabled for keyword/accessnumber this will be populated with a Position structure. |
| METADATA |
N |
Additional data about the message, see: XML MO Metadata |
Receive SMS response
| Element |
Req |
Descriptio |
| ID |
N |
Unique ID within one XML document/session. Must
correspond to the ID of the incoming message(s). |
| STATUS |
N |
Status code indicating whether processing of a
message was successful or not. Possible values:
OK, FAIL |
Receive SMS Delivery Report request
| Element |
Req |
Descriptio |
| ID |
Y |
Unique ID within one XML document/session. |
| REF |
N |
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 |
The number of the subscriber that this
delivery report is related to. |
| STATE |
Y |
Final state as assigned by the GSM Network
or Gateway. |
| DELIVERYTIME |
N |
The actual time (in local timezone of the
SMSC used) when the message was
delivered. Only present for positive delivery
reports (State is DELIVRD). |
Receive SMS Delivery Report response
| Element | Req | Description |
|---|
| 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 StatusName & 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.
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
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 250 messages in each XML document/ 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 / HTTP/1.0
Host: xml.pswin.com
Content-type: text/xml
Content-length: 245
<?xml version="1.0"?>
<SESSION>
<CLIENT>demo1</CLIENT>
<PW>demo1</PW>
<MSGLST>
<MSG>
<ID>1</ID>
<TEXT>Test message</TEXT>
<SND>4711111111</SND>
<RCV>4712345678</RCV>
</MSG>
</MSGLST>
</SESSION>
And the corresponding HTTP response:
HTTP/1.1 200 OK
Server: nginx
Date:
Content-Type: text/xml
Connection: keep-alive
<?xml version="1.0"?>
<SESSION>
<LOGON>OK</LOGON>
<REASON />
<MSGLST>
<MSG>
<ID />
<STATUS>OK</STATUS>
<INFO></INFO>
<REF>4bab7e6e-d07b-42c9-b091-2594fecb59ae</REF>
</MSG>
</MSGLST>
</SESSION>
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.
Firewall rules for Mobile Originated and Delivery Reports requests¶
Requests FROM
the PSWinCom Gateway may come from 185.78.210.113
Ports: 80, 443 or 1112
You should also allow traffic from the ip-series 185.78.210.114-118
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
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 6
times if the receiver doesn’t reply properly. The delay between each
delivery attempt will be as follow:
| Attempt no | Delay (since latter attempt) |
|---|
| 1 | 1 minutes later |
| 2 | 5 minutes later |
| 3 | 10 minutes later |
| 4 | 60 minutes later |
| 5 | 120 minutes later |
| 6 | 300 minutes later |
If a message or delivery reports is received repeatedly, then the client
is probably not replying correctly back to the Gateway within
reasonable time.
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
reply properly.
Unicode messages
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
follows.
To send Unicode messages, set the OP (Operation Type) element to
the value 9 to indicate Unicode:
<OP>9</OP>
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:
<OP>9</OP>
<TEXT>004100420043</TEXT>
Due to the size of each Unicode character, a Unicode SMS can only
contain 70 Unicode characters.
Unicode character table:
http://unicode-table.com/Example code
This example uses a simple .aspx page and the PSWinCom .Net SDK client to handle MO and DR requests.
https://github.com/PSWinCom/PSWinCom-Gateway-MoDrExample
See also
Troubleshooting
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
port.
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.