tencent cloud

Scheduled and Delayed Messages
Download PDF
Last updated:2026-01-23 17:52:23
Scheduled and Delayed Messages
Last updated: 2026-01-23 17:52:23
Download PDF
This document mainly introduces the concept and use of scheduled and delayed messages in TDMQ for RocketMQ.

Relevant Concepts

Scheduled messages: After a message is sent to the server, the business may want the consumer to receive it at a later time point rather than immediately. Messages of this type are called scheduled messages.
Delayed messages: After a message is sent to the server, the business may want the consumer to receive it after a period of time rather than immediately. Messages of this type are called delayed messages.
In fact, delayed messages can be seen as a special usage of scheduled messages, and their ultimate implementation effects are the same.

Usage Methods

Open-source Apache RocketMQ does not provide an API for users to freely set delay times. To ensure compatibility with the open-source RocketMQ client, TDMQ for RocketMQ implements scheduled sending by adding specific property key-value pairs to messages. You can schedule a message for delivery at any time within a certain range (40 days) by adding the __STARTDELIVERTIME value to the property of the message. For delayed messages, you can first calculate the scheduled delivery timestamp and then send them as scheduled messages.
The following code example shows how to use the scheduled and delayed messages of TDMQ for RocketMQ. View the complete sample code.
For delayed messages, first calculate the scheduled delivery timestamp using System.currentTimeMillis() + delayTime and then send them as scheduled messages.
4.x Client
5.X Client

Message msg = new Message("test-topic", ("message content").getBytes(StandardCharsets.UTF_8));

// Set the message to be sent 10 seconds later.
long delayTime = System.currentTimeMillis() + 10000;
// Set __STARTDELIVERTIME into the property of msg.
msg.putUserProperty("__STARTDELIVERTIME", String.valueOf(delayTime));

SendResult result = producer.send(msg);
System.out.println("Send delay message: " + result);

Duration messageDelayTime = Duration.ofSeconds(10);
final Message message = provider.newMessageBuilder()
// Set topic for the current message.
.setTopic(topic)
 // Message secondary classifier of message besides topic.
.setTag(tag)
// Key(s) of the message, another way to mark message besides message id.
.setKeys("yourMessageKey-3ee439f945d7")
// Set expected delivery timestamp of message.
.setDeliveryTimestamp(System.currentTimeMillis() + messageDelayTime.toMillis())
.setBody(body)
.build();

Use Limits

When you use delayed messages, make sure that the clocks on the clients and servers are the same (all regions use UTC+8) to avoid time differences.
Scheduled and delayed messages have a time deviation of approximately 1 second.
The allowable time range for scheduled and delayed messages varies depending on the cluster specifications. For more information, see Product Series.
For scheduled messages, the scheduled time should be a future time. If it is earlier than the current time, the messages are delivered to consumers immediately.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback