schedule_message
Schedules a WhatsApp message (text, or a file with optional caption) to one person or group for a later time, once or repeating (e.g. "every Monday at 9:00"). Paid plan only: on the free plan the call is refused with a note on how to subscribe. to works like send_message's and is resolved now, so a wrong name fails right away. Time: pass send_at as an ISO 8601 date-time with the user's UTC offset for that date (e.g. "2026-10-10T09:00:00-06:00"), and timezone as the user's IANA timezone (e.g. "America/Mexico_City"). Use the timezone and current time you know for the user; if you don't know them, ask. Mind daylight saving time: the offset must be the one in effect on that date. The first send must be in the future and at most a year ahead. Messages go out within about a minute of send_at; if the server is down for more than an hour past send_at, that send is marked missed instead of being sent late. Repeats: recurrence once (default), daily, weekly, biweekly, monthly, quarterly, semesterly or yearly, always at the same local time (a monthly message on the 31st goes on the last day of shorter months); optional until (a date like "2026-12-31", or a date-time with offset) ends the series. Each send is tried once: a failure is recorded (see list_scheduled_messages) and the series continues. Quoted replies aren't supported. Files: media.url or media.message_id (checked now and fetched again at send time; message_id only for one-off messages, so prefer a link); media.data isn't accepted. The result gives the local time and how long until it (when) and, for repeats, the first sends: read them back to the user. To change a scheduled message, cancel it with cancel_scheduled_message and schedule it again. At most 100 upcoming scheduled messages per account. If you are writing the text yourself rather than sending words the user gave you, call get_writing_style for this chat first and write it the way the user writes; skip that for dictated text. To protect the user's number from WhatsApp's anti-spam bans, messages that start a conversation with someone who hasn't messaged the user in the last 90 days may be limited to 1 per minute and 10 every 12 hours; the result says so and explains why when it happens. People who have written to the user are never limited. Confirm the recipient, text, file and time with the user first unless they already gave them. Returns the scheduled message { id, series_id (shared by every send of a repeating message), status (scheduled, processing, sent, failed, missed or cancelled), recipient (contact fields (name; name_source: address_book, push_name, group_subject, business, phone or unresolved; canonical_jid: the JID to pass to send_message and read_chat_history; phone_jid and lid_jid: the chat's phone-number and LID forms, null when unknown or for groups; phone_display: the number as +).), text?, media?, send_at (UTC), send_at_local, when (readable local time and how far away), timezone, recurrence, occurrence? (0 = first send of a series), until?, sent_at?, message_id? (once sent), error? (why it failed or was missed) } plus next_occurrences for repeats.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Contact name, phone number with country code, chat JID (person or group), or a group's exact name. | |
| text | No | The message text. With media, the caption of a photo, video or document. Required unless media is given. | |
| media | No | Optional. A file to send: pass exactly one of url or message_id. The file is fetched when the message is sent. | |
| until | No | Optional, repeats only. Last day of the series: a date ("2026-12-31", through the end of that day) or a date-time with offset. | |
| send_at | Yes | When to send (the first send, for repeats): ISO 8601 with the UTC offset in effect on that date, e.g. "2026-10-10T09:00:00-06:00". | |
| timezone | Yes | The user's IANA timezone, e.g. "America/Mexico_City". Repeats keep the same local time in it, across daylight saving changes. | |
| recurrence | No | Optional. How often to repeat (default once). |