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#

  • Method: GET
  • Endpoint: /room
  • Data:

    field type Description
    noStatusUpdate int Whether the "online" user status of the current user should be "kept-alive" (1) or not (0) (defaults to 0)
    includeStatus bool Whether the user status information of all one-to-one conversations should be loaded (default false)
  • 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.
    • 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
      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 Currently known users|guests|emails|groups|circles
      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)
      attendeePermissions int v4 Dedicated permissions for the current participant, if not Custom this are not the resulting permissions (see constants list)
      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)
      defaultPermissions int v4 Default permissions for new participants (see constants list)
      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)
      count int v1 v2 Removed: Count the users on the 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 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
      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, 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
      notificationLevel int v1 The notification level for the user (See Participant notification levels)
      lobbyState int v1 Webinar lobby restriction (0-1), if the participant is a moderator they can always join the conversation (only available with webinary-lobby capability) (See Webinar lobby states)
      lobbyTimer int v1 Timestamp when the lobby will be automatically disabled (only available with webinary-lobby capability)
      sipEnabled int v3 SIP enable status (see constants list)
      canEnableSIP int v3 Whether the given user can enable SIP for this conversation. Note that when the token is not-numeric only, SIP can not be enabled even if the user is permitted and a moderator of the conversation
      unreadMessages int v1 Number of unread chat messages in the conversation (only available with chat-v2 capability)
      unreadMention bool v1 Flag if the user was mentioned since their last visit
      unreadMentionDirect bool v4 Flag if the user was mentioned directly (ignoring @all mentions) since their last visit (only available with direct-mention-flag capability)
      lastReadMessage int v1 ID of the last read message in a room (only available with chat-read-marker capability)
      lastCommonReadMessage int v3 ID of the last message read by every user that has read privacy set to public in a room. When the user themself has it set to private the value is 0 (only available with chat-read-status capability)
      lastMessage message v1 Last message in a conversation if available, otherwise empty. Note: Even when given the message will not contain the parent or reactionsSelf attribute due to performance reasons
      objectType string v1 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 v1 Share token if "objectType" is "share:password", otherwise empty
      status string v4 Optional: Only available for one-to-one conversations and when includeStatus=true is set
      statusIcon string v4 Optional: Only available for one-to-one conversations and when includeStatus=true is set
      statusMessage string v4 Optional: Only available for one-to-one conversations and when includeStatus=true is set
      participants array v1 v2 Removed
      guestList string v1 v2 Removed

Creating a new conversation#

  • Method: POST
  • Endpoint: /room
  • Data:

    field type Description
    roomType int See constants list
    invite string user id (roomType = 1), group id (roomType = 2 - optional), circle id (roomType = 2, source = 'circles'], only available with circles-support capability))
    source string The source for the invite, only supported on roomType = 2 for groups and circles (only available with circles-support capability)
    roomName string conversation name (Not available for roomType = 1)
  • Response:

    • Status code:

      • 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
      • 400 Bad Request When the conversation name is empty for type = 3
      • 401 Unauthorized When the user is not logged in
      • 404 Not Found When the target to invite does not exist
    • Data: See array definition in Get user´s conversations

Get single conversation (also for guests)#

  • Method: GET
  • Endpoint: /room/{token}

  • Response:

    • Status code:

      • 200 OK
      • 404 Not Found When the conversation could not be found for the participant
    • 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.
    • Data: See array definition in Get user´s conversations

Get open conversations#

  • Required capability: listable-rooms
  • Method: GET
  • Endpoint: /listed-room

  • Response:

    • Status code:

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

      field type Description
      searchTerm string search term
    • 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:

    • Status code:
      • 200 OK
      • 400 Bad Request When the name is too long or empty
      • 400 Bad Request When the conversation is a one to one conversation
      • 403 Forbidden When the current user is not a moderator/owner
      • 404 Not Found When the conversation could not be found for the participant

Delete a conversation#

  • Method: DELETE
  • Endpoint: /room/{token}

  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the conversation is a one-to-one conversation (Use Remove yourself from a conversation instead)
      • 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 description for a conversation#

  • Required capability: room-description
  • Method: PUT
  • Endpoint: /room/{token}/description
  • Data:

    field type Description
    description string New description for the conversation
  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the description is too long
      • 400 Bad Request When the conversation is a one to one conversation
      • 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:

    • Status code:
      • 200 OK
      • 400 Bad Request When the conversation is not a group conversation
      • 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:

    • Status code:
      • 200 OK
      • 400 Bad Request When the conversation is not a public conversation
      • 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 read-only for a conversation#

  • Required capability: read-only-rooms
  • Method: PUT
  • Endpoint: /room/{token}/read-only
  • Data:

    field type Description
    state int New state for the conversation, see constants list
  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the conversation type does not support read-only (only group and public conversation)
      • 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:

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

Set default or call permissions for a conversation#

  • Method: PUT
  • Endpoint: /room/{token}/permissions/{mode}
  • Data:

    field type Description
    mode string default or call, in case of call the permissions will be reset to 0 (default) after the end of a call.
    permissions int New permissions for the attendees, see constants list. If permissions are not 0 (default), the 1 (custom) permission will always be added. Note that this will reset all custom permissions that have been given to attendees so far.
  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the conversation type does not support setting publishing permissions, e.g. one-to-one conversations
      • 400 Bad Request When the mode is invalid
      • 403 Forbidden When the current user is not a moderator, owner or guest moderator
      • 404 Not Found When the conversation could not be found for the participant

Add conversation to favorites#

  • Required capability: favorites
  • Method: POST
  • Endpoint: /room/{token}/favorite

  • Response:

    • Status code:
      • 200 OK
      • 401 Unauthorized When the participant is a guest
      • 404 Not Found When the conversation could not be found for the participant

Remove conversation from favorites#

  • Required capability: favorites
  • Method: DELETE
  • Endpoint: /room/{token}/favorite

  • Response:

    • Status code:
      • 200 OK
      • 401 Unauthorized When the participant is a guest
      • 404 Not Found When the conversation could not be found for the participant

Set notification level#

  • Required capability: notification-levels
  • Method: POST
  • Endpoint: /room/{token}/notify
  • Data:

    field type Description
    level int The notification level (See Participant notification levels)
  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the given level is invalid
      • 401 Unauthorized When the participant is a guest
      • 404 Not Found When the conversation could not be found for the participant

Set notification level for calls#

  • Required capability: notification-calls
  • Method: POST
  • Endpoint: /room/{token}/notify-calls
  • Data:

    field type Description
    level int The call notification level (See Participant call notification levels)
  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the given level is invalid
      • 401 Unauthorized When the participant is a guest
      • 404 Not Found When the conversation could not be found for the participant

Open a conversation#

  • Required capability: listable-rooms
  • Method: PUT
  • Endpoint: /room/{token}/listable
  • Data:

    field type Description
    scope int New flags for the conversation
  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request When the conversation type does not support making it listable (only group and public conversation)
      • 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