Docs / Reports and billing

Call recordings

Onyx Voice can record the calls of chosen people, phone numbers, queues and conference rooms. This chapter covers what gets recorded and how to turn it on, finding and playing recordings, deleting them, legal hold, how long recordings are kept, the space they take, backups, and the command line.

Many places require you to tell callers, staff or both that calls are recorded, and some require consent from everyone on the call. Check the rules that apply to you before you turn recording on, and say so in your greeting or hold announcement.

What gets recorded

Recording is decided when a call starts. There are four switches, and a call is recorded if any of them applies. A call is recorded once, however many phones it rings or transfers it goes through.

Switch	Where	What it records
Record calls = Every call	The extension's page, card Person and voicemail	Calls the person makes from their phones (to other extensions and to outside numbers), and calls that ring them directly: dialled to their extension, sent to them from a phone number (DID) or an auto attendant, or forwarded to them.
Record every call to this number	Phone numbers (DIDs), when you route a number	Calls to that number, when they ring an extension directly or are passed on to an outside number.
Record calls answered from this queue	The queue's settings	Every call answered through the queue.
Record conferences in this room	The conference room's settings	Each conference in the room, as one recording.

Calls that reach someone as a member of a ring group or a queue are not recorded by that person's own setting or by the phone number's setting. To record queue calls, use the queue's switch (see Call centre). Onyx Voice has no recording switch for ring groups, so calls an extension answers through a ring group are not recorded.

When a person logs in at a shared hot desk, their recording setting goes with them to that desk.

Only the conversation is recorded: ringing and time on hold in a queue are not. There is no key to start or stop recording in the middle of a call.

Turning recording on

For a person:

Open the extension in Extensions & numbers.
In Person and voicemail, set Record calls to Every call.
Click Save.

From the command line: onyx ext set acme 105 --record always (and --record never to stop).

For a phone number: in Phone numbers (DIDs), click Route a number, tick Record every call to this number and click Route this number. The route shows a Recorded badge. To change it on an existing route, remove the route and route the number again.

For a queue or a conference room: open it in Extensions & numbers, tick the record box and click Save. See Call centre and Conference rooms and the switchboard.

Where recordings are kept

Recordings are WAV files under /var/spool/onyx-voice/recordings, in a folder per tenant and per day (acme/2026/10/07/...). The call record in the database points at the file. Conference recordings are one file for the whole conference; each participant's call record points at the same file.

Finding and playing recordings

Open Recordings. The heading line says how many recording files the tenant has and how much space they use. (A system administrator works on the tenant picked at the top of the console.)

To find a recording:

In Find recordings, type part of a number or name under Number or name. It matches the calling number, the caller ID, the number dialled and the DID.
Optionally choose From and To dates, and tick Only recordings on legal hold.
Click Search.

The list shows the newest 50 recordings that match; click Load older recordings for more. Each row has When (with the direction of the call), From → to, Length (the talk time), Hold, and these buttons:

Play opens a player above the list, headed with the call's time and parties.
Download saves the WAV file.
Legal hold / Lift hold; see Legal hold.
Delete removes the recording.

You can also play a recorded call from Call history: recorded calls have a player in the Recording column. See Call history and reports.

Recordings are for administrators: tenant administrators see their tenant's, system administrators every tenant's. People cannot play recordings of their own calls in the user portal.

Deleting a recording

Click Delete on the row, then Click again to confirm within four seconds. The file is deleted and the call stays in Call history without its recording. A recording on legal hold cannot be deleted until the hold is lifted. Deleting a conference recording removes it for every participant's call. Every deletion is listed in Change history.

Legal hold

A recording on legal hold is never deleted, neither by hand nor by the retention period. Use it when a recording may be needed for a dispute, a complaint or an investigation.

To put a recording on hold:

Find it in Recordings and click Legal hold.
Type the reason, for example a case or ticket number and who asked for it. A reason is required.
Click Hold.

The Hold column then shows "On hold:" and the reason. To see everything on hold, tick Only recordings on legal hold and search. To release one, click Lift hold; it then follows the retention period again, so a recording older than the period is deleted at the next hourly run.

Holds act on the file: holding a conference recording holds it for every participant's call. Every hold and release is listed in Change history, with the reason.

How long recordings are kept

Each tenant has a retention period. By default it is 0: recordings are kept until someone deletes them.

To set it:

Open Recordings.
Under Keep recordings for, enter the number of Days (1 to 3650, or 0 to keep them until deleted).
Click Save.

Once an hour the server deletes the recordings of that tenant whose call is older than the period, except recordings on legal hold. The calls stay in Call history; only the recordings go. The first run is a couple of minutes after the service starts. A conference recording is deleted once the newest call pointing at it is past the period. The purge is listed in Change history.

From the command line:

onyx recordings retention acme          show the tenant's period
onyx recordings retention acme 90       keep recordings 90 days
onyx recordings retention acme 0        keep recordings until deleted
onyx recordings purge                   delete recordings past their period now, for every tenant

In a cluster, the active server runs the purge and the other server's copy follows. See High availability.

Storage

Recordings take about 1 MB per minute of call, so they are usually what fills the disk. Watch:

The heading line on Recordings: files and space for the tenant.
Server › Storage, What uses the space: the Call recordings line for the whole server. When the disk gets full, voicemail and recordings can no longer be saved, and the page warns you before that happens. You can grow the volume or move voicemail and recordings onto a disk of their own there.

Set a retention period for each tenant that records a lot. See Server tools.

Recordings and backups

Backups leave call recordings out unless you ask for them, because they can be large. To include them, open Server › Backup and tick Include call recordings (they can be large) in the Schedule card. A restore puts recordings back only if the backup has them. If you keep recordings only on this server, a lost disk loses them; either include them in backups or copy them elsewhere yourself. See Backup and restore.

Recordings from the command line

onyx recordings acme lists the tenant's latest recorded calls (25 by default; --limit 100 for more) with the start time in UTC, from, to, talk time and the full path of the file. It looks through the tenant's latest 1000 calls. With the path you can copy a file off the server, for example with scp.

When it does not work

A call that should have been recorded is not. Check which switch applies in the table at the top: a call answered through a ring group, or through a queue without its own recording switch, is not recorded.
"The recording file is gone (deleted or not finished yet)". The call is still in progress, or the file was deleted on the server. Recordings are complete once the call ends.
"This recording is on legal hold. Lift the hold first." Lift the hold, then delete it.