spreed/docs/api-v1.md

API v1 Documentation

• Constants
  • Room types
  • Participant types
• Room management
  • Creating a new room
  • Get user´s rooms
  • Get single room (also for guests)
  • Rename a room
  • Delete a room
  • Allow guests in a room (public room)
  • Disallow guests in a room (group room)
• Participant management
  • Get list of participants in a room
  • Add a participant to a room
  • Delete a participant from a room
  • Remove yourself from a room
  • Promote a user to a moderator
  • Demote a moderator to a user
• Call management
  • Get list of connected participants
  • Join a call
  • Send ping to keep the call alive
  • Leave a call (but staying in the room for future calls)
• Chat
  • Receive chat messages of a room
  • Sending a new chat message
• Guests
  • Set display name
• Signaling

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 and pagination is available, the previous chat is not available anymore.

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
    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
    unreadMessages	int	Number of unread chat messages in the room (only available with chat-v2 capability)

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

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 to add

• 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 user to add could not be found

  • Data:

    field	type	Description
    type	string	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 remove 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

Send ping to keep the call alive

• Method: POST

• Endpoint: /call/{token}/ping

• 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
    message	string	Message string with placeholders (see Rich Object String)
    messageParameters	array	Message parameters for message (see Rich Object String)

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
    • 404 Not Found When the room could not be found for the participant

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

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

See the Draft in the wiki…