All Products
Document Center


Last Updated: Jul 23, 2019


This interface is used by the consumer to consume messages in a queue in batches. A maximum of 16 messages can be acquired in one BatchReceiveMessage operation.This operation will change the acquired messages to Inactive status. The Inactive duration is determined by the VisibilityTimeout attribute of the queue (for details, see “CreateQueue Interface”).

After the messages are successfully consumed, the DeleteMessage interface should be called to delete the acquired messages in the VisibilityTimeout period. Otherwise, the acquired messages will be reset to Active status and consumable again.


A request mainly includes the following parts:

  • Request line

    GET /queues/$queueName/messages?numOfMessages=16&waitseconds=10 HTTP/1.1

  • Special URI Parameter

Parameter Name Description Required?
numOfMessages Maximum number of messages that can be acquired for the current BatchReceiveMessage operation. Required
waitseconds Maximum polling waiting time① of the ReceiveMessage request, measured in seconds. Optional


The polling waiting time of the BatchReceiveMessage request is specified by its preset waitseconds, or the PollingWaitSeconds attribute of the queue without presetting waitseconds (refer to “CreateQueue Interface”).

  • Special Request Header

    None. See “Public Request Headers”.

  • Request Body



The returned message includes 3 parts: returned status line, HTTP header and message body.

  • HTTP Status Code

    HTTP/1.1 200 OK

  • Special Response Header

    None. See Public Returned Headers.

  • Response Body

    The return result is in XML format. The message bodies and attributes of multiple messages are returned.

Parameter Name Description
MessageId Message ID, which is unique in one queue
ReceiptHandle Temporary handle generated for the acquired message, which is used to delete or modify the message in Inactive status and is valid before NextVisibleTime.
MessageBody Message body
MessageBodyMD5 MD5 value of the message body
EnqueueTime Time when a message is sent to the queue, represented in milliseconds that have elapsed since 1970-1-1 0:00
NextVisibleTime Time when a message can be consumed again, represented in milliseconds that have elapsed since 1970-1-1 0:00
FirstDequeueTime Time when a message is consumed for the first time, represented in milliseconds that have elapsed since 1970-1-1 0:00
DequeueCount Total consumption times of a message
Priority Priority of a message

Special Error

Error Code Error Message Status Code
QueueNotExist The queue name you provided is not exist. 404
MessageNotExist Message not exist. 404

Request example:

  1. GET /queues/$queueName/messages?numOfMessages=16 HTTP/1.1
  2. Host: $
  3. Date: Wed, 28 May 2012 22:32:00 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXAMPLE

Response example:

  1. HTTP/1.1 200 OK
  2. Connection:close
  3. Content-Type=text/xml;charset=utf-8
  4. Content-Length:500
  5. x-mns-request-id:512B2A634403E52B1956133E
  6. x-mns-version: 2015-06-06
  7. <?xml version="1.0” encoding=”UTF-8” ?>
  8. <Messages xmlns=””>
  9. <Message>
  10. <MessageId>5F290C926D472878-2-14D9529A8FA-200000001</MessageId>
  11. <ReceiptHandle>1-ODU4OTkzNDU5My0xNDMyNzI3ODI3LTItOA==</ReceiptHandle>
  12. <MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6D8C7</MessageBodyMD5>
  13. <MessageBody>This is a test message</MessageBody>
  14. <EnqueueTime>1250700979248</EnqueueTime>
  15. <NextVisibleTime>1250700799348</NextVisibleTime>
  16. <FirstDequeueTime>1250700779318</FirstDequeueTime >
  17. <DequeueCount>1</DequeueCount>
  18. <Priority>8</Priority>
  19. </Message>
  20. <Message>
  21. <ReceiptHandle>1-ODU4OTkzNDU5My0xNDMyNzI3MjQwLTEtOA==</ReceiptHandle>
  22. <MessageBodyMD5>C5DD56A39F5F7BB8B3337C6D11B6D8C7</MessageBodyMD5>
  23. <MessageBody>This is a test message</MessageBody>
  24. <EnqueueTime>1250700979252</EnqueueTime>
  25. <NextVisibleTime>1250700799350</NextVisibleTime>
  26. <FirstDequeueTime>1250700779330</FirstDequeueTime >
  27. <DequeueCount>1</DequeueCount>
  28. <Priority>8</Priority>
  29. </Message>
  30. </Messages>