Scheduled Messages

Schedule, manage, and monitor messages to be sent at a future time

im.scheduledMessages lets you create messages that the server will send at a specified time. You can update or delete them before they fire, execute them immediately, and stream lifecycle events.

Create a scheduled message

const scheduled = await im.scheduledMessages.create({
  chat: directChat("[phone]"),
  projectId: "my-project",
  text: "Happy New Year!",
  scheduledFor: new Date("2025-12-31T23:59:00Z"),
  service: "iMessage",
  subject: "NYE",
  effectId: MessageEffect.fireworks,
  clientMessageId: "nye-2025",
});

CreateScheduledMessageOptions

Field	Type	Required	Description
chat	ChatGuid	Yes	Destination conversation
projectId	string	Yes	Project namespace
scheduledFor	Date	Yes	When to send the message
text	string	No	Message text
service	"iMessage" | "SMS" | "RCS"	No	Service to use
subject	string	No	Subject line
effectId	string	No	Send effect ID
attachmentPath	string	No	Path to an attachment
attachmentName	string	No	Attachment display name
clientMessageId	string	No	Idempotency key
schedule	{ type: "once" } | { type: "recurring"; intervalSeconds: number }	No	Single or recurring schedule

Get a scheduled message

const scheduled = await im.scheduledMessages.get(scheduledMessageId);

List scheduled messages

list() takes no parameters and returns a plain array of all scheduled messages:

const messages = await im.scheduledMessages.list();
for (const msg of messages) {
  console.log(msg.scheduledFor, msg.status);
}

Update a scheduled message

Only pass the fields you want to change. Returns the updated ScheduledMessage.

const updated = await im.scheduledMessages.update(scheduledMessageId, {
  scheduledFor: new Date("2026-01-01T00:00:00Z"),
  text: "Happy New Year! (updated)",
});

Delete a scheduled message

await im.scheduledMessages.delete(scheduledMessageId);

Delete all scheduled messages

await im.scheduledMessages.deleteAll();

Execute immediately

Trigger a scheduled message before its scheduled time:

await im.scheduledMessages.execute(scheduledMessageId);

Execute all due messages

Execute all scheduled messages that have passed their scheduledFor time:

const executed = await im.scheduledMessages.executeDue();
// executed: ScheduledMessage[]

Real-time schedule events

for await (const event of im.scheduledMessages.subscribe()) {
  // event.type === "schedule.changed"
  console.log(event.action, event.scheduledMessage);
}

ScheduleEvent actions

Action	When it fires
created	A new scheduled message was created
updated	A scheduled message was modified
deleted	A scheduled message was removed
sent	The server sent the message successfully
failed	The server failed to send the message

ScheduledMessage shape

interface ScheduledMessage {
  id: ScheduledMessageId;
  scheduledFor: Date;
  status: ScheduledMessageStatus;
  payload: Uint8Array;
  schedule: Uint8Array;
  type: string;
  createdAt: Date;
  sentAt?: Date;
  errorMessage?: string;
}

ScheduledMessageStatus values

Value	Description
"pending"	Waiting to be sent
"inProgress"	Currently being processed
"complete"	Sent successfully
"failed"	Failed to send (check errorMessage)