Scheduled Messages

Schedule messages to be sent at a specific time in the future.

Schedule a Message

Schedule a message to be sent at a specific time.

POST /sessions/{id}/scheduled

Request Body

Parameter	Type	Required	Description
to	string	Yes	Phone number or group ID
text	string	Yes	Message text
scheduledAt	string	Yes	ISO 8601 datetime (UTC)
type	string	No	Message type (default: text)
media	string	No	Media URL (for image/video/document)
caption	string	No	Media caption

Example Request

curl -X POST http://localhost:3000/sessions/{id}/scheduled \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919988066776",
    "text": "This is a scheduled message!",
    "scheduledAt": "2026-02-01T15:00:00.000Z"
  }'

Response

{
  "success": true,
  "scheduled": {
    "id": "sched_abc123",
    "to": "919988066776",
    "text": "This is a scheduled message!",
    "scheduledAt": "2026-02-01T15:00:00.000Z",
    "status": "pending",
    "createdAt": "2026-02-01T10:00:00.000Z"
  }
}

---

Schedule Image Message

curl -X POST http://localhost:3000/sessions/{id}/scheduled \
  -H "X-API-Key: wask_your_session_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919988066776",
    "type": "image",
    "media": "https://example.com/image.jpg",
    "caption": "Scheduled image",
    "scheduledAt": "2026-02-01T15:00:00.000Z"
  }'

---

Get All Scheduled Messages

Get all scheduled messages for a session.

GET /sessions/{id}/scheduled

Query Parameters

Parameter	Type	Description
status	string	Filter by status (pending, sent, cancelled, failed)

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  "http://localhost:3000/sessions/{id}/scheduled?status=pending"

Response

{
  "success": true,
  "scheduled": [
    {
      "id": "sched_abc123",
      "to": "919988066776",
      "text": "This is a scheduled message!",
      "scheduledAt": "2026-02-01T15:00:00.000Z",
      "status": "pending",
      "createdAt": "2026-02-01T10:00:00.000Z"
    }
  ]
}

---

Get Scheduled Message

Get details of a specific scheduled message.

GET /sessions/{id}/scheduled/{scheduledId}

Example Request

curl -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/{id}/scheduled/sched_abc123

Response

{
  "success": true,
  "scheduled": {
    "id": "sched_abc123",
    "to": "919988066776",
    "text": "This is a scheduled message!",
    "scheduledAt": "2026-02-01T15:00:00.000Z",
    "status": "pending",
    "createdAt": "2026-02-01T10:00:00.000Z"
  }
}

---

Cancel Scheduled Message

Cancel a scheduled message before it's sent.

DELETE /sessions/{id}/scheduled/{scheduledId}

Example Request

curl -X DELETE \
  -H "X-API-Key: wask_your_session_key" \
  http://localhost:3000/sessions/{id}/scheduled/sched_abc123

Response

{
  "success": true,
  "message": "Scheduled message cancelled successfully"
}

Cannot Cancel Sent Messages

You can only cancel messages with status pending. Once a message is sent, it cannot be cancelled.

---

Message Status

Scheduled messages have the following statuses:

Status	Description
pending	Waiting to be sent
sent	Successfully sent
cancelled	Cancelled by user
failed	Failed to send

---

Timezone Handling

All scheduled times must be in UTC (ISO 8601 format).

Converting Local Time to UTC

JavaScript:

const localTime = new Date('2026-02-01 15:00:00'); // Your local time
const utcTime = localTime.toISOString(); // "2026-02-01T09:30:00.000Z"

PHP:

$localTime = new DateTime('2026-02-01 15:00:00', new DateTimeZone('Asia/Kolkata'));
$utcTime = $localTime->setTimezone(new DateTimeZone('UTC'))->format('c');

Python:

from datetime import datetime
import pytz

local_tz = pytz.timezone('Asia/Kolkata')
local_time = local_tz.localize(datetime(2026, 2, 1, 15, 0, 0))
utc_time = local_time.astimezone(pytz.UTC).isoformat()

---

Webhook Notifications

When a scheduled message is sent, you'll receive a webhook:

{
  "event": "message.sent",
  "sessionId": "e67a00be-ed45-4356-9488-049cabb9895d",
  "timestamp": "2026-02-01T15:00:00.000Z",
  "scheduledId": "sched_abc123",
  "status": "success",
  "result": {
    "messageId": "3EB0ABC123456789",
    "to": "919988066776@s.whatsapp.net"
  }
}

---

Best Practices

1. Minimum Schedule Time

Schedule messages at least 1 minute in the future to ensure proper processing.

2. Bulk Scheduling

For multiple scheduled messages, add delays between them:

const scheduleTime = new Date('2026-02-01T15:00:00Z');

recipients.forEach((recipient, index) => {
  const time = new Date(scheduleTime.getTime() + (index * 60000)); // 1 min apart
  scheduleMessage(recipient, message, time.toISOString());
});

3. Error Handling

Always check the response and handle errors:

const response = await scheduleMessage(data);
if (!response.success) {
  console.error('Failed to schedule:', response.error);
}

4. Monitoring

Regularly check pending scheduled messages:

curl -H "X-API-Key: wask_your_session_key" \
  "http://localhost:3000/sessions/{id}/scheduled?status=pending"

---

Limitations

• Maximum schedule time: 30 days in the future
• Scheduled messages are stored in-memory (lost on container restart)
• For persistent scheduling, use an external scheduler (cron, etc.)