Scenario Actions

Scenario actions define what happens during a call, beyond the basic dial-hold-hangup lifecycle. They let you simulate real-world mid-call operations like putting calls on hold, resuming, activating deferred media tracks, and changing media parameters -- all triggered by time or by events from the remote endpoint.

Overview

Each group can have up to 30 scenario actions. Actions are displayed as When/Then cards in the test creation form:

• When (left, blue): The trigger condition -- when should this action fire?
• Then (right, green): The action to execute -- what should happen?

Actions are connected by vertical lines to show sequence. When multiple time-based actions are defined, they execute in chronological order.

Trigger Types

At Time

The simplest trigger. The action fires at a specific number of seconds after call establishment.

Example: Hold the call at 10 seconds, resume at 20 seconds.

On Event

The action fires when a specific event is received from the remote endpoint. This is reactive -- the endpoint waits for the event and then acts.

Available events:

On Event + Delay

A composite trigger that combines event detection with a time delay. The action fires a specified number of seconds after the event is detected.

Example: 5 seconds after receiving a hold from the remote, negotiate a video track.

Action Types

Hold

Places the call on hold by sending a SIP re-INVITE with the media direction changed.

Parameters:

What happens technically:

1. A re-INVITE is sent with the SDP a= attribute modified
2. RTP sending is muted (packets stopped, but GStreamer pipeline continues running internally)
3. Hold count and duration metrics are tracked in the call timing table
4. The call state machine transitions to the held state

Resume

Resumes a previously held call by sending a SIP re-INVITE restoring the original media direction (a=sendrecv).

No additional parameters. Resume always restores full bidirectional media flow.

Start Sending Track

Activates a deferred track that was negotiated at call start but not sending (configured with "Negotiate at start" enabled and "Start sending at establishment" disabled).

Parameters:

What happens technically:

1. A re-INVITE (or UPDATE if supported) changes the track direction from a=inactive to a=sendrecv
2. The media pipeline is rebuilt to include the newly active track
3. RTP keepalive for that track stops and real media begins flowing
4. The deferred_tracks_activated metric is incremented

See Advanced Track Settings for configuring deferred tracks.

Negotiate Track

Activates a track that was not negotiated at call start (configured with "Negotiate at start" disabled, shown as port 0 in the initial SDP).

Parameters:

What happens technically:

1. A re-INVITE replaces port 0 with a real allocated port for this track
2. The remote endpoint negotiates codecs and ports for the new media line
3. The media pipeline is rebuilt to include the newly negotiated track
4. Ports are allocated and media begins flowing

Update Media

Changes media parameters (codec, bitrate) for an existing active track mid-call.

Parameters:

What happens technically:

1. Prefers SIP UPDATE (RFC 3311) if the remote advertised support, otherwise falls back to re-INVITE
2. The SDP is modified with updated codec or bitrate parameters
3. The media pipeline is rebuilt with the new parameters
4. The update_media_count metric is incremented

Send DTMF

Sends a sequence of DTMF digits during the call. Used for IVR navigation, automated menu testing, and tone transmission validation.

Parameters:

What happens technically:

1. For RFC 4733: A GStreamer rtpdtmfsrc element generates telephone-event RTP packets with the correct event code, duration, and end-bit. Packets are merged with the audio RTP stream via a funnel element.
2. For SIP INFO: A SIP INFO request is sent with Content-Type: application/dtmf-relay and body Signal=X\r\nDuration=Y.
3. Each digit in the sequence is sent with the configured inter-digit interval.
4. The dtmf_digits_sent metric is incremented for each digit transmitted.

Conflict Handling (Glare)

When both endpoints try to modify the session simultaneously (e.g., both send re-INVITEs at the same time), a glare condition occurs. The remote responds with 491 Request Pending.

CallMeter handles this automatically:

• The initiating side retries after a random backoff (0-2 seconds for the caller, 2.1-4 seconds for the callee)
• Up to 3 retries are attempted
• If all retries fail, the action is marked as failed and the scenario_actions_failed metric is incremented

Practical Scenarios

Basic Hold/Resume Cycle

Test your PBX's hold music and call recovery:

Reactive Hold Response

When the remote puts you on hold, automatically resume after 5 seconds (tests hold-resume interoperability):

Video Escalation

Start with audio only, activate video mid-call:

1. Configure Video Track 2 with "Start sending at establishment" disabled
2. Add scenario action:

Content Sharing on Hold

Simulate a conferencing system that starts content sharing when put on hold:

1. Configure Video Track 2 with "Negotiate at start" disabled
2. Add scenario action:

Metrics

Scenario actions contribute to several call timing metrics:

These metrics appear in the call timing section of the test results and can be used to verify that your SIP infrastructure handles mid-call operations correctly under load.

IVR Menu Navigation

Test an automated phone menu by sending DTMF digits at timed intervals:

Reactive IVR Chain

React to incoming DTMF tones and respond with digits (simulates two endpoints navigating each other's IVR):

DTMF Reliability Under Load

Send a full keypad sequence to verify DTMF reliability under SIP stress:

Limits

• Maximum 30 scenario actions per group
• Time-based trigger times must be less than the call duration
• Hold/Resume state machine is enforced: no double-hold, no resume without prior hold
• Track-targeting actions must reference valid tracks with the correct deferred settings
• Each event-triggered action fires at most once per call

Next Steps

• Advanced Track Settings -- DSCP marking and deferred negotiation
• Creating a Test -- Full test creation walkthrough
• Groups -- Multi-group test configuration