path: root/docs/conversation.md

# Conversation API

* API v1: 🏁 Removed with API v4: until Nextcloud 21
* API v2: 🏁 Removed with API v4: Nextcloud 19 - 21
* API v3: 🏁 Removed with API v4: Nextcloud 21 only
* API v4: Base endpoint `/ocs/v2.php/apps/spreed/api/v4`: since Nextcloud 22

## Get user´s conversations

!!! note

    Due to the structure of the `lastMessage.reactions` array the response is not valid in XML.
    It is therefor recommended to use `format=json` or send the `Accept: application/json` header,
    to receive a JSON response.

!!! note

    When `modifiedSince` is provided only conversations with a newer `lastActivity` are returned. If `includeStatus` is set to `true` all one-to-one conversations will be returned to make sure the latest user status is returned.
    Due to the nature of the data structure we can not return information that a conversation was deleted
    or the user removed from a conversation. Therefore it is recommended to do a full refresh:
    * Every 5 minutes
    * When a signaling message of type `delete` or `disinvite` was received
    * Internal signaling mode is used


* Method: `GET`
* Endpoint: `/room`
* Data:

| field            | type | Description                                                                                                                                                                     |
|------------------|------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `noStatusUpdate` | int  | When the user status should not be automatically set to online set to 1 (default 0)                                                                                             |
| `includeStatus`  | bool | Whether the user status information of all one-to-one conversations should be loaded (default false)                                                                            |
| `modifiedSince`  | int  | **Use with care as per note above.** When provided only conversations with a newer `lastActivity` (and one-to-one conversations when `includeStatus` is provided) are returned. |

* Response:
    - Status code:
        + `200 OK`
        + `401 Unauthorized` when the user is not logged in

    - Header:

| field                              | type   | Description                                                                                                                                              |
|------------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `X-Nextcloud-Talk-Hash`            | string | Sha1 value over some config. When you receive a different value on subsequent requests, the capabilities and the signaling settings should be refreshed. |
| `X-Nextcloud-Talk-Modified-Before` | string | Timestamp from before the database request that can be used as `modifiedSince` parameter in the next request                                             |

    - Data:
        Array of conversations, each conversation has at least:

| field                   | type    | Added | Removed | Description                                                                                                                                                                                                                                                                                                                                                                                       |
|-------------------------|---------|-------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id`                    | int     | v1    |         | Numeric identifier of the conversation                                                                                                                                                                                                                                                                                                                                                            |
| `token`                 | string  | v1    |         | Token identifier of the conversation which is used for further interaction                                                                                                                                                                                                                                                                                                                        |
| `type`                  | int     | v1    |         | See list of conversation types in the [constants list](constants.md#conversation-types)                                                                                                                                                                                                                                                                                                           |
| `name`                  | string  | v1    |         | Name of the conversation (can also be empty)                                                                                                                                                                                                                                                                                                                                                      |
| `displayName`           | string  | v1    |         | `name` if non empty, otherwise it falls back to a list of participants                                                                                                                                                                                                                                                                                                                            |
| `description`           | string  | v3    |         | Description of the conversation (can also be empty) (only available with `room-description` capability)                                                                                                                                                                                                                                                                                           |
| `participantType`       | int     | v1    |         | Permissions level of the current user                                                                                                                                                                                                                                                                                                                                                             |
| `attendeeId`            | int     | v3    |         | Unique attendee id                                                                                                                                                                                                                                                                                                                                                                                |
| `attendeePin`           | string  | v3    |         | Unique dial-in authentication code for this user, when the conversation has SIP enabled (see `sipEnabled` attribute)                                                                                                                                                                                                                                                                              |
| `actorType`             | string  | v3    |         | Actor type of the current user (see [constants list](constants.md#attendee-types))                                                                                                                                                                                                                                                                                                                |
| `actorId`               | string  | v3    |         | The unique identifier for the given actor type                                                                                                                                                                                                                                                                                                                                                    |
| `permissions`           | int     | v4    |         | Combined final permissions for the current participant, permissions are picked in order of attendee then call then default and the first which is `Custom` will apply (see [constants list](constants.md#attendee-permissions))                                                                                                                                                                   |
| `attendeePermissions`   | int     | v4    |         | Dedicated permissions for the current participant, if not `Custom` this are not the resulting permissions (see [constants list](constants.md#attendee-permissions))                                                                                                                                                                                                                               |
| `callPermissions`       | int     | v4    |         | Call permissions, if not `Custom` this are not the resulting permissions, if set they will reset after the end of the call (see [constants list](constants.md#attendee-permissions))                                                                                                                                                                                                              |
| `defaultPermissions`    | int     | v4    |         | Default permissions for new participants (see [constants list](constants.md#attendee-permissions))                                                                                                                                                                                                                                                                                                |
| `participantInCall`     | bool    | v1    | v2      | **Removed:** use `participantFlags` instead                                                                                                                                                                                                                                                                                                                                                       |
| `participantFlags`      | int     | v1    |         | "In call" flags of the user's session making the request (only available with `in-call-flags` capability)                                                                                                                                                                                                                                                                                         |
| `readOnly`              | int     | v1    |         | Read-only state for the current user (only available with `read-only-rooms` capability)                                                                                                                                                                                                                                                                                                           |
| `listable`              | int     | v3    |         | Listable scope for the room (only available with `listable-rooms` capability)                                                                                                                                                                                                                                                                                                                     |
| `messageExpiration`     | int     | v4    |         | The message expiration time in seconds in this chat. Zero if disabled. (only available with `message-expiration` capability)                                                                                                                                                                                                                                                                      |
| `count`                 | int     | v1    | v2      | **Removed:** Count the users on the [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) endpoint                                                                                                                                                                                                                                              |
| `numGuests`             | int     | v1    | v2      | **Removed:** Count the guests on the [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) endpoin                                                                                                                                                                                                                                              |
| `lastPing`              | int     | v1    |         | Timestamp of the user's session making the request                                                                                                                                                                                                                                                                                                                                                |
| `sessionId`             | string  | v1    |         | `'0'` if not connected, otherwise an up to 512 character long string that is the identifier of the user's session making the request. Should only be used to pre-check if the user joined already with this session, but this might be outdated by the time of usage, so better check via [Get list of participants in a conversation](participant.md#get-list-of-participants-in-a-conversation) |
| `hasPassword`           | bool    | v1    |         | Flag if the conversation has a password                                                                                                                                                                                                                                                                                                                                                           |
| `hasCall`               | bool    | v1    |         | Flag if the conversation has an active call                                                                                                                                                                                                                                                                                                                                                       |
| `callFlag`              | int     | v3    |         | Combined flag of all participants in the current call (see [constants list](constants.md#participant-in-call-flag), only available with `conversation-call-flags` capability)                                                                                                                                                                                                                     |
| `canStartCall`          | bool    | v1    |         | Flag if the user can start a new call in this conversation (joining is always possible) (only available with `start-call-flag` capability)                                                                                                                                                                                                                                                        |
| `canDeleteConversation` | bool    | v2    |         | Flag if the user can delete the conversation for everyone (not possible without moderator permissions or in one-to-one conversations)                                                                                                                                                                                                                                                             |
| `canLeaveConversation`  | bool    | v2    |         | Flag if the user can leave the conversation (not possible for the last user with moderator permissions)                                                                                                                                                                                                                                                                                           |
| `lastActivity`          | int     | v1    |         | Timestamp of the last activity in the conversation, in seconds and UTC time zone                                                                                                                                                                                                                                                                                                                  |
| `isFavorite`            | bool    | v1    |         | Flag if the conversation is favorited by the user