spreed/docs/api-v1.md

API v1 Documentation

• Constants
  • Conversation types
  • Read-only states
  • Participant types
  • Actor types of chat messages
• Conversation management
  • Creating a new conversation
  • Get user´s conversations
  • Get single conversation (also for guests)
  • Rename a conversation
  • Set read-only for a conversation
  • Set password for a conversation
  • Delete a conversation
  • Allow guests in a conversation (public conversation)
  • Disallow guests in a conversation (group conversation)
  • Add conversation to favorites
  • Remove conversation from favorites
  • Set notification level
• Participant management
  • Get list of participants in a conversation
  • Add a participant to a conversation
  • Delete a participant from a conversation
  • Remove yourself from a conversation
  • 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 conversation for future calls)
• Chat
  • Receive chat messages of a conversation
  • Sending a new chat message
  • Get mention autocomplete suggestions
  • System messages
• Guests
  • Set display name
• Signaling
  • Get signaling settings
  • External signaling API

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

Constants

Conversation types

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

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

Actor types of chat messages

• guests - guest users
• users - logged-in users
• bots - used by commands (actor-id is the used /command) and the changelog conversation (actor-id is changelog)

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 conversations 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 conversations at the same time now, therefor signaling now also requires the conversation 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 - Conversations can be marked as favorites which will pin them to the top of the conversation list.
• last-room-activity - Conversations 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 conversation 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 conversation (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 - Conversations can be in read-only mode which means people can not do calls or write chat messages.

Conversation management

Creating a new conversation

• Method: POST

• Endpoint: /room

• Data:

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

• Response:

  • Header:

    • 200 OK when the "one to one" conversation already exists
    • 201 Created when the conversation was created
    • 400 Bad Request when an invalid conversation 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 conversation which is used for further interaction
    name	string	Name of the conversation (can also be empty)
    displayName	string	name if non empty, otherwise it falls back to a list of participants

Get user´s conversations

• Method: GET

• Endpoint: /room

• Response:

  • Header:

    • 200 OK
    • 401 Unauthorized when the user is not logged in

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

    field	type	Description
    token	string	Token identifier of the conversation which is used for further interaction
    type	int
    name	string	Name of the conversation (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 conversation has a password
    hasCall	bool	Flag if the conversation has an active call
    lastActivity	int	Timestamp of the last activity in the conversation, in seconds and UTC time zone
    isFavorite	bool	Flag if the conversation 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 conversation (only available with chat-v2 capability)
    unreadMention	bool	Flag if the user was mentioned since their last visit
    lastMessage	message	Last message in a conversation if available, otherwise empty
    objectType	string	The type of object that the conversation is associated with; "share:password" if the conversation is used to request a password for a share, otherwise empty
    objectId	string	Share token if "objectType" is "share:password", otherwise empty

Get single conversation (also for guests)

• Method: GET

• Endpoint: /room/{token}

• Response:

  • Header:

    • 200 OK
    • 404 Not Found When the conversation could not be found for the participant

  • Data: See array definition in Get user´s conversations

Rename a conversation

• Method: PUT

• Endpoint: /room/{token}

• Data:

  field	type	Description
  roomName	string	New name for the conversation (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 conversation could not be found for the participant
    • 405 Method Not Allowed When the conversation is a one to one conversation

Set read-only for a conversation

• Method: PUT

• Endpoint: /room/{token}/read-only

• Data:

  field	type	Description
  state	int	New state for the conversation

• Response:

  • Header:
    • 200 OK
    • 400 Bad Request When the conversation type does not support read-only (only group and public conversation atm)
    • 403 Forbidden When the current user is not a moderator/owner or the conversation is not a public conversation
    • 404 Not Found When the conversation could not be found for the participant

Set password for a conversation

• Method: PUT

• Endpoint: /room/{token}/password

• Data:

  field	type	Description
  password	string	New password for the conversation

• Response:

  • Header:
    • 200 OK
    • 403 Forbidden When the current user is not a moderator/owner or the conversation is not a public conversation
    • 404 Not Found When the conversation could not be found for the participant

Delete a conversation

• 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 conversation could not be found for the participant

Allow guests in a conversation (public conversation)

• 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 conversation could not be found for the participant

Disallow guests in a conversation (group conversation)

• 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 conversation could not be found for the participant

Set conversation password

• Method: PUT

• Endpoint: /room/{token}/password

• Data:

  field	type	Description
  password	string	Set a new password for the conversation

• Response:

  • Header:
    • 200 OK
    • 403 Forbidden When the current user is not a moderator/owner
    • 403 Forbidden When the conversation is not a public conversation
    • 404 Not Found When the conversation could not be found for the participant

Add conversation to favorites

• Method: POST

• Endpoint: /room/{token}/favorite

• Response:

  • Header:
    • 200 OK
    • 404 Not Found When the conversation could not be found for the participant or the participant is a guest

Remove conversation from favorites

• Method: DELETE

• Endpoint: /room/{token}/favorite

• Response:

  • Header:
    • 200 OK
    • 404 Not Found When the conversation 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 conversation could not be found for the participant or the participant is a guest

Participant management

Get list of participants in a conversation

• Method: GET

• Endpoint: /room/{token}/participants

• Response:

  • Header:

    • 200 OK
    • 404 Not Found When the conversation 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 conversation

• 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 conversation 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 conversation type changed, the new value is returned

Delete a participant from a conversation

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

Remove a guest from a conversation

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

Remove yourself from a conversation

• 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 conversation could not be found for the participant

Join a conversation (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 conversation 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 conversation could not be found for the participant

  • Data:

    field	type	Description
    sessionId	string	512 character long string

Leave a conversation (not available for call and chat anymore)

• Method: DELETE

• Endpoint: /room/{token}/participants/active

• Response:

  • Header:
    • 200 OK
    • 404 Not Found When the conversation 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 conversation 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 conversation 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 conversation 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 conversation could not be found for the participant

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

• Method: DELETE

• Endpoint: /call/{token}

• Response:

  • Header:
    • 200 OK
    • 404 Not Found When the conversation could not be found for the participant

Chat

Receive chat messages of a conversation

• Method: GET

• Endpoint: /chat/{token}

• Data:

  field	type	Description
  lookIntoFuture	int	1 Poll and wait for new message or 0 get history of a conversation
  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 conversation 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	Conversation 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 conversation 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 conversation

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 conversation 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
• read_only_off - {actor} unlocked the conversation
• read_only - {actor} locked the conversation

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 conversation is not found or the session does not exist in the conversation
    • 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…