# ChatMessagesByToken
Receives chat messages from the given room
- 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.
## Documentation
- 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.
- Catalog: `Spreed`
- Schema: `Spreed`
This is a read-only table function. The Nextcloud API may not support changing the data or the Invantive UniversalSQL driver for Nextcloud does not cover it. In the latter case, please use the table NativePlatformScalarRequests to upload data to the Nextcloud API.
## Parameters of Table Function
The following parameters can be used to control the behaviour of the table function `ChatMessagesByToken`. A value must be provided at all times for required parameters, but optional parameters in general do not need to have a value and the execution will default to a pre-defined behaviour. Values can be specified by position and by name. In both cases, all parameters not specified will be evaluated using their default values.
Value specification by position is done by listing all values from the first to the last needed value. For example: a `select * from table(value1, value2, value3)` on a table with four parameters will use the default value for the fourth parameter and the specified values for the first three.
Value specification by name is done by listing all values that require a value. For example with `select * from table(name1 => value1, name3 => value3)` on the same table will use the default values for the second and fourth parameters and the specified values for the first and third.
| Name | Data Type | Required | Default Value | Documentation |
|---|:---:|:---:|:---:|---|
| `apiVersion` | `` | ☐ | v1 | Values: v1. |
| `includeLastKnown` | `` | ☐ | | Include the $lastKnownMessageId in the messages when 1 (default 0) (Values: 0, 1) |
| `lastCommonReadId` | `` | ☐ | | The last known common read message (so the response is 200 instead of 304 when it changes even when there are no messages) |
| `lastKnownMessageId` | `` | ☐ | | The last known message (serves as offset) |
| `limit` | `` | ☐ | | Number of chat messages to receive (100 by default, 200 at most) |
| `lookIntoFuture` | `` | ☑ | | Polling for new messages (1) or getting the history of the chat (0) (Values: 0, 1) |
| `markNotificationsAsRead` | `` | ☐ | | Set to 0 when notifications should not be marked as read (default 1) (Values: 0, 1) |
| `noStatusUpdate` | `` | ☐ | | When the user status should not be automatically set to online set to 1 (default 0) (Values: 0, 1) |
| `setReadMarker` | `` | ☐ | | Automatically set the last read marker when 1, if your client does this itself via chat/{token}/read set to 0 (Values: 0, 1) |
| `threadId` | `` | ☐ | | Limit the chat message list to a given thread |
| `timeout` | `` | ☐ | | Number of seconds to wait for new messages (30 by default, 30 at most) |
| `token` | `` | ☑ | | |
| `x-nextcloud-federation` | `` | ☐ | | Set to 1 when the request is performed by another Nextcloud Server to indicate a federation request |
## Columns of Table Function
The columns of the table function `ChatMessagesByToken` are shown below. Each column has an SQL data type.
| Name | Data Type | Label | Required | Documentation |
|---|:---:|---|:---:|---|
| `actorDisplayName` | `varchar2` | | ☐ | |
| `actorId` | `varchar2` | | ☐ | |
| `actorType` | `varchar2` | | ☐ | |
| `deleted` | `char` | | ☐ | |
| `expirationTimestamp` | `int64` | | ☐ | |
| `id` | `int64` | | ☐ | |
| `isReplyable` | `char` | | ☐ | |
| `isThread` | `char` | | ☐ | |
| `lastEditActorDisplayName` | `varchar2` | | ☐ | |
| `lastEditActorId` | `varchar2` | | ☐ | |
| `lastEditActorType` | `varchar2` | | ☐ | |
| `lastEditTimestamp` | `int64` | | ☐ | |
| `markdown` | `char` | | ☐ | |
| `messageParameters` | `varchar2` | | ☐ | The JSON text of the nested object. |
| `messageType` | `varchar2` | | ☐ | |
| `message` | `varchar2` | | ☐ | |
| `metaData_pinnedActorDisplayName` | `varchar2` | | ☐ | Display name of the attendee that pinned the message - Required capability: `pinned-messages` |
| `metaData_pinnedActorId` | `varchar2` | | ☐ | Actor ID of the attendee that pinned the message - Required capability: `pinned-messages` |
| `metaData_pinnedActorType` | `varchar2` | | ☐ | Actor type of the attendee that pinned the message - Required capability: `pinned-messages` |
| `metaData_pinnedAt` | `int64` | | ☐ | Timestamp when the message was pinned - Required capability: `pinned-messages` |
| `metaData_pinnedUntil` | `int64` | | ☐ | Timestamp until when the message is pinned. If missing the message is pinned infinitely - Required capability: `pinned-messages` |
| `metaData_threadId` | `int64` | | ☐ | Set when a thread is created with this message. If missing, no thread creation is associated with this message |
| `metaData_threadTitle` | `varchar2` | | ☐ | Set when a thread is created with this message. If missing, no thread creation is associated with this message |
| `reactions` | `varchar2` | | ☐ | The JSON text of the nested object. |
| `referenceId` | `varchar2` | | ☐ | |
| `silent` | `char` | | ☐ | |
| `systemMessage` | `varchar2` | | ☐ | |
| `threadId` | `int64` | | ☐ | |
| `threadReplies` | `int64` | | ☐ | |
| `threadTitle` | `varchar2` | | ☐ | |
| `timestamp` | `int64` | | ☐ | |
| `token` | `varchar2` | | ☐ | |