Recordings

Every voice and video call is recorded by default: one stereo Ogg/Opus file, the caller on the left channel and the agent on the right. Turn it off with recording.enabled: false on the agent, or for one call with agent_override.recording (per-call configuration). Read what a call produced from session.recording on GET /v1/calls/{session_id}.

{
  "recording": {
    "enabled": true,
    "notice": "This call is recorded for quality and training purposes."
  },
  "greeting": {"message": "Hi, thanks for calling Acme. {{recording.notice}} How can I help?"}
}

The file is what the agent heard after noise cancellation, not a tap on the phone line, and it excludes background audio. It covers the agent’s part of the call: hold time during a transfer is inside it as silence, and nothing after a transfer connects is recorded.

Playing and downloading

The call detail carries ready-made signed links, so a player needs no second request.

# -L follows the 302 to object storage; -o writes the file.
curl -L -o call.ogg \
  "https://api.talqing.com/v1/calls/9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1/recording?download=true" \
  -H "Authorization: Bearer $TALQING_API_KEY"

const call = await talqing.calls.get({
  session_id: "9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1",
});

if (call.session.recording.state === "available") {
  audioElement.src = call.session.recording.url!;
}

call = talqing.calls.get("9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1")

recording = call["session"]["recording"]
if recording["state"] == "available":
    print(recording["url"], recording["url_expires_at"])

GET /v1/calls/{session_id}/recording responds 302 to object storage. The link supports Range (seeking) and expires within an hour. download=true serves it as an attachment named call-{session_id}.ogg.

Do not store a signed link — ask for a fresh one each time. A URL copied from a webhook payload or a log stops working within the hour.

`recording` on a call

Field	Meaning
`state`	Whether there is anything to play. See below. On list rows and the detail.
`started_at`, `duration_s`, `bytes`	The file’s start, its own duration (matches the scrub bar) and size.
`url`	Plays inline. Detail only, and only when `state` is `available`.
`download_url`	The same object as a named download. Detail only.
`url_expires_at`	When both links stop working. Ask again for fresh ones.
`expires_at`	When retention will erase this call’s content; `null` while retention is unlimited (the default). Detail only.

`state`

available is the only playable state. Any other makes the redirect endpoint return 404 with the message below.

`state`	Meaning	`404` message
`available`	Stored and playable.	—
`none`	Recording was off for this agent, or the call had no audio.	`this call was not recorded — recording is off for this agent`
`pending`	The call is live, or the upload is running. Becomes `failed` if nothing arrives within five minutes of the call ending.	`the call is still in progress; its recording is not ready yet`
`failed`	Recording was on and produced nothing. The call, transcript and cost are unaffected.	`this call's recording could not be saved`
`deleted`	Someone deleted it.	`this recording was deleted`
`expired`	Your retention policy deleted it.	`this recording was deleted under your organization's data retention policy`
`not_shared`	Screen recording only: it was on and nobody shared a screen.	`nobody shared their screen on this call`

Recording notice

recording.notice is null by default: the call is recorded and Talqing tells the caller nothing. Whether that is lawful for you depends on your jurisdiction. The API has no default sentence; the dashboard fills in “This call is recorded for quality and training purposes.” when you turn the notice on. With a notice set, a greeting message must contain {{recording.notice}}, which resolves to the sentence and is spoken word for word. A message carrying the notice cannot be interrupted. A greeting written as instructions needs no token: the notice plays on its own, uninterruptibly, just before the generated line. Saving is refused when:

Condition	Error
Recording is off	`a recording notice announces a recording, but recording is off - …`
The greeting message lacks the token	`recording.notice is set, so the greeting message must contain {{recording.notice}} to say where the notice is spoken`
There is no greeting	`a recording notice is spoken with the greeting - …`
The agent uses a realtime model	`a recording notice needs a cascade pipeline (STT + LLM + TTS)…` — a realtime model may reword the notice
The greeting has the token but `notice` is `null`	`the greeting reads {{recording.notice}} but recording.notice is not set - …`

{{recording.notice}} resolves only in the greeting message; anywhere else, greeting instructions included, it is an error. The old {{consent.notice}} is refused with which was renamed - write {{recording.notice}} instead. On a handoff, a target that also has a notice stays quiet if the caller was already told; a target with recording off pauses the recorder. A resumed call speaks the notice again, because it is a new recording. Each time the notice finishes playing, the call records a recording.notice_given event with agent_id, agent_name, notice and interrupted (true only when the caller hung up mid-notice). It is the one event that survives a content purge. There is no tool for the caller to stop a recording mid-call: a recording kept as a record must not be erasable from inside it. Turn recording off for an agent, or delete a recording afterwards.

Screen recordings

A separate artifact of a web voice or video call, in session.screen_recording with the same shape and states as recording.


Enabled by	`vision_input.screenshare.record` on the agent, off by default. See vision and images.
Format	One 1 fps H.264 MP4, `call-{session_id}-screen.mp4`.
Coverage	The whole call, black where nobody was sharing, so it lines up with the audio and transcript.
Endpoint	`GET /v1/calls/{session_id}/screen-recording` — same `302`, one-hour link, `Range` and `download=true`.

Phone calls have no screen recording.

Deleting

DELETE /v1/calls/{session_id}/recording deletes the audio and the screen video together and returns 204. The transcript, tool calls, cost and analysis stay.

Immediate and cannot be undone.

It succeeds quietly on anything not available and leaves its state alone, so failed and expired are never overwritten. A pending recording has nothing stored yet; delete again once the call has settled.

curl -X DELETE \
  https://api.talqing.com/v1/calls/9c1f6ad2-3b47-4e58-9a2c-7f0d51e8c4b1/recording \
  -H "Authorization: Bearer $TALQING_API_KEY"

To erase the transcript, tool calls, userdata, analysis and phone numbers too, delete the call’s content with DELETE /v1/calls/{session_id} (see calls).

Retention

Recordings are kept until your workspace’s retention policy or a person deletes them; the default is unlimited. A purge sets state to expired. recording.expires_at is fixed when the call ends, so changing the policy later does not move a purge already scheduled. See data retention and privacy.

The `recording.ready` webhook

When the audio reaches storage, a recording.ready event fires with a signed url, url_expires_at, the duration and the size. It fires for the audio only, not the screen recording, and its link also expires within the hour. See webhooks.

Calls

The call record, transcript and deleting a call.

Data retention

What is stored, for how long, and what a purge destroys.

Get started

Build

Guides

Playing and downloading

`recording` on a call

`state`

Recording notice

Screen recordings

Deleting

Retention

The `recording.ready` webhook

Next

Calls

Data retention

​Playing and downloading

​recording on a call

​state

​Recording notice

​Screen recordings

​Deleting

​Retention

​The recording.ready webhook

​Next

Calls

Data retention

Playing and downloading

`recording` on a call

`state`

Recording notice

Screen recordings

Deleting

Retention

The `recording.ready` webhook

Next