---
title: Admin's Scheduled Messages
updatedAt: 2026-05-15T16:02:56.000Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# Admin's Scheduled Messages

Schedule chat messages to be sent automatically at a future date and time

Moderators and admins can schedule messages to be sent at a specific date and time in the future. The message appears in the target chat room automatically at the scheduled time, with no manual action required.

## How to schedule a message

1. Open the chat room in the Watchers interface.
2. Type your message in the text field.
3. **Right-click** the send button (or **long-press** on mobile). A submenu with "Schedule message" appears.
4. Click **Schedule message**. A modal opens — pick the **date** and **time** to send.
5. Click **Schedule**. The message is now queued.

> **Note:** Only moderators and admins can schedule messages. The submenu does not appear for regular users.

## Viewing and managing scheduled messages

After scheduling, a **clock icon** appears in the textarea area (only when the input is empty and there are pending scheduled messages for the current room). Click it to open the **Scheduled messages** modal.

The modal shows the full list of queued messages for this room, with the scheduled send time displayed on each message. From this view you can:

- **Edit the schedule**: right-click (or long-press) the message → **Edit schedule** → pick a new date and time
- **Cancel**: delete the message before it is delivered

> When you are inside the Scheduled messages modal, clicking the send button opens the schedule picker directly — no right-click needed.

## Message statuses

| Status | Meaning |
|--------|---------|
| `SCHEDULED` | Queued and waiting to be sent |
| `SENT` | Delivered to the chat room at the scheduled time |
| `CANCELLED` | Deleted before execution |

## How it works

When a message is scheduled:

1. The message content is saved in a temporary internal room (invisible to users).
2. A one-time Temporal workflow is created with a trigger at the specified date and time.
3. At the scheduled time the workflow fires, the message is posted to the target room, and the status updates to `SENT`.
4. If delivery fails, the system retries automatically: up to 5 attempts with exponential backoff (10 seconds to 1 minute).

## Admin API

Scheduled messages can be managed programmatically via the Admin API. Note that **creating** a scheduled message is only possible via the chat WebSocket interface — there is no REST endpoint for creation.

### List scheduled messages

```
GET /admin/delayed-message
```

Query parameters:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `limit` | 20 | Results per page |
| `offset` | 0 | Pagination offset |
| `order` | `id_desc` | Sort order |

Response:

```json
{
  "delayedMessages": [
    {
      "id": 1,
      "messageId": 456,
      "sendTime": "2026-06-15T14:30:00.000Z",
      "sentAt": null,
      "text": "Good morning, everyone!",
      "externalRoomId": "room:123",
      "userId": 42,
      "status": "SCHEDULED",
      "creatorAdminId": null,
      "createdAt": "2026-05-15T10:00:00.000Z",
      "updatedAt": "2026-05-15T10:00:00.000Z",
      "message": {
        "id": 456,
        "text": "Good morning, everyone!",
        "user": { "id": 42, "name": "Admin" },
        "room": { "externalRoomId": "room:123" }
      }
    }
  ],
  "pageCount": 1
}
```

### Get a single scheduled message

```
GET /admin/delayed-message/:id
```

### Update a scheduled message

```
PATCH /admin/delayed-message/:id
```

Body fields (all optional):

| Field | Type | Description |
|-------|------|-------------|
| `sendTime` | string (ISO 8601) | New send time. The old Temporal schedule is cancelled and a new one is created automatically. Only applies if the current status is `SCHEDULED`. |
| `createData` | object | Updated message content (text, type, and other message fields). |

Example — reschedule:

```json
{
  "sendTime": "2026-06-16T09:00:00.000Z"
}
```

### Cancel a scheduled message

```
DELETE /admin/delayed-message/:id
```

Cancels the Temporal schedule and sets the message status to `CANCELLED`. Returns the updated message object.

### Get scheduled message count for a room

```
GET /message/delayed-message/count/:externalRoomId
```

Returns the number of messages with status `SCHEDULED` for the given room.

```json
{ "count": 3 }
```

## WebSocket events

The backend emits the following Socket.IO events to the room when scheduled message state changes:

| Event | When |
|-------|------|
| `delayedMessageCreated` | A new scheduled message was created |
| `delayedMessageSent` | A scheduled message was delivered |
| `delayedMessageDeleted` | A scheduled message was cancelled |

## Constraints

- Only users with the **moderator** role or higher can create scheduled messages.
- The scheduled time must be **in the future**: past dates and times are rejected in the UI.
- Execution is **one-time only**: a scheduled message fires once.
- All standard message types are supported: text, stickers, image shares, bet shares.
- Rescheduling (`PATCH sendTime`) only works while the status is `SCHEDULED`.