path: root/docs/api-v1.md

# API v1 Documentation

- [Constants](#constants)
  * [Room types](#room-types)
  * [Participant types](#participant-types)
- [Room management](#room-management)
  * [Creating a new room](#creating-a-new-room)
  * [Get user´s rooms](#get-user-s-rooms)
  * [Get single room (also for guests)](#get-single-room-also-for-guests)
  * [Rename a room](#rename-a-room)
  * [Delete a room](#delete-a-room)
  * [Allow guests in a room (public room)](#allow-guests-in-a-room-public-room)
  * [Disallow guests in a room (group room)](#disallow-guests-in-a-room-group-room)
  * [Add room to favorites](#add-room-to-favorites)
  * [Remove room from favorites](#remove-room-from-favorites)
  * [Set notification level](#set-notification-level)
- [Participant management](#participant-management)
  * [Get list of participants in a room](#get-list-of-participants-in-a-room)
  * [Add a participant to a room](#add-a-participant-to-a-room)
  * [Delete a participant from a room](#delete-a-participant-from-a-room)
  * [Remove yourself from a room](#remove-yourself-from-a-room)
  * [Promote a user to a moderator](#promote-a-user-to-a-moderator)
  * [Demote a moderator to a user](#demote-a-moderator-to-a-user)
- [Call management](#call-management)
  * [Get list of connected participants](#get-list-of-connected-participants)
  * [Join a call](#join-a-call)
  * [Send ping to keep the call alive](#send-ping-to-keep-the-call-alive)
  * [Leave a call (but staying in the room for future calls)](#leave-a-call-but-staying-in-the-room-for-future-calls)
- [Chat](#chat)
  * [Receive chat messages of a room](#receive-chat-messages-of-a-room)
  * [Sending a new chat message](#sending-a-new-chat-message)
- [Guests](#guests)
  * [Set display name](#set-display-name)
- [Signaling](#signaling)
  * [Get signaling settings](#get-signaling-settings)
  * [External signaling API](#external-signaling-api)


Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`

## Constants

### Room types
* `1` "one to one"
* `2` group
* `3` public

### Participant types
* `1` owner
* `2` moderator
* `3` user
* `4` guest
* `5` user following a public link


## Capabilities

### 3.0 (Initial Talk release)
* `audio` - audio is supported
* `video` - video + screensharing is supported
* `chat` - simple text chat is supported, superseded by `chat-v2`

### 3.1
* `guest-signaling` - Guests can do signaling via api endpoints
* `empty-group-room` - Group rooms can be created without inviting a Nextcloud user group by default

### 3.2
* `guest-display-names` - Display names of guests are stored in the database, can be set via API (not WebRTC only) and are used on returned comments/participants/etc.
* `multi-room-users` - Users can be in multiple rooms at the same time now, therefor signaling now also requires the room/call token on the URL.
* `chat-v2` - Chat messages are now [Rich Object Strings](https://github.com/nextcloud/server/issues/1706) and pagination is available, the previous `chat` is not available anymore.

### 4.0
* `favorites` - Rooms can be marked as favorites which will pin them to the top of the room list.
* `last-room-activity` - Rooms have the `lastActivity` attribute and should be sorted by that instead of the last ping of the user.
* `no-ping` - The ping endpoint has been removed. Ping is updated with a call to fetch the signaling or chat messages instead.
* `system-messages` - Chat messages have a `systemMessage` attribute and can be generated by the system
* `mention-flag` - The room list populates the boolean `unreadMention` when the user was mentioned since their last visit
* `in-call-flags` - A new flag `participantFlags` has been introduced and is replacing the `participantInCall` boolean.

### 5.0
* `invite-by-mail` - *Replaced by `invite-groups-and-mails`* Guests can be invited with their email address
* `notification-levels` - Users can select when they want to be notified in conversations
* `invite-groups-and-mails` - Groups can be added to existing conversations via the add participant endpoint

## Room management

### Creating a new room

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

    field | type | Description
    ------|------|------------
    `roomType` | int |
    `invite` | string | user id (`roomType = 1`), group id (`roomType = 2` - optional)
    `roomName` | string | room name (Not available for `roomType = 1`)

* Response:
    - Header:
        + `200 OK` when the "one to one" room already exists
        + `201 Created` when the room was created
        + `400 Bad Request` when an invalid room type was given
        + `401 Unauthorized` when the user is not logged in
        + `404 Not Found` when the user or group does not exist

    - Data:

        field | type | Description
        ------|------|------------
        `token` | string | Token identifier of the room which is used for further interaction
        `name` | string | Name of the room (can also be empty)
        `displayName` | string | `name` if non empty, otherwise it falls back to a list of participants

### Get user´s rooms

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

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

    - Data:
        Array of rooms, each room has at least:

        field | type | Description
        ------|------|------------
        `token` | string | Token identifier of the room which is used for further interaction
        `type` | int |
        `name` | string | Name of the room (can also be empty)
        `displayName` | string | `name` if non empty, otherwise it falls back to a list of participants
        `participantType` | int | Permissions level of the current user
        `participantInCall` | bool | Flag if the current user is in the call (deprecated, use `participantFlags` instead)
        `participantFlags` | int | Flags of the current user (only available with `in-call-flags` capability)
        `count` | int | Number of active users
        `numGuests` | int | Number of active guests
        `lastPing` | int | Timestamp of the last ping of the current user (should be used for sorting)
        `sessionId` | string | `'0'` if not connected, otherwise a 512 character long string
        `hasPassword` | bool | Flag if the room has a password
        `hasCall` | bool | Flag if the room has an active call
        `lastActivity` | int | Timestamp of the last activity in the room, in seconds and UTC time zone
        `isFavorite` | bool | Flag if the room is favorited by the user
        `notificationLevel` | int | The notification level for the user (one of `Participant::NOTIFY_*` (1-3))
        `unreadMessages` | int | Number of unread chat messages in the room (only available with `chat-v2` capability)
        `unreadMention` | bool | Flag if the user was mentioned since their last visit
        `lastMessage` | message | Last message in a room if available, otherwise empty
        `objectType` | string | The type of object that the room is associated with; "share:password" if the room is used to request a password for a share, otherwise empty
        `objectId` | string | Share token if "objectType" is "share:password", otherwise empty
       
### Get single room (also for guests)

* Method: `GET`
* Endpoint: `/room/{token}`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

    - Data: See array definition in `Get user´s rooms`

### Rename a room

* Method: `PUT`
* Endpoint: `/room/{token}`
* Data:

    field | type | Description
    ------|------|------------
    `roomName` | string | New name for the room (1-200 characters)

* Response:
    - Header:
        + `200 OK`
        + `400 Bad Request` When the name is too long
        + `403 Forbidden` When the current user is not a moderator/owner
        + `404 Not Found` When the room could not be found for the participant
        + `405 Method Not Allowed` When the room is a one to one room

### Set password for a room

* Method: `PUT`
* Endpoint: `/room/{token}/password`
* Data:

    field | type | Description
    ------|------|------------
    `password` | string | New password for the room

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner or the room is not a public room
        + `404 Not Found` When the room could not be found for the participant

### Delete a room

* Method: `DELETE`
* Endpoint: `/room/{token}`

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `404 Not Found` When the room could not be found for the participant

### Allow guests in a room (public room)

* Method: `POST`
* Endpoint: `/room/{token}/public`

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `404 Not Found` When the room could not be found for the participant

### Disallow guests in a room (group room)

* Method: `DELETE`
* Endpoint: `/room/{token}/public`

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `404 Not Found` When the room could not be found for the participant

### Set room password

* Method: `PUT`
* Endpoint: `/room/{token}/password`
* Data:

    field | type | Description
    ------|------|------------
    `password` | string | Set a new password for the room

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `403 Forbidden` When the room is not a public room
        + `404 Not Found` When the room could not be found for the participant

### Add room to favorites

* Method: `POST`
* Endpoint: `/room/{token}/favorite`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant or the participant is a guest

### Remove room from favorites

* Method: `DELETE`
* Endpoint: `/room/{token}/favorite`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant or the participant is a guest

### Set notification level

* Method: `POST`
* Endpoint: `/room/{token}/notify`
* Data:

    field | type | Description
    ------|------|------------
    `level` | int | The notification level (one of `Participant::NOTIFY_*` (1-3))

* Response:
    - Header:
        + `200 OK`
        + `400 Bad Request` When the the given level is invalid
        + `404 Not Found` When the room could not be found for the participant or the participant is a guest

## Participant management

### Get list of participants in a room

* Method: `GET`
* Endpoint: `/room/{token}/participants`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

    - Data:
        Array of participants, each participant has at least:

        field | type | Description
        ------|------|------------
        `userId` | string | Is empty for guests
        `displayName` | string | Can be empty for guests
        `participantType` | int | Permissions level of the participant
        `lastPing` | int | Timestamp of the last ping of the user (should be used for sorting)
        `sessionId` | string | `'0'` if not connected, otherwise a 512 character long string

### Add a participant to a room

* Method: `POST`
* Endpoint: `/room/{token}/participants`
* Data:

    field | type | Description
    ------|------|------------
    `newParticipant` | string | User, group or email to add
    `source` | string | Source of the participant(s) as returned by the autocomplete suggestion endpoint (default is `users`)

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `400 Bad Request` When the source type is unknown
        + `404 Not Found` When the room could not be found for the participant
        + `404 Not Found` When the user or group to add could not be found

    - Data:

        field | type | Description
        ------|------|------------
        `type` | int | In case the room type changed, the new value is returned

### Delete a participant from a room

* Method: `DELETE`
* Endpoint: `/room/{token}/participants`
* Data:

    field | type | Description
    ------|------|------------
    `participant` | string | User to remove

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `403 Forbidden` When the participant to remove is an owner
        + `404 Not Found` When the room could not be found for the participant
        + `404 Not Found` When the participant to remove could not be found

### Remove a guest from a room

* Method: `DELETE`
* Endpoint: `/room/{token}/participants/guests`
* Data:

    field | type | Description
    ------|------|------------
    `participant` | string | Session ID of the guest to remove

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `403 Forbidden` When the target participant is not a guest
        + `404 Not Found` When the room could not be found for the participant
        + `404 Not Found` When the target participant could not be found

### Remove yourself from a room

* Method: `DELETE`
* Endpoint: `/room/{token}/participants/self`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

### Join a room (available for call and chat)

* Method: `POST`
* Endpoint: `/room/{token}/participants/active`
* Data:

    field | type | Description
    ------|------|------------
    `password` | string | Optional: Password is only required for users which are of type `4` or `5` and only when the room has `hasPassword` set to true.

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the password is required and didn't match
        + `404 Not Found` When the room could not be found for the participant

    - Data:

        field | type | Description
        ------|------|------------
        `sessionId` | string | 512 character long string

### Leave a room (not available for call and chat anymore)

* Method: `DELETE`
* Endpoint: `/room/{token}/participants/active`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

### Promote a user to a moderator

* Method: `POST`
* Endpoint: `/room/{token}/moderators`
* Data:

    field | type | Description
    ------|------|------------
    `participant` | string | User to promote

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `403 Forbidden` When the participant to remove is an owner
        + `404 Not Found` When the room could not be found for the participant
        + `404 Not Found` When the participant to remove could not be found
        + `412 Precondition Failed` When the participant to promote is not a normal user (type `3`)

### Demote a moderator to a user

* Method: `DELETE`
* Endpoint: `/room/{token}/moderators`
* Data:

    field | type | Description
    ------|------|------------
    `participant` | string | User to promote

* Response:
    - Header:
        + `200 OK`
        + `403 Forbidden` When the current user is not a moderator/owner
        + `404 Not Found` When the room could not be found for the participant
        + `404 Not Found` When the participant to demote could not be found
        + `412 Precondition Failed` When the participant to demote is not a moderator (type `2`)


## Call management

### Get list of connected participants

* Method: `GET`
* Endpoint: `/call/{token}`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

    - Data:
        Array of participants, each participant has at least:

        field | type | Description
        ------|------|------------
        `userId` | string | Is empty for guests
        `lastPing` | int | Timestamp of the last ping of the user (should be used for sorting)
        `sessionId` | string | 512 character long string

### Join a call

* Method: `POST`
* Endpoint: `/call/{token}`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

### Leave a call (but staying in the room for future calls and chat)

* Method: `DELETE`
* Endpoint: `/call/{token}`

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

## Chat

### Receive chat messages of a room

* Method: `GET`
* Endpoint: `/chat/{token}`
* Data:

    field | type | Description
    ------|------|------------
    `lookIntoFuture` | int | `1` Poll and wait for new message or `0` get history of a room
    `limit` | int | Number of chat messages to receive (100 by default, 200 at most)
    `timeout` | int | `$lookIntoFuture = 1` only, Number of seconds to wait for new messages (30 by default, 60 at most)
    `lastKnownMessageId` | int | Serves as an offset for the query. The lastKnownMessageId for the next page is available in the `X-Chat-Last-Given` header.

* Response:
    - Status code:
        + `200 OK`
        + `304 Not Modified` When there were no older/newer messages
        + `404 Not Found` When the room could not be found for the participant

    - Header:

        field | type | Description
        ------|------|------------
        `X-Chat-Last-Given` | int | Offset (lastKnownMessageId) for the next page.

    - Data:
        Array of messages, each message has at least:

        field | type | Description
        ------|------|------------
        `id` | int | ID of the comment
        `token` | string | Room token
        `actorType` | string | `guests` or `users`
        `actorId` | string | User id of the message author
        `actorDisplayName` | string | Display name of the message author
        `timestamp` | int | Timestamp in seconds and UTC time zone
        `systemMessage` | string | empty for normal chat message or the type of the system message (untranslated)
        `message` | string | Message string with placeholders (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))
        `messageParameters` | array | Message parameters for `message` (see [Rich Object String](https://github.com/nextcloud/server/issues/1706))

### Sending a new chat message

* Method: `POST`
* Endpoint: `/chat/{token}`
* Data:

    field | type | Description
    ------|------|------------
    `message` | string | The message the user wants to say
    `actorDisplayName` | string | Guest display name (ignored for logged in users)

* Response:
    - Header:
        + `201 Created`
        + `400 Bad Request` In case of any other error
        + `404 Not Found` When the room could not be found for the participant
        + `413 Payload Too Large` When the message was longer than the allowed limit of 1000 characters

    - Data:
        The full message array of the new message, as defined in [Receive chat messages of a room](#receive-chat-messages-of-a-room)

### Get mention autocomplete suggestions

* Method: `GET`
* Endpoint: `/chat/{token}/mentions`
* Data:

    field | type | Description
    ------|------|------------
    `search` | string | Search term for name suggestions (should at least be 1 character)
    `limit` | int | Number of suggestions to receive (20 by default)

* Response:
    - Status code:
        + `200 OK`
        + `404 Not Found` When the room could not be found for the participant

    - Data:
        Array of suggestions, each suggestion has at least:

        field | type | Description
        ------|------|------------
        `id` | string | The user id which should be sent as `@<id>` in the message
        `label` | string | The displayname of the user
        `source` | string | The type of the user, currently only `users`
        
### System messages

* `conversation_created` - {actor} created the conversation
* `conversation_renamed` - {actor} renamed the conversation from "foo" to "bar"
* `call_started` - {actor} started a call
* `call_joined` - {actor} joined the call
* `call_left` - {actor} left the call
* `call_ended` - Call with {user1}, {user2}, {user3}, {user4} and {user5} (Duration 30:23)
* `guests_allowed` - {actor} allowed guests in the conversation
* `guests_disallowed` - {actor} disallowed guests in the conversation
* `password_set` - {actor} set a password for the conversation
* `password_removed` - {actor} removed the password for the conversation
* `user_added` - {actor} added {user} to the conversation
* `user_removed` - {actor} removed {user} from the conversation
* `moderator_promoted` - {actor} promoted {user} to moderator
* `moderator_demoted` - {actor} demoted {user} from moderator
* `guest_moderator_promoted` - {actor} promoted {user} to moderator
* `guest_moderator_demoted` - {actor} demoted {user} from moderator
        
## Guests

### Set display name

* Method: `POST`
* Endpoint: `/guest/{token}/name`
* Data:

    field | type | Description
    ------|------|------------
    `displayName` | string | The new display name

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found` When the room is not found or the session does not exist in the room
        + `403 Forbidden` When the user is logged in
        
        
## Signaling

### Get signaling settings

* Method: `GET`
* Endpoint: `/signaling/settings`
* Data:

    field | type | Description
    ------|------|------------
    `stunservers` | array | STUN servers
    `turnservers` | array | TURN servers
    `server` | string | URL of the external signaling server
    `ticket` | string | Ticket for the external signaling server

    - STUN server
    
       field | type | Description
       ------|------|------------
       `url` | string | STUN server URL

    - TURN server
    
       field | type | Description
       ------|------|------------
       `url` | array | One element array with TURN server URL
       `urls` | array | One element array with TURN server URL
       `username` | string | User name for the TURN server
       `credential` | string | User password for the TURN server

* Response:
    - Header:
        + `200 OK`
        + `404 Not Found`

### External signaling API
See External Signaling API [Draft](https://github.com/nextcloud/spreed/wiki/Signaling-API) in the wiki…