--- title: "Schedules the sending of a new chat message to the given room" method: POST path: "/ocs/v2.php/apps/spreed/api/{apiVersion}/chat/{token}/schedule" tags: ["chat"] --- # Schedules the sending of a new chat message to the given room `POST /ocs/v2.php/apps/spreed/api/{apiVersion}/chat/{token}/schedule` The author and timestamp are automatically set to the current user and time. Required capability: `scheduled-messages` ## Path parameters - `apiVersion` 'v1', required - `token` string, required ## Headers - `OCS-APIRequest` boolean, required ## Request body - object - `message` string, required — The message to send - `sendAt` integer, required — When to send the scheduled message - `replyTo` integer — Parent id which this scheduled message is a reply to - `silent` boolean — If sent silent the scheduled message will not create any notifications when sent - `threadTitle` string — Only supported when not replying, when given will create a thread (requires `threads` capability) - `threadId` integer — Thread id without quoting a specific message (requires `threads` capability) ## Response `201` Message scheduled successfully - object - `ocs` object, required - `meta` OCSMeta, required - `status` string, required - `statuscode` integer, required - `message` string - `totalitems` string - `itemsperpage` string - `data` ScheduledMessage, required - `id` string, required — SnowflakeID - `actorId` string, required — Actor id of the message author - `actorType` string, required — Actor type of the message author - `threadId` integer, required — Thread ID if the scheduled message is for a thread - `threadTitle` string — Title of the thread if the scheduled message is for a thread - `parent` ChatMessage - `actorDisplayName` string, required — Display name of the message author (can be empty for type `deleted_users` and `guests`) - `actorId` string, required — Actor id of the message author - `actorType` string, required — See [Constants - Actor types of chat messages](https://nextcloud-talk.readthedocs.io/en/latest/constants#actor-types-of-chat-messages) - `expirationTimestamp` integer, required — Unix time stamp when the message expires and should be removed from the clients UI without further note or warning (only available with `message-expiration` capability) - `message` string, required — Message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706)) - `messageParameters` object, required — Message parameters for `message` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706)) - `messageType` string, required — Currently known types are `comment`, `comment_deleted`, `system` and `command` - `systemMessage` string, required — Empty for normal chat message or the type of the system message (untranslated) - `deleted` true — Set to `true` when the message was deleted - `id` integer, required — ID of the comment - `isReplyable` boolean, required — True if the user can post a reply to this message (only available with `chat-replies` capability) - `markdown` boolean, required — Whether the message should be rendered as markdown or shown as plain text - `reactions` object, required — An array map with relation between reaction emoji and total count of reactions with this emoji - `reactionsSelf` string[] — When the user reacted this is the list of emojis the user reacted with - `referenceId` string, required — A reference string that was given while posting the message to be able to identify a sent message again (only available with `chat-reference-id` capability). For grouped file uploads support, expected format is `{sha256(uploadId)}-{order}`, matching /^[a-f0-9]{60}-[0-9]{3}$/ - `timestamp` integer, required — Timestamp in seconds and UTC time zone - `token` string, required — Conversation token - `lastEditActorDisplayName` string — Display name of the last editing author (only available with `edit-messages` capability and when the message was actually edited) - `lastEditActorId` string — Actor id of the last editing author (only available with `edit-messages` capability and when the message was actually edited) - `lastEditActorType` string — Actor type of the last editing author - See [Constants - Actor types of chat messages](https://nextcloud-talk.readthedocs.io/en/latest/constants#actor-types-of-chat-messages) (only available with `edit-messages` capability and when the message was actually edited) - `lastEditTimestamp` integer — Unix time stamp when the message was last edited (only available with `edit-messages` capability and when the message was actually edited) - `silent` boolean — Whether the message was sent silently (only available with `silent-send-state` capability) - `threadId` integer — Thread ID if this message is part of a thread - `isThread` boolean — Whether this message is the root of a thread - `threadTitle` string — Title of the thread if this message is the root of a thread - `threadReplies` integer — Number of replies in the thread if this message is the root of a thread - `metaData` ChatMessageMetaData - `pinnedActorType` string — Actor type of the attendee that pinned the message - Required capability: `pinned-messages` - `pinnedActorId` string — Actor ID of the attendee that pinned the message - Required capability: `pinned-messages` - `pinnedActorDisplayName` string — Display name of the attendee that pinned the message - Required capability: `pinned-messages` - `pinnedAt` integer — Timestamp when the message was pinned - Required capability: `pinned-messages` - `pinnedUntil` integer — Timestamp until when the message is pinned. If missing the message is pinned infinitely - Required capability: `pinned-messages` - `threadId` integer — Set when a thread is created with this message. If missing, no thread creation is associated with this message - `threadTitle` string — Set when a thread is created with this message. If missing, no thread creation is associated with this message - `replyToMessageId` integer — Set only when a message in a convo is private replied on a 1-1 room. Represents the parent message id - `replyToConversationToken` string — Set only when a message in a convo is private replied on a 1-1 room. Represents the parent message's group conversation token. - `replyToConversationName` string — Set only when a message in a convo is private replied on a 1-1 room. Represents the parent message's group conversation name - `replyToActorDisplayName` string — Set only when a message in a convo is private replied on a 1-1 room. Represents the parent message's actor display name - `message` string, required — Message string with placeholders - `messageType` string, required — Currently known types are `comment`, `comment_deleted`, `system` and `command` - `createdAt` integer, required — UNIX timestamp when the scheduled message was created - `sendAt` integer, required — UNIX timestamp when the message should be sent - `silent` boolean, required — Whether the message should be sent silently without creating chat notifications - `originalSendAt` integer — Set only if sending failed to persist the original timestamp and expose it ## Other responses - `400` — Scheduling the message is not possible - `401` — Current user is not logged in - `403` — When trying to cross reference wrongly on a reply-private - `404` — Actor not found - `413` — Message too long ## Changes - **2026-03-31** `dc2b6567a07b` — 5 info - added the non-success response with the status `403` - added the optional property `ocs/data/parent/allOf[subschema #2]/metaData/replyToActorDisplayName` to the response with the `201` status - added the optional property `ocs/data/parent/allOf[subschema #2]/metaData/replyToConversationName` to the response with the `201` status - added the optional property `ocs/data/parent/allOf[subschema #2]/metaData/replyToConversationToken` to the response with the `201` status - …1 more - **2026-02-09** `2dd98af77e49` — 2 info - added the optional property `ocs/data/parent/allOf[subschema #2]/metaData/threadId` to the response with the `201` status - added the optional property `ocs/data/parent/allOf[subschema #2]/metaData/threadTitle` to the response with the `201` status - **2026-01-22** `5ffe9b2c44ea` — 1 info - added the optional property `ocs/data/originalSendAt` to the response with the `201` status - **2025-12-05** `a1ee27cbe6bb` — 4 breaking, 1 warning, 1 info - the `ocs/data/id` response's property type/format changed from `integer`/`int64` to `string`/`` for status `201` - removed the required property `ocs/data/metaData` from the response with the `201` status - removed the required property `ocs/data/parentId` from the response with the `201` status - removed the required property `ocs/data/roomId` from the response with the `201` status - …2 more - **2025-11-08** `6ef64fbefde3` — 1 info - endpoint added [Change history](https://skmtc.dev/nextcloud/apis/spreed-full/changes/ocs/v2.php/apps/spreed/api/:apiVersion/chat/:token/schedule/post.md) --- [API](https://skmtc.dev/nextcloud/apis/spreed-full.md) · [All operations](https://skmtc.dev/nextcloud/apis/spreed-full/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nextcloud/spreed-full/revisions/41d6458d6d6e/schema)