--- title: "Receives chat messages from the given room" method: GET path: "/ocs/v2.php/apps/spreed/api/{apiVersion}/chat/{token}" tags: ["chat"] --- # Receives chat messages from the given room `GET /ocs/v2.php/apps/spreed/api/{apiVersion}/chat/{token}` - Receiving the history ($lookIntoFuture=0): The next $limit messages after $lastKnownMessageId will be returned. The new $lastKnownMessageId for the follow up query is available as `X-Chat-Last-Given` header. - Looking into the future ($lookIntoFuture=1): If there are currently no messages the response will not be sent immediately. Instead, HTTP connection will be kept open waiting for new messages to arrive and, when they do, then the response will be sent. The connection will not be kept open indefinitely, though; the number of seconds to wait for new messages to arrive can be set using the timeout parameter; the default timeout is 30 seconds, maximum timeout is 60 seconds. If the timeout ends a successful but empty response will be sent. If messages have been returned (status=200) the new $lastKnownMessageId for the follow up query is available as `X-Chat-Last-Given` header. The limit specifies the maximum number of messages that will be returned, although the actual number of returned messages could be lower if some messages are not visible to the participant. Note that if none of the messages are visible to the participant the returned number of messages will be 0, yet the status will still be 200. Also note that `X-Chat-Last-Given` may reference a message not visible and thus not returned, but it should be used nevertheless as the $lastKnownMessageId for the follow-up query. ## Path parameters - `apiVersion` 'v1', required - `token` string, required ## Query parameters - `lookIntoFuture` 0 | 1, required - `limit` integer - `lastKnownMessageId` integer - `lastCommonReadId` integer - `timeout` integer - `setReadMarker` 0 | 1 - `includeLastKnown` 0 | 1 - `noStatusUpdate` 0 | 1 - `markNotificationsAsRead` 0 | 1 - `threadId` integer ## Headers - `x-nextcloud-federation` string - `OCS-APIRequest` boolean, required ## Response `200` Messages returned - object - `ocs` object, required - `meta` OCSMeta, required - `status` string, required - `statuscode` integer, required - `message` string - `totalitems` string - `itemsperpage` string - `data` ChatMessageWithParent[], required - `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 - `parent` union - 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 - DeletedChatMessage - `id` integer, required — ID of the parent comment - `deleted` true, required — `true` when the parent is deleted ## Other responses - `304` — No messages - `404` — Thread not found ## Changes > 62 revisions in range; 1 could not be searched. - **2026-03-31** `dc2b6567a07b` — 8 info - added the optional property `ocs/data/items/allOf[#/components/schemas/ChatMessage]/allOf[subschema #2]/metaData/replyToActorDisplayName` to the response with the `200` status - added the optional property `ocs/data/items/allOf[#/components/schemas/ChatMessage]/allOf[subschema #2]/metaData/replyToConversationName` to the response with the `200` status - added the optional property `ocs/data/items/allOf[#/components/schemas/ChatMessage]/allOf[subschema #2]/metaData/replyToConversationToken` to the response with the `200` status - added the optional property `ocs/data/items/allOf[#/components/schemas/ChatMessage]/allOf[subschema #2]/metaData/replyToMessageId` to the response with the `200` status - …4 more - …earlier changes not shown [Full history](https://skmtc.dev/nextcloud/apis/spreed-full/changes/ocs/v2.php/apps/spreed/api/:apiVersion/chat/:token/get.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)