SCHEDULED MESSAGES

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

json
{
  "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

json
{
  "method": "cancelMessageSchedule",
  "message_id": "5121960361126208"
}

⚠️ No acknowledgement is returned. cancelMessageSchedule is fire-and-forget — there is no _ack, and none of the SDKs expose a helper for it today. To send it you must build the request yourself and pass it through the SDK's generic send.