# Scheduled Messages

## Overview

Scheduled Messages let you queue a WhatsApp send for a future time — once, or on a repeating schedule. Find the feature under More → Scheduled. It's the right tool for time-sensitive sends you want to set and forget: a launch announcement at 9:00 AM, a weekly digest every Monday, or a monthly statement reminder.

Each schedule tracks its own recipients and reports back delivery results, so the detail page shows who was sent, delivered, read, or failed. WaDesk shows you the next run time, and the actual sending runs automatically in the background — even when you're not logged in.

> Access: Scheduled Messages require the Manager workspace role or higher and a plan that includes the Scheduled messages feature. Your plan also sets a limit on how many schedules the workspace can create.

## Creating a Schedule

Click New schedule on the list page and fill in the composer:

1. Name it. Enter a schedule name for your own reference in reports and the list view.
2. Choose the schedule type. Pick Once or Recurring (see Once vs Recurring).
3. Pick the sender number(s). Choose one number, or several for a multi-device send (see Multi-Device & Audience). The picker matches the active engine, so a Cloud API / Twilio workspace doesn't see old Unofficial API phones.
4. Compose the message. Choose the message type — Plain text, an approved Template, a Media attachment, or a Location pin. Only approved templates appear in the picker.
5. Choose the audience. Set the recipient type to a Group, a Queue (the audience of a past completed broadcast), or typed Numbers (see Recipients).
6. Set the date, time, and time zone. See Time Zones & Lead Time. For recurring schedules, also set the repeat pattern and optional end date.

When you submit, WaDesk checks the schedule, adds each recipient to the list as pending so the detail page can show who will receive it, records which engine it's using, and registers the job to fire at the chosen time. The schedule then shows as scheduled (once) or running (recurring).

> Lead time: A schedule must be set at least 2 minutes in the future, or the form shows "Schedule must be at least 2 minutes from now." This gives the system time to set it up and avoids time-zone edge cases. The send date itself must be today or later.

## Message Types

Pick what the schedule sends:

Type | What it sends
--- | ---
Plain | A free-text message.
Template | An approved template — its body, header, footer, buttons, and carousel, with contact details filled in per recipient when it fires.
Media | An uploaded image, video, or document (up to 50 MB) with an optional caption.
Location | A pinned map location (needs a latitude and longitude).

On the Business API engine, an approved Meta template gets its full message built for each recipient before each run, so buttons, carousels, and media headers send correctly — and the same ban-prevention checks (approval, not paused, above the quality floor, reachable media) run before any sending allowance is spent.

## Recipients

Set the recipient type to populate exactly one target source:

Type | Source | Refreshed at send time?
--- | --- | ---
Group | One or more contact groups. | Yes (single number) — the group's members are re-checked when the job fires, so contacts added later are still included.
Queue | One or more past completed broadcasts; their original recipients are re-targeted. The picker lists up to 50 recent completed sends. | Taken from each broadcast's recipient list.
Number | Phone numbers typed directly (each 8–20 characters). | Fixed at the typed list.

If the selected recipients add up to no valid numbers, the form shows "Selected recipients are empty." Each number is matched to a workspace contact where possible, so the detail page can show a name.

## Once vs Recurring

Schedules come in two types:

- Once — fires a single time at the date and time you set, then completes.
- Recurring — repeats on a pattern and stays active between runs. Configure:
  - Repeat interval: daily, weekly, or monthly.
  - Repeat every: how often within that interval, e.g. every 2 weeks (1–365).
  - Days of week: required for weekly schedules — pick which weekdays fire.
  - End date: optional; after this date the schedule stops and is marked completed.

After each recurring run, WaDesk works out the next run time in the schedule's own time zone (daily adds the chosen number of days, weekly moves to the next allowed weekday, monthly adds the chosen number of months). The schedule keeps running until the end date is reached or there are no more runs, at which point it completes.

## Time Zones & Lead Time

Every schedule is tied to a specific time zone (for example Asia/Kolkata or America/New York), pre-selected to your workspace's time zone. The date and time you enter are read in that zone, so:

- A send set for "9:00 AM Asia/Kolkata" always fires at 9:00 AM local time, no matter where the server is.
- Recurring runs use the schedule's own time zone, so daily and weekly runs land at the same clock time every time.
- Daylight-saving changes are handled, so the time stays the same on the clock.

As above, the time must be at least 2 minutes in the future.

> Pick the time zone deliberately. Choosing the wrong one (or your own instead of your audience's) is the most common reason a schedule fires at an unexpected hour. Double-check it before saving.

## Schedule & Recipient Statuses

The list page summarizes schedules by status; the detail page shows per-recipient outcomes that roll up into the totals.

Status | Meaning
--- | ---
scheduled | A one-off (or the next run of a recurring schedule) is waiting to fire.
running | A recurring schedule that is active and armed for its next slot.
paused | Temporarily stopped; it will not fire until resumed.
completed | A one-off has fired, or a recurring schedule has reached its end and will not run again.
failed | The run couldn't be carried out; the reason is shown.
cancelled | Stopped by you before it could fire.

Each recipient is tracked independently as pending, sent, delivered, read, or failed, just like a broadcast. Delivery updates are de-duplicated and reconciled, so the counts stay accurate. Wallet credits are charged only for new sends, so repeated or out-of-order updates never double-charge.

## Pause, Resume, Cancel, Run-Now & Edit

From the list or the detail page you can control a schedule throughout its life. The status updates instantly in the dashboard even if the background service is briefly busy.

Action | Effect | Allowed from
--- | --- | ---
Pause | Stops the schedule from firing; moves it to paused. | scheduled / running
Resume | Re-activates a paused schedule back to scheduled (once) or running (recurring). | paused
Run now | Fires the schedule on the next check (within about 60 seconds), ignoring the set time. | any state except completed / cancelled
Cancel | Stops a future schedule entirely; moves it to cancelled. | any state except completed / cancelled / failed
Edit | Update the name, message, date, time, or time zone. The next run time is recalculated when any timing field changes. | any unfinished state

> Editing is locked once finished. A completed, cancelled, or failed schedule can't be edited — create a new schedule, or use Retry on a failed one (below).

## Retrying a Failed Schedule

If a schedule ends in failed, open the retry action and pick a fresh date, time, and time zone (again, at least 2 minutes out). WaDesk then:

1. Cancels any leftover job from the failed run so the same recipients aren't sent to twice.
2. Resets the schedule back to scheduled, clears the old failure details, and zeroes the run counters (including the billing counter).
3. Resets every recipient back to pending for a clean run.
4. Re-registers the job to fire at the new time.

Retry only applies to failed schedules — for any other state, use Run now instead.

## Multi-Device & Audience

Selecting two or more numbers splits the schedule into one schedule per number and divides the audience evenly across them. To get the split right, group and queue audiences are turned into a fixed phone list when you create the schedule for multi-device sends — otherwise each number would re-expand the same group and every contact would get one copy per number. Single-number schedules keep the group or queue reference, so membership can refresh at send time.

Each number's schedule holds only its share of the recipients. After saving, you'll see how many schedules were created across how many numbers.

## How Sends Fire & Restart Recovery

The sending runs in a background service, so schedules fire on time even when no one is logged in. Two things are worth knowing:

- Run-now timing: "Run now" fires the schedule on the next check, within about 60 seconds.
- Restart recovery: if the background service restarts, it re-loads every active (scheduled or running) schedule and re-arms it. Recipients are re-checked at that point (so a group that has grown is honoured), and a schedule is skipped if its owner can't afford at least one message — so a wallet with no credits never starts sending.

## Deleting a Schedule

You can delete a schedule from the list. Deleting first cancels the registered job — so a deleted schedule never fires a stray message — then removes the schedule and any uploaded media file. In practice, deletion is most useful for tidying up schedules that are already completed, cancelled, or failed; for an active schedule you usually want Pause or Cancel first, so the action is reversible.

## Ban-Safety & Pacing

Scheduled sends use the same safety controls as the rest of WaDesk, set by your admin under Admin → Settings → System Message → Sender pacing:

Control | Default | Effect
--- | --- | ---
Message gap | 3 seconds | Delay between one message and the next, varied randomly by ±20%.
Batch size | 50 recipients | How many messages go out before a pause (when batching is on).
Batch gap | 5 minutes | Cooldown between batches, varied randomly by ±20%.
Daily cap (Unofficial API) | 4000 / day / number | Maximum messages a single number can send per day (resets daily).

> Be mindful with recurring sends. A recurring schedule re-sends every time it fires — only target audiences who opted in, keep the content fresh and relevant, and set an end date so a forgotten schedule doesn't keep messaging people forever. Repeated unsolicited messages are a fast path to a WhatsApp number ban. And because schedules fire at a fixed local time, the wrong time zone can deliver messages in the middle of the night for your audience — which drives complaints, hurts template quality on the Business API, and raises ban risk. Check the time zone matches the people you're sending to.