PSWinCom Gateway XML SMS API

Modified on Tue, 19 Nov 2024 14:36 by FM — Categorized as: Gateway, XML API

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 over HTTPS:https://xml.pswin.com
failover: https://xml2.pswin.com



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

ElementReqPropertyDescription
CLIENTYUsernameContains the login name assigned to you by the PSWinCom Gateway Operator.
PWYPasswordPassword 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.
SDYSessionDataA 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 to get this enabled.

The response XML when submitting a message will contain the following two child elements under the SESSION element:

ElementDescription
LOGONStatus for logon. Possible values: "OK" or "FAIL".
REASONOptional 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

ElementReqDescription
IDNUnique ID within one XML document/session. Autogenerated by Gateway if not set in Request.
REFNUnique 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.
STATUSNStatus code indicating whether processing of a message was successful or not. Possible values: OK, FAIL
INFONAdditional 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

ElementReqDescription
IDNUnique ID within one XML document/session. Must correspond to the ID of the incoming delivery report(s).
STATUSNStatus 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):

 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

When receiving a request (message request or delivery response request), the encoding will always be specified in the Content-Type HTML header. If you're using an off-the-shelf server component, it should be able to handle the encoding for you.

Example of a message request with ISO-8859-1 charset:

POST /message HTTP/1.1
Host: myhost.example
Content-Length: 215
Content-Type: application/xml; charset=iso-8859-1
Psw-Message-Reference: b8ab8927-5b0c-4851-bdf9-f037dc5ca78e
Psw-Message-Type: MO
Psw-Message-Version: 2

<?xml version="1.0" encoding="iso-8859-1"?>...

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 noDelay (since latter attempt)
11 minutes later
25 minutes later
310 minutes later
460 minutes later
5120 minutes later
6300 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.