Skip to content

Latest commit

 

History

History
192 lines (151 loc) · 6.76 KB

ocs-status-api.rst

File metadata and controls

192 lines (151 loc) · 6.76 KB

OCS Status API

The OCS Status API allows you to access and modify status API from outside over pre-defined OCS calls.

The base URL for all calls to the share API is: <nextcloud_base_url>/ocs/v2.php/apps/user_status/api/v1/user_status

All calls to OCS endpoints require the OCS-APIRequest header to be set to true.

User Status - Status Manipulation

Fetch your own status

  • Required capability: user_status
  • Method: GET
  • Endpoint: /
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found If the user does not have a status set

Set your own status

  • Required capability: user_status
  • Method: PUT
  • Endpoint: /status
  • Data:
field type Description Allowed values
statusType string New status for the authenticated user online, away, dnd, invisible, offline
  • Response:
    • Status code:
      • 200 OK
      • 400 Bad Request If the sent status-type is not valid

Set a custom message (predefined)

  • Required capability: user_status
  • Method: PUT
  • Endpoint: /message/predefined
  • Data:
field type Description
messageId string Message-Id of the predefined message
clearAt int Unix Timestamp representing the time to clear the status
  • Response:
    • Status code:
      • 200 OK
      • 400 Bad Request If the sent messageId does not exist
      • 400 Bad Request If the Unix timestamp is in the past

Set a custom message (user-defined)

  • Required capability: user_status, supports_emoji for statusIcon support
  • Method: PUT
  • Endpoint: /message/custom
  • Data:
field type Description
statusIcon string/null The icon picked by the user (must be an emoji, at most one)
message string The custom message picked by the user
clearAt int Unix Timestamp representing the time to clear the status
  • Response:
    • Status code:
      • 200 OK
      • 400 Bad Request If the statusIcon is not a an emoji or more than one emoji
      • 400 Bad Request If the message is too long
      • 400 Bad Request If the Unix timestamp is in the past

Clear message

  • Required capability: user_status
  • Method: DELETE
  • Endpoint: /message
  • Response:
    • Status code:
      • 200 OK

User Status - Predefined statuses

Base endpoint ics: /ocs/v2.php/apps/user_status/api/v1/predefined_statuses

Fetch the list of predefined statuses

  • Required capability: user_status
  • Method: GET
  • Endpoint: /
  • Response:
    • Status code:
      • 200 OK

User Status - Retrieve statuses

Base endpoint ics: /ocs/v2.php/apps/user_status/api/v1/statuses

Fetch a list of all set user-statuses

  • Required capability: user_status
  • Method: GET
  • Endpoint: /
  • Data:
field type Description
limit int Limit for pagination
offset int Offset for pagination
  • Response:
    • Status code:
      • 200 OK

Fetch a specific user's status

  • Required capability: user_status
  • Method: GET
  • Endpoint: /{userId}
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found If the user does not have a status set

Fetch a user's backup status

In some scenarios the user's status can be overwritten automatically, e.g. by joining a call in Nextcloud Talk, or when the availability automation is enabled. In this case the userId can be prefixed with an _ underscore, to get the original user status. When a user status is returned and the user_status > restore capability is available, the backup status should be added as an item in the predefined status list. Clicking that should then do an API call to User status - Restore backup should be done.

  • Required capability: user_status
  • Method: GET
  • Endpoint: /_{userId}
  • Response:
    • Status code:
      • 200 OK
      • 404 Not Found If the user does not have a backup status set

Files Sharing

The user-status is also exposed via the following Files Sharing APIs:
  • GET /ocs/v2.php/apps/files_sharing/api/v1/sharees
  • GET /ocs/v2.php/apps/files_sharing/api/v1/sharees_recommended
  • GET /ocs/v2.php/apps/files_sharing/api/v1/shares
  • GET /ocs/v2.php/apps/files_sharing/api/v1/shares/inherited
  • GET /ocs/v2.php/apps/files_sharing/api/v1/shares/pending
  • GET /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}
  • POST /ocs/v2.php/apps/files_sharing//api/v1/shares
  • PUT /ocs/v2.php/apps/files_sharing/api/v1/shares/{id}

User status - Restore backup

  • Required capability: user_status > restore
  • Method: DELETE
  • Endpoint: /revert/{messageId}
  • Response:
    • Status code:
      • 200 OK