PSWinCom Gateway Simple HTTP API

Modified on Mon, 03 Jun 2024 13:05 by FM — Categorized as: Legacy Documentation

This is a legacy protocol and its use is strongly discouraged. Use the PSWinCom Gateway XML SMS API instead.

This document describes how to use the HTTP Interface of the PSWinCom SMS Gateway. This document is intended for developers only, and basic knowledge of the HTTP protocol is required.

The HTTP (HyperText Transfer Protocol) Interface of the PSWinCom SMS Gateway service is suitable for applications that already have HTTP client features built-in. The interface is “firewall-friendly” since standard HTTP protocol and port number 80 is used for client connections.

However, the HTTP interface is only recommended for submitting and receiving single messages, and IS NOT INTENDED to be used for bulk messaging. If you need to send several messages at the same time, use the Gateway XML SMS API which allows pushing a XML document with several messages in one single HTTP POST request.

For bulk messaging and higher throughput than about 1 message pr second, the XML interface is recommended.


Gateway connect information

Endpoints

HTTPS interface URL
Primary: https://simple.pswin.com
failover: https://simple2.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

Note: The basic HTTP send script return a minimal result code/string intended for use in automated applications. When sending ”manually” from a web browser, the browser might not understand the response since it is not a complete HTML document. The result might be that the web browser intend to save the response as a file, instead of displaying it directly. To avoid this situation, the script sendhttp.asp can be used instead of send.asp. The sendhttp.asp script will return a normal HTML document to display the answer.

Technical information

Using a single HTTP POST operation, the client may submit a SMS of any type to the PSWinCom SMS Gateway. Similarly, when receiving a SMS, the Gateway will initiate a HTTP POST operation to an URL defined by the customer.

The Gateway is HTTP version 1.1 compliant, but when delivering SMS from the Gateway to the customer, HTTP 1.0 is used for backward compatibility.

When POSTing, all parameters should be URL-encoded in the ISO-8859 Latin 1 character set, or the encoding specified in the enc parameter.

A HTTP GET Request may also be used for sending, but note that client software may put restrictions on the length of the URL.

Security Considerations

In the HTTP protocol, all data, including username and password, are sent as clear-text over the Internet and may be intercepted by a third-party.

The SSL secured interface (HTTPS protocol) can be used so that information is not sent as clear text. It is also recommended that you send the message as a POST request, since URLs often end up in log files.

Submitting SMS

This POST operation is initiated by the customer, and the response is returned from the Gateway to the customer over the same HTTP session. In terms of a client-server relationship, the customer here acts as a client and the Gateway as a server.

Request

A valid submission of a HTTP POST may look like this:

POST https://simple.pswin.com HTTP/1.1
Content-type: application/x-www-form-urlencoded
Host: simple.pswin.com

USER=Username&PW=Password&RCV=4799887766&SND=SenderID&TXT=test%e6%f8%e5
A valid submission using HTTP GET may look like this:

https://simple.pswin.com?USER=Username&PW=Password&RCV=4799887766&SND=SenderID&TXT=test%e6%f8%e5

Response

The following response will be valid for the request above:

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 03 May 2016 10:17:20 GMT
Content-Type: text/plain; charset=utf-8
Content-Length: 5
Connection: keep-alive

0
OK
The response will consist of two lines. First line is a numeric statuscode and the second is a corresponding description. A successful submission of the message will have a result code of 0. Any other result means that the submission has failed permanently and should be resubmitted.

Receiving delivery report

Delivery reports (handset status) may be forwarded to the customer application instead of being read manually on the account web.

Request

The Gateway will submit a HTTP POST Request as follows:

POST /receiveDeliveryReport.asp HTTP/1.0
Host: yourserver.com
Content-type: application/x-www-form-urlencoded

RCV=4712345678&REF=BB35EDF6-3D61-4DE5-9C95-C6E5E35D48EA&STATE=DELIVRD&DELIVERYTIME=2013.03.01+23%3a01%3a00
The hostname, port and path will depend on the corresponding values set for the actual customer account on the Gateway.

Response

The Gateway expects the customer (server) to reply with a HTTP status code of 200 (OK) if the delivery report was successfully received. Any other status value than 200 will result in the Gateway retrying delivery of the delivery report at a later time.

A sample successful response from the customer may be:

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.1
Content-Type: text/plain
The response should be as minimal as possible, and not contain any body unless required.

Correlating messages and delivery reports

You can use the REF value to correlate the delivery report with the message. If you set RCPREQ=Y when sending, you can get a unique reference value back that you can later use to do the correlation.

The HTTP response will with this interface respond with a third parameter that will contain the assigned unique reference value.

Sample response:

HTTP/1.0 200 OK
Server: Microsoft-IIS/5.0
Date: Mon, 08 Oct 2001 09:52:36 GMT
Content-Type: text/plain
Content-Length: 15
0
OK
4A4B0034DB

Receiving SMS

This POST operation is initiated by the Gateway, and the response should be returned by the customer to the Gateway over the same HTTP session. In terms of a client-server relationship, the customer here acts as a server and the Gateway as a client. Typically, the customer will receive and handle the incoming SMS using a webapplication running on a web-server such as IIS or Apache.

Request

The Gateway will submit a HTTP POST Request as follows:

HTTP: 
POST /ReceiveSMS HTTP/1.1
Content-Type: application/x-www-form-urlencoded
User-Agent: PSWinCom-SMSGateway/1.0
Host: your-hostname.com
Content-Length: xx
Expect: 100-continue
Connection: Keep-Alive

HTTP/1.1 100 Continue

ID=1&SND=4712345678&RCV=26112&TXT=Test message
Alternate format XML HTTP:

POST /ReceiveSMS HTTP/1.1
Content-Type: application/xml
PSW-Message-type: MO
PSW-Message-version: 2
Host: your-hostname.com
Content-Length: xx
Connection: Keep-Alive

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE MSGLST SYSTEM "pswincom_receive_request.dtd">
<MSGLST>
    <MSG>
        <ID>1</ID>
        <TEXT>Test message</TEXT>
        <SND>4712345678</SND>
        <RCV>26112</RCV>
        <NET />
    </MSG>
</MSGLST>
The hostname (your-hostname.com/ReceiveSMS), port and path will depend on the corresponding values set for the actual customer account on the Gateway.

Response

The Gateway expects the customer (server) to reply with a HTTP status code of 200 (OK) if the SMS was successfully received. Any other status value than 200 will result in the Gateway retrying delivery of the SMS at a later time. A sample successful response from the customer may be:

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.1
Content-Type: text/plain
The response should be as minimal as possible, and not contain any body unless required.

HTTP Parameters

Encoding (enc)


This parameter specifies the encoding used to interpret the URL-encoded values of the remaining parameters.

Regardless of the encoding specified, it does not allow you to send characters outside the GSM 03.38 character set. To do so you need to change the Content Type.

Also note that this is separate from the encoding specified in the Content-Type HTTP header of a POST request. The Content-Type encoding decodes the binary request body, whereas the enc parameter decodes the binary string obtained when URL-decoding the decoded body.

Supported encodings are ISO-8859-1 and UTF-8. When not specified, the encoding defaults to ISO-8859-1.

Exaple: "måløyværing" 
enc=ISO-8859-1&TXT=m%e5l%f8yv%e6ring
enc=UTF-8&TXT=m%c3%a5l%c3%b8yv%c3%a6ring

Client identification (USER and PW)


These two parameters are used to identify the client user account on the Gateway. Both username(user) and password(pw) will be assigned to you by the Gateway operator when you sign up for an account.



Session Data (SD)


A free text field that can be used to tag the session with customer specific data such as the application name, username, reference-id for end-user billing etc. The maximum length is 200 characters. Leave empty unless required.

Example:

SD=My-company-data

Text body/message (TXT)


This parameter contains the message text itself. For sending, the message length should not exceed 160 characters unless you would like to use concatenated SMS messages. 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. Messages of more than 2144 characters will be truncated. The message must/will be URL-encoded.

Example:

TXT=Please+send+me+a+copy+of+the+datamodel.+Rgds,+John
When sending logos, this parameter is not used. Instead the data is submitted with the HEX-parameter. When sending Picture-messages, you can attach an up to 120 characters long text using this parameter.

Binary message (HEX)


When sending binary messages like logos and pictures, you specify the data as a hex-string. Depending on the ContentType CT parameter, you might have to include the User Data Header part of the binary message.

Example:

HEX=0000000000000000000000000000000000000000601000080600000
1C0707C003E0E038003E0734E0072CE07C000E031DA005B8C070000207F
BA005DFE040001FFC1EA005783FF801F0046BE007D6200F8000070DA005
B0E0000000070F4002F0E000000007078001E0E00000000200000000400
00000000000000000000
The sample parameter above shows a hex-encoded 72x14 Caller Group Graphic.

The content-type (CT) parameter must always be specified when the HEX-parameter is used. Otherwise the Gateway will not be able to identify what kind of message this is.

Receiver Number (RCV)


The receiver must be a GSM cellular phone with SMS capabilities. The number must be prefixed with the country code for the recipients country and entered without the "+" or any spaces. For example, “RCV=+47 112233 44" is not valid, but "RCV=4711223344" is valid. The Gateway will perform basic validation of the number given upon sending. It is not possible to provide multiple receiver numbers.

Sender Number (SND)


Number of sender to be displayed on receiver’s handset when sending and the originating number when receiving. Numeric with no “+” or space, max 15 digits. Alphanumeric up to 11 characters can also be used when sending. Please note that no special/national characters are allowed for alphanumeric sendernumber. Only the characters a-z, A-Z, 0-9 and !”#%&’()*+-./?><; are allowed.

Content Type (CT)




Specifies the type of the content found in the TXT- or HEX parameter. Needed when sending Unicode messages or custom UDH.

For plain text (the default), only the TXT parameter is used. For the other types, only the HEX parameter is used.

See Message types for possible values.

Examples: 
CT=1&TXT=m%e5l%f8yv%e6ring
CT=9&HEX=f09fa585f09f8f9defb88fe29881696e67

Message class (CLASS)


In order to send text messages as Flash messages (displayed directly on the handset screen), the Message Class must be set to the value 0 (zero). Otherwise, do not supply this parameter when sending as other values will have no effect.

Reference (REF)


A reference value that uniquely identifying the message that this delivery report relates to. This value must be treated as a string with at least 36 characters.

State (STATE)


This property is the final state (handset status) of the message in question.

Only the value DELIVRD should be considered a positive delivery acknowledgement.

For full list of possible delivery states, see: Delivery Report Status

DeliveryTime (DELIVERYTIME)


Optional parameter. When sending SMS with 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: The date and time “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 for sending.

When receiving a delivery report, this property will give the date and time when the message was given its final state. Please note that the date and time is given in the local time zone of the SMSC used for delivery. The format is: ”yyyy.dd.mm hh:mm:ss”

Address (ADDRESS)

Mandatory for sending: Not supported Mandatory for receiving: No

Optional. This property 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.

Replace SMS (REPLACE)


Optional parameter. If set this will be an 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 also