Welcome GuestLogin
© Copyright Link Mobility ASA
Home

Search the wiki

»

API Documentation


Mobile Payment


Other






PSWinCom Gateway XML SMS API

RSS
Modified on Fri, 10 Feb 2017 09:59 by Torbjørn Marø Categorized as Gateway, XML API
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 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.

XML may also be posted to the gateway as mail using SMTP. Please see the document SMTP Interface for more information regarding this.




Gateway connect information

Primary Endpoints

XML over HTTP:http://xml.pswin.com
failover: http://xml2.pswin.com
XML over HTTPS:https://xml.pswin.com
failover: https://xml2.pswin.com

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.
XML over HTTPS:https://xml-lb1.pswin.com
Alternate Fiber route https://xml-lb2.pswin.com

Raw TCP SOCKET Endpoints - Only use if unable to use HTTP(s) as transport, was created to support older industrial devices.

XML over TCP socketsocket.pswin.com - Port: 1111
failover:socket2.pswin.com - port 1112

Legacy CPA/GAS Endpoints - WILL BE TERMINATED Q4 2016

Only for legacy software. All new connections should be made towards the regular endpoints
XML over TCP socketsms.pswin.com - Port: 1111
failover:sms-backup.pswin.com - port 1112
XML over HTTP:http://sms3.pswin.com/sms
failover: http://sms3-backup.pswin.com/sms
XML over HTTPS:https://secure.pswin.com/XMLHttpWrapper/process.aspx
failover: https://secure-backup.pswin.com/XMLHttpWrapper/process.aspx

Firewall rules for Mobile Originated and Delivery Reports requests

Requests FROM the PSWinCom Gateway may come from the following IP Adresses: 217.149.126.54, 62.92.103.106 or 85.19.118.116.
Ports: 80, 443 or 1112

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 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:

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.

Element valid for a Submit SMS request:

Element Reg 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 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
RCV N 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.
RCPREQ N Set to “Y” (Yes) to indicate that a delivery report forward is desired for this message.
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.
CPATAG N 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 to null.
AGELIMIT N 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.

Examples:
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.
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

Elements valid for a submit SMS response:

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

Elements valid for a 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

Elements valid for a 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

Elements valid for a 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).

Elements valid for a 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

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 / 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.

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

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

© Copyright Link Mobility ASA.