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"  
      }  
   ]  
}

Codeless Reference

where:

Argument	Description
id	The unique identifier of the event listener.
channel	Name of the channel to subscribe to.
selector	A selector is a query expressed in the SQL-92 syntax and formatted as the condition part of the SQL's WHERE clause. The condition references headers in the published messages.
message	When a listener gets triggered, it assigns data of the message matching the where clause condition to this variable(message).

This operation does not return a value.

The example below creates a message listener named "my-listener-1" for the "default" channel. When a message is published to the "default" channel the listener gets triggered and saves the message content to the message variable. Then the data stored in the message variable gets printed.