NUACOM API

Calls

Call Recording

Call recordings are the audio files of recorded calls, kept per account and addressed by the call's call_id. This group holds the playback and download endpoint, the admin-only delete and the account's storage statistics. The call row that tells you a recording exists is in Call Logs; the transcript of a recording is in Speech To Text and follows the same access rule as playback.

Workflow (what the portal does)

  1. Find the call: the rows of GET /v2/call-log carry recording (true when a file exists and the user may listen to it) and the call's ids. Use the row's call_id, the telephony id shared by the legs of one call, for everything in this group; call_unique_id is the row's own id and is not a recording id. Call Logs explains how to read a row.
  2. Play or download: GET /v3/call-recording/{callId} streams the file. format is 0 for MP3 (the default), 1 for OGG or 2 for WAV; start and end trim the audio and are positions in seconds with optional decimals (90.5). Send both or neither. The answer is the audio bytes with Content-Disposition: attachment; filename=… and a Content-Type detected from the file. The endpoint supports HTTP range requests: a Range: bytes=… header is answered with 206 and Content-Range, a range past the end of the file with 416. Each playback is recorded in the account's recording access log (user, time and IP address).
  3. Transcript: GET /v2/speech-to-text/{callUniqueId} takes the same call_id (its parameter is named callUniqueId, but it is this value) when the account has transcription enabled, and applies the access rule of playback.
  4. Delete (account admin): DELETE /v2/call-recording/{callUniqueId}, again with the row's call_id. It removes the file and its transcript, sets the call row's recording to false and answers 204, also when no recording exists for that id. There is no undo; the deletion is written to the access log.
  5. Storage (account admin): GET /v2/call-recording/statistics answers used (value in bytes, formatted, and percentage of the allowance as a string such as "6.84"), allowed (value in GB, formatted as "10 Gb") and oldest_file.date (null when nothing is stored). The allowance is the recording storage of the account's subscriptions that include recording plus any storage add-ons; when it is 0, percentage is "100".
# The whole call as MP3, saved to disk
curl -o call.mp3 \
  'https://api.api-nuacom.com/v3/call-recording/1761640800.123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Seconds 30 to 90 only, as OGG
curl -o excerpt.ogg \
  'https://api.api-nuacom.com/v3/call-recording/1761640800.123?format=1&start=30&end=90' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Who can access a recording

flowchart TD
    start{"No Recordings add-on active?"} -- "yes" --> denyAll["403 for everyone, admins included"]
    start -- "no" --> admin{"Account admin?"}
    admin -- "yes" --> allow["Playback and transcript allowed"]
    admin -- "no" --> toggle{"Call Recording Access toggle on?"}
    toggle -- "no" --> deny["403"]
    toggle -- "yes" --> access{"Call-log access to this call?<br/>(all, own extension, or granted extension/queue/number)"}
    access -- "yes" --> allow
    access -- "no" --> deny

Roles and access

  • Playback and transcript: an account admin can play every recording of the account. Any other user needs the Call Recording Access toggle on their user profile (an account admin sets it in the portal's user settings) and access to the call through their call-log permissions: call-log access "all", or a call on their own extension or on an extension, queue or number granted to them. Otherwise the answer is 403.
  • The No Recordings add-on, when active on the account, blocks playback and transcripts for everyone, admins included (403).
  • The recording flag on call rows is decided by a stricter test than playback: the Call Recording Access toggle must be on even for an admin, and a non-admin user also needs the account to hold the call recording add-on or a subscription that includes recording. An admin whose toggle is off therefore sees recording: false on rows they can still play.
  • Delete and statistics are account admin only; any other user gets 403 with the body "Forbidden".
  • With the account's ISO dates option, oldest_file.date is ISO 8601 in the requested timezone (UTC by default); without it, it is Y-m-d H:i:s in Irish time.

Pitfalls

  • format on playback is a number (0, 1, 2); anything else answers 422.
  • Trimming needs both start and end, as plain decimals (90.5, not 1:30), with end after start.
  • A recording is prepared on demand: fetched from storage, decrypted and, for OGG, WAV or a trim, converted. The first request for a given file and format can take a few seconds; the prepared file is reused for about two minutes.
  • An id that is not a call_id (for example a call_unique_id) answers 404; for a user with limited call-log access it answers 403 instead, because the visibility check runs first.
  • A row with recording: true can still answer 404: recordings are kept for six months by default (longer with a retention add-on), and a deleted recording is gone at once.
  • DELETE answers 204 for an id that has no recording, so a mistyped id looks like success.