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, by the switches below, and a call is recorded if any of them applies. People can also record a single call from the phone with *1. 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 calls = Calls with outside numbers only | The same | The same, but only calls with someone outside the company: calls between colleagues are not recorded. |
| Record the calls this group connects | The ring group's settings | Every call answered through the ring group. |
| Record every call to this number | Inbound routes, 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 them, use the queue's or the ring group's own switch (see Call centre).
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.
Recording one call from the phone
During a call, press *1: the phone beeps and the call is recorded from then on. Press *1 again to stop (a lower tone). On a call that a switch above already records, *1 beeps twice and the recording goes on. The portal softphone's Record button does the same. Each person may do this unless an administrator unticks May record a call from the phone on their extension (onyx ext set acme 105 --record-ondemand off).
Recording notice
To tell outside callers that calls may be recorded, turn on Play a recording notice to outside callers in the Recording notice card on this page and choose the notice: the server's own voice ("This call may be recorded", made by the speech package) or one of your prompts. Every outside call to the company's phone numbers starts with it.
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 (--record external for outside calls only, and --record never to stop).
For a phone number: in Inbound routes, 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.
Call insights: transcripts, summaries and sentiment
Onyx Voice can turn recorded calls into text, with the two sides of the call told apart, and have a language model write a short summary, a sentiment score and the follow-ups that were promised. Only recorded calls get insights: turn recording on first (see What gets recorded).
Transcripts and summaries contain what was said on the call. With a cloud AI service, the words of the call (and with its speech-to-text, the audio) go to that service. Check that your customers' and staff's privacy rules allow it, and tell callers in your recording notice.
To turn call insights on:
- Set up the AI service once for the whole server: Server settings, card AI (call insights) (see AI (call insights)). Without it, calls are still transcribed but get no summary.
- A system administrator opens Tenants and sets the company's Call insights to Transcripts only or Transcripts, summaries and sentiment. From the command line:
onyx tenant set acme --insights insights(transcriptsoroff).
From then on, each recorded call is transcribed shortly after it ends, one call at a time. A call of a few minutes takes about a minute on a small server. Calls longer than 3 hours are not transcribed.
On Recordings, the Insights column shows the sentiment (Very negative to Very positive) and the first lines of the summary, or the state of the transcript (Transcribing soon, Transcribing..., Transcript failed). Click Transcript to see the summary, the topics, the follow-ups and the conversation turn by turn, each turn with who spoke and when. Transcribe again makes it again (for example after changing the AI service). The search box on Recordings also finds calls by words said on them.
Sentiment is the outside caller's mood by the end of the call (for a call between colleagues, the caller's), from 1 (very negative) to 5 (very positive), with one sentence saying why.
The call insights report
On Recordings, click How callers felt (or open Recordings › Call insights). For the period you choose it shows, by person, by direction and by ring group or queue: the number of transcribed calls, the average sentiment, and how many calls were negative (1-2) or positive (4-5). Calls to look at lists the most negative calls; Open shows the transcript.
How the two sides are told apart
For tenants with call insights, each recording also keeps the two sides of the call in separate files while it is waiting to be transcribed. The transcript names them: side A is usually the caller, side B the person or people who answered. The separate files are deleted once the transcript is saved; the normal recording stays. Recordings made before call insights were switched on are transcribed from the mixed recording, without telling the sides apart.
Transcripts are deleted with their recording (by hand, or by the retention period), and recordings on legal hold keep their transcript.
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 recording shows Transcript failed. Click Transcript to see why. "There is no speech model on this server" means the speech-to-text model that comes with the onyx-voice package is missing: reinstall the package. A refusal from the AI service names its reason (a wrong API key, a model name it does not know).
- Transcripts but no summaries. The tenant is set to Transcripts only, or the AI service is not set up: the transcript says "No summary: ..." with the reason. Use Save and test in Server settings, card AI (call insights).
- 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.