Call recording API#

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

Start call recording#

  • Required capability: recording-v1
  • Method: POST
  • Endpoint: /recording/{token}
  • Data:
Field Type Description
status int Type of call recording (see Constants - Call recording status)
  • Response:
    • Status code:
      • 200 OK
      • 400 Bad Request Message: status. When the status to start is invalid.
      • 400 Bad Request Message: config. Need to enable the config recording.
      • 400 Bad Request Message: recording. Already have a recording in progress.
      • 400 Bad Request Message: call. Call is not activated.
      • 401 Unauthorized When the participant is a guest.
      • 403 Forbidden When the user is not a moderator/owner.
      • 412 Precondition Failed When the lobby is active and the user is not a moderator.

Stop call recording#

  • Required capability: recording-v1
  • Method: DELETE

  • Endpoint: /recording/{token}

  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request Message: config. Need to enable the config recording.
      • 400 Bad Request Message: call. Call is not activated.
      • 401 Unauthorized When the participant is a guest.
      • 403 Forbidden When the user is not a moderator/owner.
      • 412 Precondition Failed When the lobby is active and the user is not a moderator.

Store call recording#

  • Required capability: recording-v1
  • Method: POST

  • Endpoint: /recording/{token}/store

  • Header:

field type Description
TALK_RECORDING_RANDOM string Random string that needs to be concatenated with room token to generate the checksum using the recording_servers['secret'].
TALK_RECORDING_CHECKSUM string The checksum generated with TALK_RECORDING_RANDOM.
  • Data:
field type Description
file string File with the recording in a multipart/form-data request.
owner string The person that started the recording.
  • Response:
    • Status code:
      • 200 OK
      • 400 Bad Request Error: invalid_file: File in block list or invalid
      • 400 Bad Request Error: empty_file: Invalid file extension
      • 400 Bad Request Error: file_mimetype: Invalid mimetype
      • 400 Bad Request Error: file_name. :nvalid file name
      • 400 Bad Request Error: file_extension: Invalid file extension
      • 400 Bad Request Error: owner_participant: Owner is not to be a participant of room
      • 400 Bad Request Error: owner_invalid: Owner invalid
      • 400 Bad Request Error: owner_permission: Owner have not permission to store record file
      • 401 Unauthorized When the validation as recording server failed
      • 404 Not Found Room not found
      • 429 Too Many Request Brute force protection

Dismiss store call recording notification#

  • Required capability: recording-v1
  • Method: DELETE
  • Endpoint: /recording/{token}/notification
  • Data:
field type Description
timestamp string Timestamp in seconds and UTC time zone that notification was created.
  • Response:
    • Status code:
      • 200 OK
      • 403 Forbidden When the user is not a moderator/owner.
      • 404 Not Found Room not found

Share store call recording#

  • Required capability: recording-v1
  • Method: POST
  • Endpoint: /recording/{token}/share-chat
  • Data:
field type Description
timestamp string Timestamp in seconds and UTC time zone that notification was created.
fileId integer File id of recording to share at the room.
  • Response:
    • Status code:
      • 200 OK
      • 400 Bad Request Error: file: Shared file is invalid
      • 400 Bad Request Error: system: Internal system error
      • 403 Forbidden When the user is not a moderator/owne
      • 404 Not Found Room not found

Recording server requests#

  • Required capability: recording-v1
  • Method: POST

  • Endpoint: /recording/backend

  • Header:

field type Description
TALK_RECORDING_RANDOM string Random string that needs to be concatenated with request body to generate the checksum using the secret configured for the backend.
TALK_RECORDING_CHECKSUM string The checksum generated with TALK_RECORDING_RANDOM.

  • Data:

    • Body as a JSON encoded string; format depends on the request type, see below.

  • Response:

    • Status code:
      • 200 OK
      • 400 Bad Request: When the body data does not match the expected format.
      • 403 Forbidden: When the request validation failed.

Started call recording#

  • Data format:

    json { "type": "started", "started": { "token": "the-token-of-the-room", "status": "the-type-of-recording (see [Constants - Call recording status](constants.md#call-recording-status))", "actor": { "type": "the-type-of-the-actor", "id": "the-id-of-the-actor", }, }, }

  • Response:

    • (Additional) Status code:
      • 404 Not Found: When the room is not found.

Stopped call recording#

  • Data format:

    json { "type": "stopped", "stopped": { "token": "the-token-of-the-room", "actor": { "type": "the-type-of-the-actor", "id": "the-id-of-the-actor", }, }, }

    • actor is optional

  • Response:

    • (Additional) Status code:
      • 404 Not Found: When the room is not found.

Failed call recording#

  • Data format:

    json { "type": "failed", "failed": { "token": "the-token-of-the-room", }, }

  • Response:

    • (Additional) Status code:
      • 404 Not Found: When the room is not found.