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

Endpoint URL

The xxxx.backendless.app is a subdomain assigned to your application. For more information see the Client-side Setup section of this documentation.

https://xxxx.backendless.app/api/messaging/<channel-name>/<subscription-id>

where:

Argument                Description
<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

Important

Make sure to replace xxxx in the domain name in the sample requests below to the one assigned to your application.

Establishing a subscription:

Request:

curl -H Content-Type:application/json -X POST -d '{}' \  
-v https://xxxx.backendless.app/api/messaging/default/subscribe

Response:

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

Retrieving messages for the subscription:

Request:

curl -X GET   
-v https://xxxx.backendless.app/api/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"  
      }  
   ]  
}