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