Skip to main content
GOWA Message Scheduler Overview 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, typing indicators, and the experimental /send/interactive endpoint are not schedulable.

Schedule fields

Without scheduled_at, the request is sent immediately as usual.

Examples

Scheduled responses have schedule_id instead of message_id.
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.
The list returns results.data and results.pagination (limit, default 25; offset; total).

Statuses

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. Before the first attempt, GOWA persists a WhatsApp message ID for the occurrence. After its 2-minute claim expires, an interrupted occurrence is requeued with that same ID and counts toward the attempt budget. Polls also retain their encryption secret across retries. This preserves message identity after an ambiguous acknowledgment, but does not guarantee exactly-once delivery.
  • Older interrupted attempts: legacy attempts whose outcome is unknown retain conservative recovery. The worker skips that occurrence for a recurring schedule or fails a one-off schedule rather than assigning it a new message identity.

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.