PSWinCom Gateway Polling API For Retrieving Delivery Reports and MO SMS Messages

Modified on Mon, 03 Jul 2017 15:21 by tormar — Categorized as: Uncategorized

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 certificates



Polling 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