The recording API: starting and stopping a recording mid-transfer

Recording does not have to be all or nothing for a whole call. The recording function in the agent API lets an outside program start and stop a recording on demand, which is exactly what you need when a transfer changes who is on the line. You can stop recording before a sensitive moment and start it again once the customer reaches a closer, all from a single HTTP call.

The four values

The function takes a value that says what to do. START sends a start-recording signal to the agent screen, and you can have more than one recording running at the same time. STOP sends a stop signal that ends every active recording on that agent screen at once, so it is a clean sweep rather than a single-target stop. STATUS returns the current Call recording details and agent session information, including the recording ID, filename, server, and start time, so your program can confirm what is actually being captured.

All of this runs through the agent-side API (application programming interface), naming the agent_user whose session you are recording. The agent must be logged in; if they are not, the call returns an error instead of a recording.

Tagging the file with stage

The optional stage field appends a value to the recording filename, up to 14 characters, and anything longer gets truncated. It only works with START. This is how you label a mid-call segment so it is obvious later: pass stage as _MIDCALL and the file carries that tag. When you start a fresh recording after a handoff, a stage tag makes the transfer segment easy to find without digging through timestamps. Keep the tags short and consistent across your scripts, since a predictable suffix is what lets a later search or report group the right segments together.

sequenceDiagram
  participant P as External program
  participant A as Agent screen
  participant S as Server
  P->>A: recording START stage MIDCALL
  A->>S: begin capture
  P->>A: recording STATUS
  A-->>P: recording active with filename
  P->>A: recording STOP
  A->>S: end all active recordings
  S-->>P: recording function sent

Why this matters during a transfer

The on-demand nature is the whole point. With On-demand recording driven from the API, your CRM can stop capture during a payment step to keep card data out of the audio, then start a new segment once the customer is handed to a Closer. Because STOP ends all active recordings on the screen, you do not have to track each one individually to be sure capture has actually stopped, which is the safer default when compliance is on the line.

Keep in mind that STOP is a screen-wide sweep. If you intend to keep one recording running while ending another, START-ing several and then STOP-ping is not the tool; STOP clears them all. Plan your start and stop points around that, and lean on STATUS to verify the actual state of the Agent session before you assume anything. For how recording behaves when an agent leaves a 3-way, see starting a recording on leave 3-way, and the wider handoff context lives in our transfers and closers guide.

Recording control that you can script per segment is the difference between a clean compliance story and a pile of audio you have to redact later. See our pricing for a dialer where the recording API is ready to wire into your workflow.