Any outgoing message can be scheduled instead of sent immediately, by adding a schedule_date to the request.

This works the same way for every send method — sendMessage, sendPhoto, sendVideo, sendDocument and the rest. There is no separate "schedule" method.

Scheduling a message

Field Type Required Description
schedule_date Long Optional Unix Epoch timestamp in milliseconds at which the message should be sent. Omit it to send immediately.

Everything else about the request is unchanged.

Example — scheduling a text message

{
  "method": "sendMessage",
  "chat_id": "90090684293000559",
  "text": "Your appointment is tomorrow.",
  "reference": 111111170,
  "schedule_date": 1743699509087
}

SDK Mapping — scheduling

The SDK send helpers accept schedule_date through the out-message object rather than as a positional argument:

SDK How to set it
Java message.setScheduleDate(1743699509087L); before api.send(message);
JavaScript message.schedule_date = 1743699509087; before api.send(...)
Python message.schedule_date = 1743699509087 before napi.send(...)

Receiving a scheduled message

When a scheduled message is delivered, it arrives as scheduledMessage rather than message. The body is identical to a normal incoming message and additionally carries schedule_date.

SDK Callback
Java onScheduleMessage(IncomingMessage incomingMsg)
JavaScript onScheduleMessage(incomingScheduleMsg)
Python on_schedule_message(self, incoming_message)

Cancelling a scheduled message

Use cancelMessageSchedule to stop a scheduled message before it is sent.

Field Type Required Description
method String Yes "cancelMessageSchedule"
message_id String Yes The id of the scheduled message to cancel. The request is ignored if this is missing.

Example