Recordings API

List call recordings and fetch time‑limited download URLs, and choose where recordings go: kept in Telenow, or sent to you with no copy kept. All endpoints are organization‑scoped and return the dashboard envelope { "success": true, "data": { … } }.

Auth: an API key (X-API-Key, org implicit) or a user JWT plus X-Org-Id. Reads work with any valid key; POST /upload requires an owner, admin, or developer key, and PUT /delivery an owner or admin one. A key is pinned to its own org — another org's {orgId} in the path returns 403.

Endpoints

Paging and one call's recordings

Without parameters the list returns the newest 200 recordings. To read further back, or to read one call's parts, pass any of:

• sessionId — only that call's recordings;
• limit — page size, at most 200;
• cursor — the data.nextCursor of the page before; the next page starts just after its last recording.

nextCursor is set while a page came back full and null on the last page. Recordings stored after you started paging appear at the top of the list, never inside the pages behind your cursor.

Use /call-audio in browser code

This is the single most common "recording won't load" cause, and it is not a Telenow bug.

EasyPrivacy‑class filter lists (uBlock Origin, AdGuard, Brave Shields) block any URL containing recording — they're targeting session‑replay trackers like Hotjar and FullStory, and our path is collateral damage. The request never reaches the server; you see a failed XHR in devtools and an empty player, while the same URL fetched with curl returns 200.

/call-audio/{id}/file and /call-audio/{id}/signed-url are the same handlers behind the same auth — only the path differs, chosen to survive those filter lists. Rules of thumb:

• Browser/XHR/<audio src> → use /call-audio/….
• Server‑to‑server → either works; /recordings/… is fine and stays supported.

If a customer reports "Recording could not be loaded", have them try in a private window with extensions disabled before you investigate storage.

Downloading audio

Recordings are not public. Request a signed URL (valid 5 minutes) per recording id and use it immediately:

curl https://api.telenow.ai/api/orgs/{orgId}/recordings/{id}/signed-url \
  -H "X-API-Key: vai_live_…"

{ "success": true, "data": { "url": "https://…", "expiresAt": "2026-06-08T12:34:56Z" } }

GET …/{id}/file streams the bytes directly (local storage) or redirects to a signed storage URL (S3‑style backends) — useful for an <audio src>. It's JWT/key‑protected, so it can't be embedded in a public page; for that, fetch a signed-url instead.

Metadata

GET /api/orgs/{orgId}/recordings/{id}

The recording row carries: id, org_id, the session_id it belongs to, agent_id, channel (e.g. softphone, web, telephony), storage_kind, mime, sample_rate, duration_sec, size_bytes, metadata, and created_at. List with the org endpoint and filter by agent via ?agentId=:

{ "success": true, "data": { "recordings": [ /* … */ ], "total": 12 } }

Recordings on the call detail (the two‑recording case)

A single call can have more than one recording. The most common reason is a warm transfer: the AI portion (Telenow's in‑house mix, uploaded when the stream stops at transfer/hangup) and the bridged human portion (the carrier's own recording of the caller talking to the human, ingested after the transfer) are stored as two rows.

The single recording_id on the call (the latest) stays for back‑compat, but the call detail endpoint returns all of a call's recordings as an array, oldest first, so neither half is hidden:

GET /api/orgs/{orgId}/calls/{id}

{
  "success": true,
  "data": {
    "id": "…",
    "recording_id": "…",
    "recordings": [
      {
        "id": "…",
        "channel": "telephony",
        "duration_sec": 92,
        "created_at": "2026-06-08T12:30:11Z",
        "source": null
      },
      {
        "id": "…",
        "channel": "telephony",
        "duration_sec": 145,
        "created_at": "2026-06-08T12:31:48Z",
        "source": "transfer_bridge"
      }
    ]
  }
}

The source field marks the post‑transfer carrier recording as "transfer_bridge"; the AI conversation has source: null. Each part is downloaded by its own recording id through /recordings/{id}/signed-url (or /file) — there is no per‑call audio endpoint. Calls without a transfer return a single‑element array (or an empty one when nothing was recorded).

Uploading

POST /api/orgs/{orgId}/recordings/upload accepts multipart/form-data. This is how the browser web‑call widget stores its locally‑mixed HD audio; most server‑side recordings (softphone, telephony, transfer bridges) are created automatically and you never call this.

Send a real duration_sec. If it's absent or wrong, the recording can be stored with a duration derived from an epoch timestamp — which surfaces in the dashboard as an absurd length and breaks the player's seek bar. Pass the actual measured duration in seconds.

Limits and errors

Where recordings go

By default Telenow keeps each call recording: you play it in the dashboard, list and download it with the endpoints above, and receive recording.ready with a signed link. An owner or admin can instead have recordings sent to you, with no copy kept in Telenow. Each finished recording then goes to your webhook as a recording.audio event, and Telenow stores nothing: no file and no recording row. In the dashboard this is Settings → Organization → Call recordings → Where recordings go.

This setting only decides where the file goes. Whether a call is recorded at all is still its agent's telephony.recording setting, and on a softphone call the member's Record their softphone calls setting.

Read the setting

curl https://api.telenow.ai/api/orgs/{orgId}/recordings/delivery \
  -H "X-API-Key: $TELENOW_API_KEY"

{
  "success": true,
  "data": {
    "destination": "telenow",
    "sendModeAvailable": true,
    "audioEndpoints": { "orgWide": 1, "agentScoped": 0 },
    "ready": true
  }
}

An endpoint subscribed with ["*"] doesn't count: it never receives recording.audio, which goes only to endpoints that name it.

Change it

curl -X PUT https://api.telenow.ai/api/orgs/{orgId}/recordings/delivery \
  -H "X-API-Key: $TELENOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "destination": "send" }'

The body has one field, destination: "telenow" or "send". The answer is the same object as the GET, after the change.

Before you switch to send:

1. Create an endpoint with no agentId whose events include recording.audio. An endpoint scoped to one agent is not enough: it never receives other agents' recordings, or any softphone call's.
2. Make your receiver accept the recording.audio request. It is multipart/form-data, not JSON, and it carries the only copy of the audio.

Each recording follows the setting in force when it finishes, so a call already in progress when you switch follows the new choice. Recordings already kept in Telenow stay. Recordings sent while send was on were never kept, so switching back to telenow doesn't bring them here.

While recordings are sent to you

• Nothing is stored for new calls. They have no recording row, so the list, /file and /signed-url endpoints have nothing for them, the dashboard can't play them, and recording.ready doesn't fire. A recorded call's call.ended says "recordingMode": "send".
• Uploads are refused with 409 (see Uploading).
• A transferred call's bridged part is not recorded. In this mode Telenow asks no carrier to record a transferred call, because the carrier would keep its own copy.
• A recording that can't be delivered is gone. Telenow retries it for a while from memory only, then reports it as recording.failed. There is no copy to fetch later.
• The last endpoint that receives every recording is protected. While destination is send, you can't take recording.audio off the last endpoint with no agentId that has it, or delete that endpoint: both are refused with 409.

Errors (all endpoints)

recording.ready webhook

When a recording is finalized — including ones that land shortly after a call ends, such as a transfer bridge — Telenow fires the recording.ready webhook carrying a signed URL, so you can ingest audio without polling. While recordings are sent to you instead, nothing is stored and recording.ready doesn't fire: the audio itself arrives as recording.audio.

Related

• Calls, recordings & insights — where recordings surface in the dashboard.
• Making & receiving calls — how transfers produce two recordings.
• Sessions & calls API — the call detail object the recordings[] array lives on.