Consuming Messages

Consume messages from a queue and its channels.

Consuming messages requires permissions to the queue and access to its Messages endpoint.

A response to a GetMessages request contains the list of messages with their payload, message ID, expiration time, visibility timeout, delivery count, and a receipt. The maximum number of messages that can be returned in one response is 20, but the actual number of messages returned depends on the number of available messages and whether the request used long polling.

Consumers are responsible for updating messages and deleting messages, which require the message's receipt.

Message locking

Consumers can "lock" a message retrieved from the queue so that another consumer can't retrieve the same message. Messages are locked by specifying a visibility timeout. The Queue API uses the visibilityInSeconds parameter to set this value.

The visibility timeout can be set at the queue level when creating a queue, or it can be specified when consuming or updating messages. If a consumer is having difficulty successfully processing a message, it can update the message to extend its invisibility. If a message's visibility timeout isn't extended, and the consumer doesn't delete the message, it returns to the queue.

When consuming, you don't need to specify the visibility timeout. The visibility timeout configured for the queue applies to the request. When creating a queue, the default visibility timeout is 30 seconds. If you include the optional visibility timeout parameter in a request, you can specify a minimum value of 0 seconds and a maximum value of 12 hours.

Using a visibility timeout of 0 effectively acts as a peek functionality. Messages retrieved this way will most likely be delivered to another consumer, because their visibility doesn't change.

Delivery count

Each time a message is retrieved using a GetMessages request, or by Console polling, its delivery count increases. If the delivery count exceeds the queue's configured maximum, the message is sent to the dead letter queue.

Long polling

By default, a GetMessages request uses long polling. The request waits for messages for 30 seconds, and if the timeout passes and no messages are available for consumption, the request returns an empty response. Long polling is useful to prevent tight loop retries on empty responses.

Consumers can change this behavior by including the timeoutInSeconds parameter in their request, which accepts values of 0 to 30 seconds. Setting the timeoutInSeconds value to 0 results in an immediate response from the queue, whether or not there are messages available.