Polling JSON REST API

Modified on Wed, 03 Aug 2022 09:47 by FM — Categorized as: Uncategorized

You can poll for mobile originated messages (MO) and delivery reports (DR) using our JSON REST API.


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.

Authentication

Requests are authenticated using Basic authentication and your credentials are the same as for sending messages to the gateway.

REST methods

None of the following methods require a request body.

Poll

POST /api/output/rest/{payloadtype}/gateway/{userid}?ackrequired=true|false

Parameters

Path parameter Possible values Description
payloadtype mo|dr What kind of message you are polling for
userid Your gateway username Must be the same as in your basic auth header
ackrequired true|false Wether or not you want the message to stay in the queue until acked

The ackrequired parameter defines wether or not the message/dr is removed from the queue upon retrieval or if it should be removed by a separate ack request. If you set it to true the message/dr will be returned to the queue after 20 seconds with no ack sent.

Possible HTTP responses

Code Result Body
200 A message was found and returned See Example MO response or Example DR response
401 You are not allowed to access this queue, check your credentials See Example Error Response
404 At the moment there are no more messages in your queue, try again later See Example Error Response
500 Something unexpected happened See Example Error Response

Ack

PUT /api/output/rest/{payloadtype}/gateway/{userid}/ack/{reference}

Parameters

Path parameter Possible values Description
payloadtype mo|dr What kind of message you are acking
userid Your gateway username Must be the same as in your basic auth header
reference GUID The GUID reference returned by the poll request

Possible HTTP responses

Code Result Body
204 The message was successfully acknowledged No content
401 You are not allowed to access this queue, check your credentials See Example Error Response
404 The message with the provided reference does not exist or has already been acknowledged See Example Error Response
500 Something unexpected happened See Example Error Response

Example requests

Polling MO with no ack required

Request 
POST https://poll.pswin.com/api/output/rest/mo/gateway/myuser?ackrequired=false
Authorization: Basic kja934msf99w3==
Response 
200 OK
Content-Type: application/json
 
{
    "sender": "4712345678",
    "receiver": "1234",
    "text": "Some text",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}

Polling MO with ack required

Request 
POST https://poll.pswin.com/api/output/rest/mo/gateway/myuser?ackrequired=true
Authorization: Basic kja934msf99w3==
Response 
200 OK
Content-Type: application/json
 
{
    "sender": "4712345678",
    "receiver": "1234",
    "text": "Some text",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}
Ack Request 
PUT http://poll.pswin.com/api/output/rest/mo/gateway/myuser/ack/7e5ac56a-4c79-6e8a-6431-24ac84f49fe2
Authorization: Basic kja934msf99w3==
Ack Response 
204 No Content
Content-Type: text/html

Polling DR with no ack required

Request 
POST https://poll.pswin.com/api/output/rest/dr/gateway/myuser?ackrequired=false
AUTHORIZATION: BASIC kja934msf99w3==
Example response 
200 OK
Content-Type: application/json
 
{
    "receiver": "4712345678",
    "state": "DELIVRD",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}

Polling DR with ack required

Request 
POST https://poll.pswin.com/api/output/rest/dr/gateway/myuser?ackrequired=true
Authorization: Basic kja934msf99w3==
Response 
200 OK
Content-Type: application/json
 
{
    "receiver": "4712345678",
    "state": "DELIVRD",
    "operatorTimestamp": "2017-11-08T13:37:00Z",
    "reference": "7e5ac56a-4c79-6e8a-6431-24ac84f49fe2"
}
Ack Request 
PUT http://poll.pswin.com/api/output/rest/dr/gateway/myuser/ack/7e5ac56a-4c79-6e8a-6431-24ac84f49fe2
Authorization: Basic kja934msf99w3==
Ack Response 
204 No Content
Content-Type: text/html

Other

Example error response

404 Not Found
Content-Type: application/json

{
    "statusCode": 404,
    "message": "The resource you have requested cannot be found.",
    "details": "Error details are currently disabled."
}