Conversation avatar API#

  • API v1: Base endpoint /ocs/v2.php/apps/spreed/api/v1: since Nextcloud 27

Set conversations avatar#

  • Required capability: avatar
  • Method: POST
  • Endpoint: /room/{token}/avatar
  • Data:
field type Description
file string Blob of image in a multipart/form-data request. Only accept images with mimetype equal to PNG or JPEG and need to be squared image.

  • Response:

    • Status code:

      • 200 OK
      • 400 Bad Request When: is one-to-one, no image, file is too big, invalid mimetype or resource, isn't square, unknown error
      • 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

    • Data:

      • 200 OK: See array definition in Get user´s conversations
      • 400 Bad Request: Array with a message field contain the error in user language

Set emoji as avatar#

  • Required capability: avatar
  • Method: POST
  • Endpoint: /room/{token}/avatar/emoji
  • Data:
field type Description
emoji string A single emoji being used as avatar (can contain properties like gender, skin color, age, job, etc.)
color string/null HEX color code (6 times 0-9A-F) without the leading # character (omit to fallback to the default bright/dark mode icon background color)

  • Response:

    • Status code:

      • 200 OK
      • 400 Bad Request When the conversation is a one-to-one conversation
      • 400 Bad Request When the emoji is not a single emoji
      • 400 Bad Request When color was provided but is not matching the expected pattern
      • 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

    • Data:

      • 200 OK: See array definition in Get user´s conversations
      • 400 Bad Request: Array with a message field contain the error in user language

Delete conversations avatar#

Note

To determine if the delete option should be presented to the user, it's recommended to check the isCustomAvatar property of the Get user´s conversations API.

  • Required capability: avatar
  • Method: DELETE

  • Endpoint: /room/{token}/avatar

  • Response:

    • Status code:

      • 200 OK
      • 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

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

Get conversations avatar (binary)#

  • Required capability: avatar
  • Federation capability: federation-v1
  • Method: GET

  • Endpoint: /room/{token}/avatar

  • Response:

    • Status code:
      • 200 OK
      • 404 Not Found When the conversation could not be found for the participant
    • Body: the image file

Get dark mode conversations avatar (binary)#

  • Required capability: avatar
  • Federation capability: federation-v1
  • Method: GET

  • Endpoint: /room/{token}/avatar/dark

  • Response:

    • Status code:
      • 200 OK
      • 404 Not Found When the conversation could not be found for the participant
    • Body: the image file

Get federated user avatar (binary)#

  • Required capability: federation-v1
  • Method: GET
  • Endpoint: /proxy/{token}/user-avatar/{size}
  • Data:
field type Description
size int Only 64 and 512 are supported
cloudId string Federation CloudID to get the avatar for
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found When the conversation could not be found for the participant
    • Body: the image file

Get dark mode federated user avatar (binary)#

  • Required capability: federation-v1
  • Method: GET
  • Endpoint: /proxy/{token}/user-avatar/{size}/dark
  • Data:
field type Description
size int Only 64 and 512 are supported
cloudId string Federation CloudID to get the avatar for
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found When the conversation could not be found for the participant
    • Body: the image file