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"
  }'
FieldTypeNotes
bot_user_idintegerRequired. The bot user that sends the message. A non-bot id returns 422.
textstringRequired. The message body. Max 50,000 characters.
send_atdatetimeRequired. ISO 8601. Must be in the future, otherwise 422. Send it with an offset: a time without one is read as Copenhagen time (Europe/Copenhagen).
mediaarrayOptional. Up to 10 { url, type } pairs — same rules as on direct messages: one type for all items, https URLs on public addresses, at most 100 MB per file, downloaded within 15 seconds. 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. A scheduled message returns 201.

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-09T07:00:00+02:00",
    "created_at": "2026-10-04T14:00:00+02:00"
  }
}

id identifies the scheduled message, not the chat message it becomes. send_at comes back in Copenhagen time, whatever offset you sent; it is the same moment.

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, all in one data array (not paginated). A message leaves the list once it is sent. An unknown room id returns 404.

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.