How to tag a recording mid-call with the stage parameter

When you trigger Call recording through the Agent API, VICIdial normally generates an automatic filename based on date, time, and agent. The stage parameter lets you append a custom suffix at the moment recording starts—so you can tell a compliance segment from a sales pitch just by looking at the filename.

How stage works

The stage parameter is optional. It only works when paired with value=START on the recording function, or with value=BEGIN on the stereo_recording function. It has no effect on STOP, END, or STATUS calls.

VICIdial appends whatever string you pass directly to the recording filename. The value is limited to 14 characters—anything longer is truncated silently. A leading underscore in your stage value is a common convention to visually separate it from the auto-generated filename prefix.

Example calls with stage

Standard recording with a stage suffix:

http://server/agc/api.php?source=test&user=6666&pass=1234&agent_user=1000&function=recording&value=START&stage=_MIDCALL

The SUCCESS response confirms the stage was applied:

SUCCESS: recording function sent - 6666|START_MIDCALL||||192.168.1.5|8600051|PAUSED

Notice the response value reads START_MIDCALL rather than just START—that confirms the suffix was accepted. The same pattern applies to stereo_recording: a BEGIN with stage=_MIDCALL returns BEGIN_MIDCALL in the SUCCESS line.

How stage values appear in filenames

flowchart LR
  A[API call with stage=_PAYMENT] --> B[VICIdial appends suffix]
  B --> C[Base filename generated]
  C --> D[20240610-143022__1000_]
  D --> E[Final filename with stage]
  E --> F[20240610-143022__1000__PAYMENT]

Practical naming conventions

Because stage is limited to 14 characters, keep values short and machine-parseable. Some patterns that work well:

• _CONSENT — marks the segment where the agent reads the compliance disclosure.
• _PAYMENT — marks a segment that should be flagged for PCI review.
• _ESCALATION — marks calls that escalated mid-conversation for QA sampling.

**Heads up:** The 14-character limit is enforced silently. If you pass _ESCALATION_QA (15 characters), VICIdial will truncate it to _ESCALATION_Q without warning. Always verify the actual filename in the STATUS response or in the Recording retention log after the call.

Stage versus campaign-level filename variables

VICIdial also supports campaign-level filename variables that can embed lead data, campaign IDs, or phone numbers into recording names automatically. The stage parameter is different—it is per-call and per-segment, controlled at the moment of the API call. Use campaign variables for consistent naming across all recordings; use stage when you need runtime context that the campaign template cannot know in advance.

For the broader picture of how recording filenames are structured in VICIdial, see VICIdial call recording explained. To see campaign-level filename variables in action, check out VICIdial campaign recording filename variables.

Want a managed setup where the Agent API is ready to use from day one? See VICIfast pricing.