Skip to main content

Scheduled messages

Read with ChatGPTRead with Claude

Schedule a WhatsApp message to be sent later from one of your 2Chat numbers, once or on a recurring schedule, and manage the messages that are still waiting to go out.

These endpoints work with both WhatsApp Web numbers and WhatsApp Business API (WABA) numbers connected to your account. They share data with the 2Chat app: a message you schedule through the API appears in the conversation in the app, and messages scheduled from the app are returned by these endpoints.

How scheduling works​

  • Times are local. send_at and ends.date are wall-clock times in the timezone you send, as an IANA name such as America/New_York. Without timezone, your account's time zone is used, or UTC if the account has none. Responses report the next send in UTC as next_send_at_utc.
  • Recurring messages keep their local time. A daily message at 09:00 in America/New_York stays at 09:00 New York time across daylight saving changes.
  • One-time or recurring. Without repeat, the message is sent once. With repeat, it's sent every every units of unit (minute, hourly, daily, weekly, monthly or yearly) until ends says to stop:
    • never: keeps going until you cancel it.
    • occurrences: stops after that many sends in total.
    • date: no send goes out after ends.date.
  • Monthly and yearly series that start on a day a shorter month doesn't have (for example the 31st) are sent on that month's last day.
  • Editing isn't available. To change a scheduled message, cancel it and schedule a new one.

Statuses​

statusMeaning
pendingWaiting for its next send.
in_progressBeing sent right now.
completedEvery send of the message or series was accepted for delivery. Follow each message's delivery with the messages endpoints or webhooks.
failedA send failed and the scheduled message was stopped. It won't be sent again.

A cancelled message keeps its last status and has cancelled: true.

What stops a scheduled message​

  • You cancel it with Cancel a scheduled message.
  • A send is rejected. For example, the number is disconnected, or the message isn't allowed on a WABA number. A recurring series stops completely: later sends don't go out, and the message ends as failed. Temporary errors are retried a couple of times before that.
  • Your account expires. Pending scheduled messages are closed without being sent.
WhatsApp Business API (WABA) numbers

On a WABA number, a text or media message can only be delivered while the contact's 24-hour customer service window is open. If the window is closed when the message is due, the send is rejected and the scheduled message is stopped. Scheduling a template is only available in the 2Chat app.

Limitations​

  • Groups: scheduling a message to a WhatsApp group is only available in the 2Chat app. Group messages scheduled from the app are listed with to_number: null.
  • Templates: scheduling a WABA template is only available in the 2Chat app. Messages scheduled with a template from the app show its name in template.

The scheduled message object​

Every endpoint in this section returns scheduled messages with these fields:

{
    "uuid": "EST83feed3c-4f8d-446b-8cbc-4efcc14ef901",
    "status": "pending",
    "cancelled": false,
    "next_send_at_utc": "2026-12-07 13:00:00",
    "timezone": "America/New_York",
    "channel_uuid": "WPNb932ad7f-250a-4ada-86a6-c1691e00a2cb",
    "to_number": "+447700900461",
    "text": "Your weekly menu is ready!",
    "url": "https://example.com/menu.jpg",
    "template": null,
    "recurring": true,
    "repeat": {
        "unit": "weekly",
        "every": "1"
    },
    "ends": {
        "type": "occurrences",
        "occurrences": "4",
        "date": null
    },
    "sent_count": "0",
    "created_at": "2026-11-20 15:04:12"
}
FieldDescription
uuidID of the scheduled message. Use it to cancel it or send it now.
statuspending, in_progress, completed or failed. See Statuses.
cancelledtrue if the message was cancelled.
next_send_at_utcWhen the next send is due, in UTC (YYYY-MM-DD HH:MM:SS).
timezoneThe time zone send_at and ends.date are in.
channel_uuidThe 2Chat number the message is sent from.
to_numberRecipient's phone number. null for group messages scheduled from the app.
textMessage text, or null.
urlURL of the attached media file, or null.
templateName of the WABA template, for messages scheduled with one from the app. Otherwise null.
recurringfalse for a one-time message, true for a series.
repeatnull for a one-time message. For a series: unit and every, how often it's sent.
endsnull for a one-time message. For a series: type (never, occurrences or date), occurrences (meaningful only when type is occurrences) and date (the end, in timezone, when type is date).
sent_countHow many times it has been sent so far.
created_atWhen it was scheduled, in UTC.

repeat.every, ends.occurrences and sent_count are returned as numeric strings.

Endpoints​