Scheduled Sends

Any send request can be scheduled instead of sent immediately. Add scheduled_at and timezone; GOWA stores the request and a background worker sends it at that time. Schedules survive restarts and wait for an offline device. Schedulable message types: text, image, file, video, audio, sticker, contact, link, location, poll and forward (/message/{id}/forward). Presence and typing indicators are not schedulable.

Schedule fields

Field	Required	Description
`scheduled_at`	yes	RFC 3339 time of the first send, in the future, e.g. `2026-11-01T09:00:00+07:00`. The first send always happens at this time.
`timezone`	yes	IANA zone (e.g. `Asia/Jakarta`) used to compute repeats, so “09:00 every day” stays 09:00 across DST changes.
`recurrence`	no	`once` (default), `daily`, `weekly` or `monthly`.
`weekdays`	weekly	Days to send, `0` = Sunday … `6` = Saturday, e.g. `[1, 3, 5]`.
`day_of_month`	monthly	`1`–`31`; clamped to the last day of shorter months.
`end_at`	no	Recurring only. No sends after this time.
`occurrence_limit`	no	Recurring only. Stop after this many sends.

Without scheduled_at, the request is sent immediately as usual.

Examples

# once, tomorrow morning
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "628123456789",
    "message": "Reminder: meeting at 10:00",
    "scheduled_at": "2026-11-01T09:00:00+07:00",
    "timezone": "Asia/Jakarta"
  }'

{
  "code": "SUCCESS",
  "message": "Success",
  "results": {
    "schedule_id": "0b5c3a8e-7f5d-4d6f-9d1e-2f8c1a7b9e10",
    "scheduled_at": "2026-11-01T02:00:00Z",
    "next_run_at": "2026-11-01T02:00:00Z"
  }
}

Scheduled responses have schedule_id instead of message_id.

# every Monday, Wednesday and Friday at 08:30, 12 times
curl -u admin:changeme -X POST http://localhost:3000/send/message \
  -H "Content-Type: application/json" -H "X-Device-Id: my-device" \
  -d '{
    "phone": "120363025246125486@g.us",
    "message": "Standup in 30 minutes",
    "scheduled_at": "2026-11-02T08:30:00+07:00",
    "timezone": "Asia/Jakarta",
    "recurrence": "weekly",
    "weekdays": [1, 3, 5],
    "occurrence_limit": 12
  }'

# monthly invoice on the 1st, with an uploaded file (multipart: repeat weekdays as separate fields if used)
curl -u admin:changeme -X POST http://localhost:3000/send/file \
  -H "X-Device-Id: my-device" \
  -F phone=628123456789 \
  -F file=@invoice.pdf \
  -F scheduled_at=2026-12-01T09:00:00+07:00 \
  -F timezone=Asia/Jakarta \
  -F recurrence=monthly \
  -F day_of_month=1 \
  -F end_at=2027-12-31T23:59:59+07:00

Uploaded files are kept on the server until the schedule finishes. In multipart bodies send weekdays as repeated fields (-F weekdays=1 -F weekdays=3).

Manage schedules

Schedules belong to a device; send the same X-Device-Id.

Action	Request
List	`GET /send/schedules` with optional `status`, `search` (recipient or text), `message_type`, `limit`, `offset`
Get one	`GET /send/schedules/{schedule_id}`
Pause	`POST /send/schedules/{schedule_id}/pause`
Resume	`POST /send/schedules/{schedule_id}/resume`
Cancel	`POST /send/schedules/{schedule_id}/cancel`

curl -u admin:changeme -H "X-Device-Id: my-device" \
  "http://localhost:3000/send/schedules?status=active&limit=25"

The list returns results.data and results.pagination (limit, default 25; offset; total).

Statuses

Status	Meaning
`active`	Waiting for its next run.
`running`	Claimed by the worker and sending.
`paused`	Held until resumed.
`completed`	No runs left.
`failed`	Gave up after retries, or the stored request was invalid.
`cancelled`	Cancelled by you.

Delivery behavior

The worker checks for due schedules every 5 seconds.
Device offline or not logged in: the run waits and retries every 30 seconds. Waiting does not count as a failed attempt, so a schedule survives long outages.
Send errors: retried with backoff starting at 15 seconds and capped at 5 minutes, up to 10 attempts per occurrence. A recurring schedule then skips to its next occurrence; a one-off schedule becomes failed.
Invalid request (for example a bad recipient): fails immediately without retrying.
Late runs: an occurrence delayed past end_at is not sent.
Crashes and restarts: shutdown does not abort a send already in flight. If the process dies mid-send, GOWA cannot know whether the message went out, so once the 2-minute claim expires that occurrence is skipped as interrupted and not resent. Recurring schedules continue with their next occurrence.

Over MCP

The MCP tool whatsapp_send accepts the same schedule fields, and whatsapp_schedule lists, gets, pauses, resumes and cancels schedules. See MCP server.

Check GET /app/info: results.scheduled_sends is true when the server accepts schedule fields and exposes /send/schedules.

Getting Started

Core Concepts

Usage Examples

Integrations

Advanced

Schedule fields

Examples

Manage schedules

Statuses

Delivery behavior

Over MCP

​Schedule fields

​Examples

​Manage schedules

​Statuses

​Delivery behavior

​Over MCP

Schedule fields

Examples

Manage schedules

Statuses

Delivery behavior

Over MCP