This document describes how to use the interface for receiving SMS
and Delivery Reports using a polling service. Normally the Gateway
will push MO messages and delivery reports to the client. However, in
some cases regulations or restrictions may prohibit pushing of traffic
into the clients network or system. In those cases, PSWinCom offers
an API for polling the Gateway for new MO messages and delivery
reports.
This document is intended for developers only, and basic knowledge of
usage of PSWinCom Gateway is required.
Before reading this document you should be familiar with at least one
of the alternative interfaces of PSWinCom Gateway.
Also refer to the product web for more information.
Gateway connect information
Endpoint URL
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 certificatesPolling Services
Overview
Usage of this API must be handled carefully, as continuously polling
towards the system may degrade performance. When the poll-request
returns no messages, the client should wait at least 10 seconds before
issuing a new poll-request. When the poll-request returns a message,
a new request may be issued immediately until the request returns
empty.
The Gateway has separate polling queues for MO messages and
Delivery Reports. They may therefore be retrieved independent of
each other.
Direct fetch versus acknowledged fetch
The service has two variants of fetching messages. They are both
explained below:
Direct fetch
By setting the ackRequired parameter to false when fetching either an
MO message or a Delivery Report, the Gateway will pull the oldest MO
message off the queue and return it. If the response is lost, or the
client application fails to process it, the message will be lost. A direct
fetch should be used when speed is more important than avoiding the risk of
losing a message or delivery report.
Acknowledged fetch
By setting the ackRequired parameter to true when fetching either an
MO message or a Delivery Report, the Gateway will peek on the oldest
MO message in the queue and return it, but NOT remove it from the
queue. Subsequent calls with ackRequired set to true will thus result in
the same message or delivery report be returned every time.
The client application must call AcknowledgeMessage or
AcknowledgeDeliveryReport with the messageId of every fetched
message to inform the Gateway that the MO message or Delivery
With this scenario you will need two calls to the Gateway for each
message or delivery report, and that will impact on performance.
However, it will secure that all messages and delivery reports are
successfully transmitted to the client application.
Report has been fetched and processed.
Objects/complex types
FetchResponse
The FetchNextMessage method will return a response value object
called FetchResponse. This object has attributes described as follows:
| Attribute |
Description |
| StatusCode |
Integer. Statuscode indicating whether the
operation was successful or failed. A
statuscode of 200 represents a successful
operation. Otherwise the StatusCode will
indicate a failure, and the Description attribute
will contain further information. |
| StatusDescription |
String. Textual descriptions of the statuscode
given by the StatusCode attribute. |
| MessageID |
String. When a message is successfully
fetched, this attribute will contain a unique ID
for this message. If using acknowledged fetch,
this is the ID that must be used to
acknowledge the message. |
| MessageTimestamp |
String. When a message is successfully
fetched, this attribute will contain a timestamp
of when this message was created on the
Gateway. It can be used to identify old MO
messages that may no longer be relevant to
process. Format: “yyyy.MM.dd hh:mm:ss”
using CET timezone. |
| SMSMessage |
The message object. When a message is
successfully fetched, this attribute will contain
the MO message details. Format of this
message is described in the ordinary SOAP
interface specification. |
C# notation of the FetchResponse object:
public class FetchResponse
{
public int StatusCode;
public string StatusDescription;
public string MessageID;
public string MessageTimestamp;
public IncomingSMSMessage SMSMessage;
public FetchResponse ()
{
}
}
FetchDRResponse
The FetchNextDeliveryReport method will return a response value
object called FetchDRResponse. This object has attributes described as
follows:
| Attribute |
Description |
| StatusCode |
Integer. Statuscode indicating whether
the operation was successful or failed. A
statuscode of 200 represents a
successful operation. Otherwise the
StatusCode will indicate a failure, and
the Description attribute will contain
further information. |
| StatusDescription |
String. Textual descriptions of the
statuscode given by the StatusCode
attribute. |
| DeliveryReportID |
String. When a delivery report is
successfully fetched, this attribute will
contain a unique ID for this delivery
report. If using acknowledged fetch, this
is the ID that must be used to
acknowledge the delivery report. |
| DeliveryReportTimestamp |
String. When a message is successfully
fetched, this attribute will contain a
timestamp of when this delivery report
was created on the Gateway. Format:
“yyyy.MM.dd hh:mm:ss” using CET
timezone. |
| DeliveryReportMessage |
The delivery report object. When a
delivery report is successfully fetched,
this attribute will contain the delivery
report details. Format of this delivery
report is described in the ordinary SOAP
interface specification. |
C# notation of the FetchDRResponse object:
public class FetchDRResponse
{
public int Code;
public string Description;
public string DeliveryReportID;
public string DeliveryReportTimestamp;
public DeliveryReport DeliveryReportMessage;
public FetchDRResponse ()
{
}
}
AcknowledgeResponse
The AcknowledgeMessage and AcknowledgeDeliveryReport methods
will return a response value object called AcknowledgeResponse. This
object has attributes described as follows:
| Attribute |
Description |
| Code |
Integer. Statuscode indicating whether the
operation was successful or failed. A statuscode of
2xx represents a successful operation. Otherwise
the Code will indicate a failure, and the
Description attribute will contain further
information. |
| Description |
String. Textual descriptions of the statuscode
given by the Code attribute. |
C# notation of the AcknowledgeResponse object:
public class AcknowledgeResponse
{
public int StatusCode;
public string StatusDescription;
public AcknowledgeResponse ()
{
}
}
Status codes
| Code |
Description |
| 200 |
Operation was successful. |
| 210 |
Message acked ok. |
| 301 |
Username/Password invalid. |
| 302 |
No outbound queue found. Either you
account is not properly configured, or you
have not yet received any messages. |
| 303 |
No new messages to receive. Please wait
before retrying. |
| 312 |
No outbound queue found. Either you
account is not properly configured, or you
have not yet received any delivery reports. |
| 313 |
No message with that ID was found. |
| 314 |
An error occured while trying to
acknowledge the delivery report. |
Methods
FetchNextMessage
This method is used to fetch a single SMS MO message from the
Gateway.
Syntax:
FetchResponse r = FetchNextMessage(
string username,
string password,
bool ackRequired)
The
username and
password parameters are string values containing
user id and password for your PSWinCom SMS Gateway account. The
ackRequired parameter is a Boolean value indicating whether the
message should be retrieved directly, or if an acknowledge is required.
FetchNextDeliveryReport
This method is used to fetch a delivery report message from the
Gateway.
Syntax:
FetchDRResponse r = FetchNextDeliveryReport(
string username,
string password,
bool ackRequired)
The
username and
password parameters are string values containing
user id and password for your PSWinCom SMS Gateway account. The
ackRequired parameter is a Boolean value indicating whether the
delivery report should be retrieved directly, or if acknowledge is
required.
AcknowledgeMessage
This method is used to acknowledge a received SMS MO Message.
Syntax:
AcknowledgeResponse r = AcknowledgeMessage(
string username,
string password,
string messageId)
The
username and
password parameters are string values containing
user id and password for your PSWinCom SMS Gateway account. The
messageId is the ID of the message received that you want to
acknowledge that you have received and processed successfully.
The method will return a response object of type
AcknowledgeResponse. This object is described in 4.3
AcknowledgeResponse.
AcknowledgeDeliveryReport
This method is used to acknowledge a received SMS MO Message.
Syntax:
AcknowledgeResponse r = AcknowledgeDeliveryReport(
string username,
string password,
string messageId)
The
username and
password parameters are string values containing
user id and password for your PSWinCom SMS Gateway account. The
messageId is the ID of the delivery report received that you want to
acknowledge that you have received and processed successfully.
The method will return a response object of type
AcknowledgeResponse. This object is described in 4.3
AcknowledgeResponse.
Source code example