Changes the visibility timeout of a consumed message, controlling how long it remains invisible to other consumers before becoming available for redelivery.
How it works
When a consumer receives a message from a queue, the message becomes invisible to other consumers for a duration called the visibility timeout. During this period, the consumer processes and deletes the message. If processing takes longer than expected, call ChangeMessageVisibility to extend the timeout and prevent another consumer from receiving the same message.
The new visibility timeout starts from the moment the ChangeMessageVisibility call is made, not from when the message was originally received.
Example: A queue has a 60-second visibility timeout. A consumer receives a message and begins processing. After 15 seconds, processing is still underway, so the consumer calls ChangeMessageVisibility with VisibilityTimeout set to 30. The message stays invisible for 30 more seconds from that call -- it becomes visible again 45 seconds after it was first received (15 + 30), not 90 seconds (60 + 30).
Authorization
By default, only Alibaba Cloud accounts can call this operation. Resource Access Management (RAM) users must be granted the required permissions first. For details, see Permission policies and examples.
| Item | Value |
|---|---|
| API | ChangeMessageVisibility |
| Action | mns:ChangeMessageVisibility |
| Resource | acs:mns:$region:$accountid:/queues/$queueName/messages |
Request
Request line
PUT /queues/$queueName/messages?receiptHandle=<receiptHandle>&visibilityTimeout=<visibilitytimeout> HTTP/1.1URI parameters
| Parameter | Type | Required | Example | Description |
|---|---|---|---|---|
| ReceiptHandle | String | Yes | MbZj6wDWli+QEauMZc8ZRv37sIW2iJKq3M9Mx/KSbkJ0 | The receipt handle returned when the message was last consumed. For details, see ReceiveMessage. |
| VisibilityTimeout | Integer | Yes | 50 | The new visibility timeout in seconds. Valid values: 1 to 43200 (1 second to 12 hours). |
Request headers
No operation-specific request headers. Only common request headers are used.
Request body
None.
Response
Status code
HTTP/1.1 200 OKResponse headers
No operation-specific response headers. Only common response headers are returned.
Response body
The response body is in XML format:
| Parameter | Type | Example | Description |
|---|---|---|---|
| ReceiptHandle | String | TbZj6wDWli+9CEauMZc8ZRv37sIW2iJKq3M9Mx/TS1 | A new receipt handle, valid until NextVisibleTime. Use this handle for subsequent delete or modify operations on the message. The previous receipt handle is no longer valid. |
| NextVisibleTime | Long | 1250700979298000 | The time when the message becomes visible again, as a UNIX timestamp in milliseconds since January 1, 1970, 00:00:00 UTC. |
Examples
Sample request
PUT /queues/$queueName/messages
?receiptHandle=MbZj6wDWli+QEauMZc8ZRv37sIW2iJKq3M9Mx/KSbkJ0&visibilityTimeout=50 HTTP/1.1
Host: $AccountId.mns.cn-hangzhou.aliyuncs.com
Date: Wed, 28 May 2012 22:32:00 GMT
x-mns-version: 2015-06-06
Authorization: MNS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIEXA****Sample response
HTTP/1.1 200 OK
x-mns-request-id:512B2A634403E52B1956****
x-mns-version: 2015-06-06<?xml version="1.0" encoding="UTF-8"?>
<ChangeVisibility xmlns="http://mns.aliyuncs.com/doc/v1/">
<ReceiptHandle>TbZj6wDWli+9CEauMZc8ZRv37sIW2iJKq3M9Mx/TS1</ReceiptHandle>
<NextVisibleTime>1250700979298000</NextVisibleTime>
</ChangeVisibility>Error codes
| Error code | Error message | HTTP status code | Description |
|---|---|---|---|
| InvalidArgument | The value of Element must be between Low and High seconds/bytes. | 400 | The parameter value is out of range. Specify a value within the valid range. |
| ReceiptHandleError | The receipt handle you provided is not valid. | 400 | The receipt handle is invalid. Get a valid receipt handle by calling ReceiveMessage. |
| QueueNotExist | The queue name you provided does not exist. | 404 | The specified queue does not exist. Verify the queue name or create the queue first. |
| MessageNotExist | The receipt handle you provided has expired. | 404 | The message became visible again before processing completed, and the receipt handle expired. Consume messages before the visibility timeout expires, or extend the timeout by calling ChangeMessageVisibility sooner. |
Related operations
The following operations are commonly used together in a message processing workflow:
ReceiveMessage -- Receive a message and get its receipt handle.
ChangeMessageVisibility -- Extend the visibility timeout if processing takes longer than expected.
DeleteMessage -- Delete the message after processing completes.