Scheduled Messages

Schedule a message to a group chat, delivered by a bot user at the time you choose. Until then nothing shows in the chat; when the time comes the message is sent like any other, with a push notification to the members.

Only group chats can be scheduled to. Take the room id from the chat's address in the CMS, the same id the chat_message incoming webhook is set up with. To message one person, use Direct Messages instead.

Required scope: write:chat_messages

Endpoints

POST

/api/open/v1/chat-rooms/{id}/scheduled-messages

Schedule a message to the group chat

GET

/api/open/v1/chat-rooms/{id}/scheduled-messages

List the messages waiting to be sent

DELETE

/api/open/v1/scheduled-chat-messages/{id}

Cancel a scheduled message

Schedule a message

curl -X POST https://customer.monotree.com/api/open/v1/chat-rooms/240/scheduled-messages \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_user_id": 873,
    "text": "Stock count on Friday at 15:00. Bring your scanner.",
    "send_at": "2026-10-09T07:00:00+02:00"
  }'

Field	Type	Notes
`bot_user_id`	integer	Required. The bot user that sends the message. A non-bot id returns `422`.
`text`	string	Required. The message body.
`send_at`	datetime	Required. ISO 8601, with an offset. Must be in the future, otherwise `422`.
`media`	array	Optional. `{ url, type }` pairs — same rules as incoming webhook media (same type, max 10, publicly reachable URLs). The files are fetched when you schedule, not when the message is sent.

The room ({id} in the path) must be a group chat. A 1:1 chat returns 422, an unknown id 404.

Response

{
  "data": {
    "id": 31,
    "room_id": 240,
    "text": "Stock count on Friday at 15:00. Bring your scanner.",
    "bot_user_id": 873,
    "send_at": "2026-10-09T05:00:00+00:00",
    "created_at": "2026-10-04T12:00:00+00:00"
  }
}

id identifies the scheduled message, not the chat message it becomes.

List and cancel

GET /chat-rooms/{id}/scheduled-messages returns the messages still waiting to be sent to that chat, soonest first, in the shape above. A message leaves the list once it is sent.

DELETE /scheduled-chat-messages/{id} cancels one and returns 204. A message that has already been sent returns 404.

To change the text or the time, cancel the message and schedule it again.

Good to know

Messages go out once a minute, so a message is sent within a minute after send_at.
The bot does not need to be a member of the chat.
Only messages scheduled through the API are listed and can be cancelled here. Messages that managers schedule in the app are their own.
If the chat is deleted before send_at, the message is dropped.