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
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 certificatesNote:
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)
- Mandatory for sending: No
- Mandatory for receiving: Not supported
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)¶
- Mandatory for sending: Yes
- Mandatory for receiving: Not supported
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)
- Mandatory for sending: No
- Mandatory for receiving: Not supported
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)¶
- Mandatory for sending: No
- Mandatory for receiving: Yes
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)
- Mandatory for sending: No
- Mandatory for receiving: Not supported
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)
- Mandatory for sending: Yes
- Mandatory for receiving: Yes
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)
- Mandatory for sending: No
- Mandatory for receiving: Yes
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)
- Mandatory for sending: No
- Mandatory for receiving: Not supported
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)
- Mandatory for sending: No
- Mandatory for receiving: Not supported
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)
- Mandatory for receiving: Yes
- Mandatory for sending: Not supported
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)
- Mandatory for receiving: Yes
- Mandatory for sending: Not supported
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 StatusDeliveryTime (DELIVERYTIME)
- Mandatory for sending: No
- Mandatory for receiving: No
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)
- Mandatory for sending: No
- Mandatory for receiving: Not supported
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