Skip to content

Retrieve Messages

The API returns messages for a subscription. To establish a subscription use the Channel Subscription API. If the subscription includes a selector (conditional delivery), only the messages which match the selector will be returned in the response. Otherwise, the response includes all messages received in the past 60 seconds. The expiration timeframe for the messages can be modified in the Backendless Pro version of the product. Messages previously returned to the client are excluded for the subsequent requests.

Method

GET

URL

https://api.backendless.com/<application-id>/<REST-api-key>/messaging/<channel-name>/<subscription-id>

where:

Argument                Description
<application-id> the ID of your application generated upon its creation. You can get the value in the Manage > App Settings section of the Backendless Console.
<REST-api-key> REST API key of your application. You can get the value from the Manage > App Settings section of the Backendless Console.
<subscripton-id> ID of the subscription to retrieve the messages for. It must be obtained with the Channel Subscription API request.

Request headers

user-token: optional value obtained as a result of the login operation.

where:

Argument                Description
user-token Optional header. Contains a value returned by Backendless in a preceding user Login API call. If user-token is set in the request, the operation will be executed with the security policy associated with the currently logged in user. This means all the permissions and roles assigned to the user will be enforced by Backendless.

Request Body:

None

Response Body

{  
  "messages":   
  [  
    {  
      "messageId":"value",  
      "data":value,  
      "publishedAt":timestamp,  
      ["publisherId":value,]  
      ["headers": {"key1":"value1","key2":"value2"}]  
    },  
    ...  
  ]  
}

Each message in the response contains the following parameters:

Argument                Description
messageId unique message ID. The ID is assigned at the time of message publishing.
headers an array which is a collection of key/value pairs. Includes all the headers included with the message publishing. Additionally, Backendless adds the BL_APPLICATION_ID header which contains the application ID.
data message payload. It is the object published with the Publishing API or Backendless Console.
publisherID the property contains sender (publisher) ID, if it is provided by the publisher.
publishedAt a timestamp indicating when the message was received by Backendless from the publisher.

Example

Establishing a subscription:

Request:

curl -H Content-Type:application/json -X POST -d '{}' \  
-v https://api.backendless.com/APP-ID/REST-API-KEY/messaging/default/subscribe

Response:

{  
"subscriptionId":"1BA31C04-CDCA-2AC0-FF76-6E6F81101100"  
}

Retrieving messages for the subscription:

Request:

curl -X GET   
-v https://api.backendless.com/APP-ID/REST-API-KEY/messaging/default/1BA31C04-CDCA-2AC0-FF76-6E6F81101100

Response:

{  
  "messages":[  
      {  
         "headers":{  
            "DSId":"FC6FB0BB-4449-0D1D-FFAE-4670D1138200",  
            "DSDstClientId":"AD12813D-7BC1-A216-FF65-E86D00A14000",  
            "BL_APPLICATION_ID":"3FAD6F76-617D-7EDD-FF4D-AE26C5C04F00",  
            "BL_VERSION_URL_PREFIX":"v1"  
         },  
         "publishedAt":1359071622226,  
         "publisherId":null,  
         "data":"Hello World",  
         "messageId":"D98A994C-7EF6-7DE2-FFC3-95807BDF8700-4428"  
      }  
   ]  
}