nextcloud-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)
  • Add room to favorites
  • Remove room from favorites
  • Set notification level
• 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
  • Get signaling settings
  • External signaling API

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

Constants

Room types

• 1 "one to one"
• 2 group
• 3 public

Read-only states

• 0 read-write
• 1 read-only

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.

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

6.0

• locked-one-to-one-rooms - One-to-one conversations are now locked to the users. Neither guests nor other participants can be added, so the options to do that should be hidden as well. Also a user can only leave a one-to-one room (not delete). It will be deleted when the other participant left too. If the other participant posts a new chat message or starts a call, the left-participant will be re-added.
• read-only-rooms - Rooms can be in read-only mode which means people can not do calls or write chat messages.

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)
    readOnly	int	Read-only state for the current user (only available with read-only-rooms 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 or empty
    • 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
    • 400 Bad Request When the participant is a moderator/owner and there are no other moderators/owners left.
    • 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
    • 400 Bad Request When the participant is a moderator/owner and there are no other moderators/owners left.
    • 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
    • 400 Bad Request When the participant to promote is not a normal user (type 3)
    • 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

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
    • 400 Bad Request When the participant to demote is not a moderator (type 2)
    • 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

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)
    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
    • 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

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 in the wiki…