Chapter 32: Channel Variables Catalog

Channel variables are per-channel named string values that FreeSWITCH maintains for the lifetime of a call leg. They are referenced in dialplan expressions and application arguments as ${variable_name}. Variables are set by the user directory when a caller authenticates, by dialplan actions such as set and export, by endpoint modules such as mod_sofia, and by core applications at runtime. A variable set with set applies only to the current leg; export additionally propagates the variable to any B-leg created by a subsequent bridge.

Call Control and Routing

These variables govern what FreeSWITCH does before, during, and after a bridge.

Variable	Purpose
continue_on_fail	Controls dialplan continuation when a bridge attempt fails. Set to true to continue processing regardless of failure cause. Set to a comma-separated list of Q.850 cause names (e.g., USER_BUSY,NO_ANSWER) or numeric codes (e.g., 17,18) to continue only on those specific causes. Default: false.
hangup_after_bridge	When true, the A-leg is terminated as soon as the B-leg hangs up. When false (default), dialplan execution continues after the bridge returns. Evaluated after park_after_bridge and transfer_after_bridge.
park_after_bridge	When true, the call is parked after the bridge returns instead of continuing dialplan execution. Evaluated before hangup_after_bridge.
park_after_early_bridge	When true, the call is parked after an early-media bridge terminates, before the B-leg answers. Corresponds to SWITCH_PARK_AFTER_EARLY_BRIDGE_VARIABLE in switch_types.h.
transfer_after_bridge	Specifies a dialplan transfer destination (extension [dialplan [context]]) to execute after a bridge completes.
transfer_after_early_bridge	Specifies a dialplan transfer destination to execute when an early-media bridge terminates before the B-leg answers. Corresponds to SWITCH_TRANSFER_AFTER_EARLY_BRIDGE_VARIABLE.
call_timeout	Maximum number of seconds to wait for the B-leg to answer when using the bridge application. Applies to the A-leg and governs all bridges on that channel. Has no effect once early media is received unless ignore_early_media=true is also set. Default: 60.
park_timeout	When set on a parked channel, the call is disconnected after this many seconds. Accepts an integer or the form seconds:HANGUP_CAUSE_NAME. If not set the parked call is held until explicitly transferred. Example: park_timeout=30:MEDIA_TIMEOUT.
fail_on_single_reject	Applies when the , (AND) operator is used in a bridge dial string. When true, a single rejection from any listed destination terminates the entire bridge attempt immediately. Can be set to a specific cause name (USER_BUSY) to fail only on that cause, or a negated cause (!NORMAL_CLEARING) to fail on all other causes. Accepts a custom delimiter list: ^^:CAUSE1:CAUSE2. Default: false.
failure_causes	Comma-separated list of Q.850 cause names. When the bridge returns with one of these causes, the channel is considered failed and transfer_on_fail is invoked. Operates as the reverse of continue_on_fail. Defined in switch_channel.c.
transfer_on_fail	Dialplan transfer destination to execute when a bridge fails. Used in conjunction with failure_causes. Format: extension [dialplan [context]]. Defined in switch_channel.c.
bridge_early_media	When true, live audio received as early media from the B-leg is buffered and played back to the A-leg as ringback. Increases resource usage relative to the default (false). Useful with loopback channels or multi-destination originations where network-generated tones must be relayed accurately.
ignore_early_media	Controls whether early media (SIP 183 with SDP) causes the bridge to "connect" immediately. true ignores early media and keeps ringing until the B-leg answers. ring_ready behaves like true but also sends a SIP 180 to the A-leg when the first 183 is received. Default: false.
ringback	Audio to play to the A-leg while waiting for the B-leg to answer (early media phase). Accepts a full filesystem path to an audio file or a TGML tone string (e.g., %(2000,4000,440,480)). Takes effect only when there is no early media from the B-leg unless ignore_early_media is also set.
transfer_ringback	Audio to play to the A-leg during a transfer when the channel is already answered. Accepts the same formats as ringback.
transfer_fallback_extension	Dialplan extension to transfer a call to when a transfer attempt fails. Set this before executing the transfer.
hold_music	Audio stream to play when a channel is placed on hold. Accepts a local stream reference (e.g., local_stream://moh) or a full audio file path.
temp_hold_music	Overrides hold_music for a single hold operation. Cleared automatically after the hold ends. Corresponds to SWITCH_TEMP_HOLD_MUSIC_VARIABLE in switch_types.h.
instant_ringback	When true, ringback defined by ringback is generated immediately without waiting for a ringing indication from the B-leg. Default: false.
max_forwards	Sets the SIP Max-Forwards header value for outbound requests on this channel. Corresponds to SWITCH_MAX_FORWARDS_VARIABLE.
max_session_transfers	Maximum number of times a channel may be transferred. When the count is exceeded, further transfer attempts are rejected. Corresponds to SWITCH_MAX_SESSION_TRANSFERS_VARIABLE in switch_types.h.
export_vars	Comma-separated list of variable names to automatically export to any B-leg created by a bridge. Equivalent to calling export on each listed variable. Corresponds to SWITCH_EXPORT_VARS_VARIABLE.
bridge_export_vars	Like export_vars but variables are exported only to the B-leg for the duration of the bridge, not permanently. Corresponds to SWITCH_BRIDGE_EXPORT_VARS_VARIABLE.
send_silence_when_idle	Integer. When set to a negative value (typically -1), FreeSWITCH sends comfort-noise silence packets to the channel when there is no audio to send. Prevents RTP timeouts on devices that require a continuous media stream. Read by switch_ivr.c and switch_rtp.c. Corresponds to SWITCH_SEND_SILENCE_WHEN_IDLE_VARIABLE.
playback_terminators	String of DTMF digits that cause a playing audio file to stop immediately. Example: 1234567890*#. Set to none to disable termination. Applies to playback, read, play_and_get_digits, and similar applications. Corresponds to SWITCH_PLAYBACK_TERMINATORS_VARIABLE.
ignore_display_updates	When true, incoming SIP UPDATE or re-INVITE requests that only modify display name are silently ignored and not relayed to the bridged party. Corresponds to SWITCH_IGNORE_DISPLAY_UPDATES_VARIABLE.
enable_heartbeat_events	Integer seconds. When set, FreeSWITCH fires a SESSION_HEARTBEAT event on this channel at the specified interval. Useful for monitoring long-duration calls. Corresponds to SWITCH_ENABLE_HEARTBEAT_EVENTS_VARIABLE.

---

Routing and Recovery Controls

These variables steer dialplan transfer/redirect behavior and call recovery.

Variable	Purpose
force_transfer_context	Forces the dialplan context used by the transfer application when no context is given in the transfer arguments.
force_transfer_dialplan	Forces the dialplan engine used by the transfer application when none is given in the transfer arguments.
inbound_dialplan	Overrides the dialplan engine used for inbound calls on the endpoint.
group_context	Dialplan context applied to channels created by the group dialer.
inline_destination	Destination used for inline dialplan execution on a redirected or hung-up leg.
disable_q850_reason	When true, suppresses the Q.850 Reason header in SIP hangup signaling.
ignore_completed_elsewhere	When true, ignores the SIP "completed elsewhere" indication on CANCEL so the call is not flagged as answered elsewhere.
enum_nameserver	DNS nameserver(s) used for ENUM lookups by mod_enum.
recovery_profile_name	Overrides the SIP profile name stored and used for call recovery.
secondary_recovery_module	Name of a secondary endpoint module consulted when recovering a call.

Bridge and Transfer

These variables are set by the core when a bridge or transfer is active or has just completed. Most are read-only at runtime; a few are also operator-settable to influence behavior.

Variable	Purpose
bridge_channel	Set by the core on both legs when a bridge is established. Contains the channel name (e.g., sofia/internal/1001@10.0.0.1) of the remote leg. Read-only; set in switch_ivr_bridge.c. Corresponds to SWITCH_BRIDGE_CHANNEL_VARIABLE.
bridge_uuid	Set by the core on both legs when a bridge is established. Contains the UUID of the remote leg. Cleared when the bridge ends. Read-only. Corresponds to SWITCH_BRIDGE_UUID_VARIABLE.
bridge_to	Set to the channel name of the most recently bridged B-leg after the bridge completes. Read-only; corresponds to SWITCH_BRIDGE_VARIABLE (bridge_to) in switch_types.h.
last_bridge_to	Set to the channel name of the previously bridged B-leg when a new bridge supersedes it. Useful for inspecting bridge history after multiple sequential bridges. Read-only; corresponds to SWITCH_LAST_BRIDGE_VARIABLE.
signal_bridge_to	UUID of the channel for a signal-only bridge (used by uuid_bridge). The two legs pass signaling to each other but media is handled independently. Operator-settable before calling signal_bridge. Corresponds to SWITCH_SIGNAL_BRIDGE_VARIABLE.
signal_bond	Set on a channel to the UUID of its signal-bonded peer after a signal bridge is established. Read-only; set by switch_ivr_bridge.c. Corresponds to SWITCH_SIGNAL_BOND_VARIABLE.
originate_signal_bond	Set on the A-leg channel immediately after origination to the UUID of the newly created B-leg. Distinct from signal_bond in that it records the origination relationship rather than a subsequent signal bridge. Read-only. Corresponds to SWITCH_ORIGINATE_SIGNAL_BOND_VARIABLE.
originator	UUID of the channel that originated this leg. Set on the B-leg by the originate engine. Read-only; corresponds to SWITCH_ORIGINATOR_VARIABLE.
originator_codec	Codec string of the A-leg at the time of origination. Set on the B-leg by the core (switch_core_session.c) so the B-leg can offer a compatible codec list. Read-only; corresponds to SWITCH_ORIGINATOR_CODEC_VARIABLE.
originator_video_codec	Video codec string of the A-leg at the time of origination. Set on the B-leg alongside originator_codec. Read-only; corresponds to SWITCH_ORIGINATOR_VIDEO_CODEC_VARIABLE.
exec_after_bridge_app	Dialplan application name to execute on this channel immediately after the bridge returns. The application runs before dialplan processing resumes. Corresponds to SWITCH_EXEC_AFTER_BRIDGE_APP_VARIABLE.
exec_after_bridge_arg	Argument string for the application named in exec_after_bridge_app. Corresponds to SWITCH_EXEC_AFTER_BRIDGE_ARG_VARIABLE.
att_xfer_result	Set by the att_xfer (attended transfer) application to success or failure after the transfer completes. Read-only; set in mod_dptools.c. Corresponds to SWITCH_ATT_XFER_RESULT_VARIABLE.
transfer_history	Multi-value variable. Each transfer appends a record in the format epoch:uuid:type:destination. Read by CDR modules to reconstruct the transfer chain. Read-only; set by switch_ivr.c and mod_sofia. Corresponds to SWITCH_TRANSFER_HISTORY_VARIABLE.
transfer_source	Identifies the source of the most recent transfer on this channel. Format matches the entries in transfer_history. Read-only; set alongside transfer_history. Corresponds to SWITCH_TRANSFER_SOURCE_VARIABLE.
holding_uuid	UUID of the channel currently on hold associated with this channel. Set by mod_sofia during attended transfer scenarios. The originate engine reads and clears this variable when bridging back. Corresponds to SWITCH_HOLDING_UUID_VARIABLE.
soft_holding_uuid	UUID of a channel placed in a "soft" hold during a three-way call or similar scenario. Cleared when the three-way terminates and the held party is bridged back. Corresponds to SWITCH_SOFT_HOLDING_UUID_VARIABLE.
endpoint_disposition	Describes the SIP negotiation outcome set by mod_sofia and the core state machine. Common values: RECEIVED, EARLY MEDIA, ANSWER, PROXY MEDIA, DELAYED NEGOTIATION, CODEC NEGOTIATION ERROR, NO CODECS, REDIRECT_ERROR, ATTENDED_TRANSFER. Read-only. Corresponds to SWITCH_ENDPOINT_DISPOSITION_VARIABLE.
channel_name	The full channel name string (e.g., sofia/internal/1001@example.com). Set by the core when the channel is created. Read-only. Corresponds to SWITCH_CHANNEL_NAME_VARIABLE.
audio_spool_path	Directory path where audio files are spooled before being written to their final location. When set, the core writes audio to this path first and then moves it. Corresponds to SWITCH_AUDIO_SPOOL_PATH_VARIABLE.

---

Bridge Behavior and Pre-Execution

These variables tune the bridge and uuid_bridge applications, attended/blind transfer, and the intercept application.

Variable	Purpose
bridge_answer_timeout	Seconds to wait for the A-leg to answer during a bridge before bailing out. Integer seconds.
bridge_terminate_key	DTMF digit that, when received, terminates the bridge. Single-key string.
bridge_filter_dtmf	When true, DTMF is filtered (not passed) across the bridge.
bridge_generate_comfort_noise	Generates comfort-noise toward the far leg during the bridge. true uses level 1400, or supply an integer level (values below -1 disable).
continue_on_answer_timeout	When true, the bridge continues rather than failing when the answer timeout is reached.
answer_delay	Milliseconds to sleep immediately after a channel is answered. Integer ms; ignored in proxy/text mode.
answer_flags	Default flags for the answer application when called with no arguments. Substring-matched values is_conference, decode_video, and debug_video set the corresponding channel flags.
bridge_pre_execute_app	Dialplan application executed on the A-leg before the bridge loop begins.
bridge_pre_execute_data	Argument data passed to bridge_pre_execute_app.
bridge_pre_execute_aleg_app	Application executed on the caller (A) leg just before a multi-threaded bridge.
bridge_pre_execute_aleg_data	Argument data for bridge_pre_execute_aleg_app.
bridge_pre_execute_bleg_app	Application executed on the callee (B) leg just before a multi-threaded bridge.
bridge_pre_execute_bleg_data	Argument data for bridge_pre_execute_bleg_app.
campon	When true, enables camp-on (retry) behavior on bridge.
attended_transfer_no_copy	Comma-separated list of variable names NOT to copy across legs during an attended transfer.
blind_transfer_uuid	UUID of the leg to hang up or transfer when performing a blind transfer.
confirm_blind_transfer	When true, requires confirmation handling for blind transfers.
deny_refer_requests	When true on a bridged leg, rejects incoming SIP REFER (transfer) requests.
hold_hangup_xfer_exten	When a held leg's bridge ends, transfer the other leg to this extension instead of hanging it up.
xfer_uuids	Supplies the pair of leg UUIDs for an att_xfer operation.
intercept_pre_bond	When true, allows intercept to grab a leg that is in a pre-bond state.
intercept_unanswered_only	When true, restricts intercept to unanswered legs only.
intercept_unbridged_only	When true, restricts intercept to unbridged legs only.
uuid_bridge_continue_on_cancel	When true, a uuid_bridge parks the surviving leg rather than hanging up when a leg cancels.
uuid_bridge_park_on_cancel	When true, parks the surviving leg on a uuid_bridge cancel.

Origination

These variables are set inside the {} global block or [] per-leg block of an originate command or bridge dial string. They control how outbound legs are established.

Variable	Purpose
originate_timeout	Total wall-clock seconds to wait across all legs before the originate fails. When using the | (OR) operator, applies to the entire sequence unless originate_continue_on_timeout is set. Default: 60.
originate_continue_on_timeout	When true and the | (OR) operator is used, the originate continues to the next destination after originate_timeout expires on the current destination instead of failing. Default: false.
originate_retries	Number of times to retry the entire originate dial string on failure. Valid range: 1 to 100. Works only when originate_retry_sleep_ms is also set or the value is 100 or fewer.
originate_retry_sleep_ms	Milliseconds to wait between originate retry attempts. Valid range: 500 to 60000.
leg_timeout	Per-leg answer timeout in seconds. Set in the [] per-leg block. Overrides call_timeout for that leg. Cannot be used in the global {} block; use originate_timeout there instead.
leg_progress_timeout	Per-leg timeout in seconds for receiving any early media or ring indication. If no media is received within this window the leg is abandoned. Set in the [] per-leg block.
leg_delay_start	Seconds to delay before initiating this leg. Set in the [] per-leg block. The leg_timeout timer does not start until after the delay expires.
group_confirm_key	DTMF digit the called party must press to accept the call. Used for answer confirmation in parallel or sequential ring scenarios. The call is not bridged until the key is received.
group_confirm_file	Audio file to play to the B-leg while waiting for the confirmation key. Played in a loop until the key is pressed or a timeout occurs.
group_confirm_error_file	Audio file to play to the B-leg when a wrong DTMF key is received.
group_confirm_timeout	Seconds to wait for the confirmation key. When set, takes precedence over group_confirm_cancel_timeout.
group_confirm_cancel_timeout	When true, cancels the confirmation timeout so the B-leg is held indefinitely until a key is received. Has no effect if group_confirm_timeout is also set.
group_confirm_read_timeout	Milliseconds of silence after a key press before accepting the input.
fail_on_single_reject	See Call Control and Routing section above.
originated_legs	Set on the A-leg after origination completes. Contains a pipe-delimited list of uuid:disposition:cause for each B-leg that was attempted. Populated by the originate engine in switch_ivr_originate.c. Read-only after origination.
originate_disposition	Set on the caller channel to indicate the outcome of an originate. Possible values include success, failure, call accepted, and Q.850 cause name strings. Read-only; set by originate engine.
originating_leg_uuid	Set on a B-leg channel to record the UUID of the A-leg that originated it. Read-only; set by originate engine.
sip_invite_to_uri	When set before a bridge, overrides the To URI placed in the outbound SIP INVITE. Read by mod_sofia in sofia_glue.c.
sip_invite_from_uri	When set before a bridge, overrides the From URI placed in the outbound SIP INVITE. Read by mod_sofia in sofia_glue.c.
sip_invite_req_uri	When set before a bridge, overrides the Request-URI of the outbound SIP INVITE. Read by mod_sofia in sofia_glue.c.
sip_invite_domain	Overrides the domain portion of the INVITE. Set automatically from the gateway from_domain if not already set. Read by mod_sofia in mod_sofia.c.

---

Originated-Leg Controls

These variables are set on the A-leg (or in the dial string) to shape the outbound leg created by bridge/originate.

Variable	Purpose
origination_uuid	Forces the originated session to use this UUID instead of an auto-generated one.
origination_channel_name	Sets the display name of the originated peer channel.
origination_callee_id_name	Sets the originated peer channel's callee_id_name.
origination_callee_id_number	Sets the originated peer channel's callee_id_number.
origination_audio_mode	Overrides the outbound SDP audio direction for the originated leg: sendrecv, sendonly, recvonly, or inactive (consumed once, then cleared).
origination_nested_vars	When true, allows nested/recursive ${var} expansion during origination by disabling variable-existence checking.
call_uuid	Logical call-group UUID. Used as the channel's Channel-Call-UUID in events and propagated from caller to originated peer legs so multiple legs share one call UUID.
inherit_codec	When true, an outbound/B-leg inherits the codec of the originating leg.
leg_required	When true on an originated leg, marks that leg as required in the dial.
preserve_originated_vars	When false, originated-leg variables are not preserved onto the caller leg.
push_channel_name	When true, derives and pushes the B-leg channel name (X-FS-Channel-Name) from the caller leg.

Caller Identity

FreeSWITCH maintains several caller-ID variables with distinct scopes and precedence.

Variable	Purpose
caller_id_name	The display name presented by the inbound call. Set by the endpoint module from the incoming SIP From header or equivalent. Effectively read-only in the dialplan; modify presentation using effective_caller_id_name.
caller_id_number	The calling number presented by the inbound call. Set by the endpoint module from the incoming SIP From header or equivalent. Effectively read-only in the dialplan; modify presentation using effective_caller_id_number.
effective_caller_id_name	Overrides the caller ID name presented to downstream parties. Automatically exported to the B-leg. Must be set before calling bridge; it is not valid in an origination string. To remove an override, set to _undef_.
effective_caller_id_number	Overrides the caller ID number presented to downstream parties. Automatically exported to the B-leg. Must be set before calling bridge; it is not valid in an origination string.
outbound_caller_id_name	Default caller ID name used for user-directory-driven outbound calls. Typically set in the directory entry and referenced in conference and gateway configurations.
outbound_caller_id_number	Default caller ID number used for user-directory-driven outbound calls. Typically set in the directory entry.
origination_caller_id_name	Caller ID name to use when originating a new call (A-leg). Specified inside the {} origination variable block in an originate command or bridge dial string. Takes precedence over effective_caller_id_name at origination time.
origination_caller_id_number	Caller ID number to use when originating a new call (A-leg). Specified inside the {} origination variable block.

---

Effective and Initial Callee Identity

These override the caller/callee identity presented in outbound signaling.

Variable	Purpose
effective_callee_id_name	Overrides the callee ID name presented in outbound signaling.
effective_callee_id_number	Overrides the callee ID number presented in outbound signaling.
initial_callee_id_name	Sets the initial (pre-update) callee ID name for outbound signaling.
initial_callee_id_number	Sets the initial (pre-update) callee ID number for outbound signaling.
effective_ani	Overrides the ANI used for the call's effective caller profile.
effective_aniii	Overrides the ANI II digits for the call's effective caller profile.

SIP

These variables expose SIP message fields and control SIP header injection. They are specific to channels handled by mod_sofia.

Inbound Fields (set by mod_sofia on call arrival)

Variable	Purpose
sip_from_user	The user part of the SIP From URI of the incoming request.
sip_from_host	The host part of the SIP From URI of the incoming request.
sip_from_uri	The full From URI (user@host) of the incoming request.
sip_from_display	The display name from the SIP From header (quoted string), if present. Set in sofia.c.
sip_to_user	The user part of the SIP To URI of the incoming request.
sip_to_host	The host part of the SIP To URI of the incoming request.
sip_to_uri	The full To URI (user@host) of the incoming request.
sip_req_uri	The full Request-URI of the incoming SIP INVITE. Set by sofia_glue.c.
sip_contact_user	The user part of the SIP Contact URI from the incoming request.
sip_contact_host	The host part of the SIP Contact URI from the incoming request.
sip_call_id	The SIP Call-ID header value of the dialog. Set on arrival and updated on reINVITE.
sip_user_agent	The User-Agent or Server header string from the remote SIP party.
sip_network_ip	IP address of the network interface on which the SIP message arrived. Set by mod_sofia.
sip_received_ip	Source IP address from which the SIP request was received. May differ from sip_network_ip when NAT is involved.
sip_via_host	Host portion of the topmost Via header in the incoming SIP request.
sip_via_port	Port from the topmost Via header in the incoming SIP request.
sip_via_rport	rport parameter from the topmost Via header, if present.
sip_via_protocol	Transport protocol from the topmost Via header (e.g., UDP, TCP, TLS).
sip_cid_type	The caller-ID presentation type derived from the inbound identity headers. Set by mod_sofia in sofia.c to rpid when a Remote-Party-ID header is present, or pid when a P-Asserted-Identity or P-Preferred-Identity header is present.

Authentication Fields

Variable	Purpose
sip_auth_username	The username credential presented during SIP digest authentication. Populated by mod_sofia and available in the directory auth event.
sip_auth_password	The password used during SIP digest authentication. Available during directory lookup for authenticating registrations and calls.
sip_auth_realm	The digest realm from the SIP authentication challenge. Populated by mod_sofia.

Redirect Handling

Variable	Purpose
outbound_redirect_fatal	When true, a SIP 3xx redirect response causes the bridge to fail immediately instead of following the redirect. Read by mod_sofia in sofia.c.
sip_redirect_profile	Sofia profile name to use when following a 3xx redirect. Defaults to the current profile name.
sip_redirect_context	Dialplan context to use when routing a redirected call. Defaults to redirected.
sip_redirect_dialplan	Dialplan module to use when routing a redirected call. Defaults to XML.
sip_redirect_fork	When true, a 3xx redirect with multiple Contact headers causes FreeSWITCH to originate all contacts simultaneously rather than sequentially.
sip_redirected_to	Set by mod_sofia to the full Contact URI that was selected when following a 3xx redirect. Read-only; set after redirect processing.
sip_contact_params	Extra parameters appended (after a ;) to the outbound Contact URI built by mod_sofia when routing an inbound or redirected call. Read by sofia_glue.c.

Custom Headers

Variable	Purpose
sip_h_X-Header-Name	Prefix pattern for injecting or reading arbitrary SIP headers. Any channel variable whose name begins with sip_h_ causes mod_sofia to include the corresponding header (with the sip_h_ prefix stripped) in outbound SIP messages. Incoming custom headers are also stored using this prefix. Example: setting sip_h_X-Account-Code=1234 adds X-Account-Code: 1234 to the outbound INVITE.

SIP Variable Conventions

mod_sofia exposes all incoming SIP headers as channel variables using the prefix sip_h_. For standard headers this means sip_h_Subject, sip_h_P-Asserted-Identity, and so on. For outbound calls, setting a channel variable with the sip_h_ prefix causes mod_sofia to inject the corresponding header into the outgoing INVITE or other SIP message (the prefix is stripped to form the header name). Custom extension headers follow the same convention: sip_h_X-My-Header=value produces X-My-Header: value in the INVITE.

In addition to the raw sip_h_ map, mod_sofia parses a number of frequently used headers into dedicated variables at call arrival:

• sip_from_user, sip_from_host, sip_from_uri, sip_from_display
• sip_to_user, sip_to_host, sip_to_uri, sip_req_uri
• sip_contact_user, sip_contact_host
• sip_call_id, sip_user_agent
• sip_via_host, sip_via_port, sip_via_rport, sip_via_protocol
• sip_network_ip, sip_received_ip

These parsed variables are convenient aliases; the raw header is still accessible via the sip_h_ prefix if needed.

Presence

Variable	Purpose
presence_id	SIP URI identifying this channel for presence subscription purposes. When set, mod_sofia uses this value to generate NOTIFY events for subscribed watchers. Example: 1000@example.com.
presence_data	Arbitrary string attached to presence state notifications. Passed through to NOTIFY event bodies.

---

Outbound Header Control

Set on the originating leg, these shape the headers and routing of the outbound INVITE generated by mod_sofia.

Variable	Purpose
sip_force_full_from	Forces the From header of the outbound INVITE to this full value.
sip_force_full_to	Forces the To header of the outbound INVITE to this full value.
sip_invite_from_params	Extra parameters appended to the From header of the outbound INVITE.
sip_invite_to_params	Extra parameters appended to the To header of the outbound INVITE.
sip_invite_params	Extra parameters appended to the request-URI of the outbound INVITE.
sip_invite_contact_params	Extra parameters appended to the Contact header of the outbound INVITE.
sip_invite_pid_params	Extra parameters appended to the P-Asserted/P-Preferred-Identity header of the outbound INVITE.
sip_invite_tel_params	Extra tel-URI parameters appended to the outbound INVITE.
sip_invite_cseq	Forces a specific numeric CSeq value on the outbound INVITE.
sip_invite_route_uri	Sets the Route header URI for the outbound INVITE.
sip_route_uri	Overrides the outbound proxy/Route URI used to send the INVITE (and subsequent requests), bypassing normal routing.
sip_contact_uri	Overrides the Contact URI used as the redirect/target for inbound legs.
sip_content_encoding	Sets the Content-Encoding header on the outbound INVITE's SDP body.
sip_h_date	Supplies an explicit Date header for the outbound INVITE.
sip_h_identity	Supplies an explicit STIR/SHAKEN Identity (PASSporT) header on the outbound INVITE.
sip_allow	Value used to build the Allow header on UPDATE-based callee-ID/display updates; if it contains UPDATE, UPDATE is treated as allowed.
sip_transport	Forces the SIP transport (udp/tcp/tls/…) for the outbound request when not set in the URI.
sip_require_timer	When false, disables advertising/requiring the SIP session timer on the outbound INVITE.
sip_cid_in_1xx	When false, disables sending callee ID in 1xx provisional responses even if the profile enables it.
sip_cid_suppress_privacy_none	When true, suppresses the explicit Privacy: none indication that FreeSWITCH otherwise adds.
sip_reason	Overrides the SIP Reason header sent on outbound BYE/CANCEL (full Reason-header string), unless disable_q850_reason suppresses it.

Behavior Controls

Variable	Purpose
sip_auto_simplify	When true, FreeSWITCH attempts to refer/transfer itself out of the call path (call simplification) on bridge.
sip_copy_custom_headers	When false, stops sip_h_* custom headers from being copied across bridged/transferred legs (default on).
sip_copy_multipart	When false, disables copying the sip_multipart body to the new leg on transfer (default on).
sip_disable_recording	When true, rejects an inbound SIPREC/record request with 488 instead of starting recording.
sip_enable_soa	true/false to enable or disable Sofia SOA (offer/answer) processing for the channel.
sip_force_nat_mode	When true, forces NAT mode on the channel (sets the NAT flag and sip_nat_detected).
sip_sticky_contact	When true, forces "sticky" NAT contact behavior (record-route plus a NAT session timeout).
sip_ignore_reinvites	When true, answers re-INVITEs with 200 OK without renegotiating media.
sip_ignore_remote_cause	When true, uses FreeSWITCH's own hangup cause rather than the bridged leg's SIP cause.
sip_wait_for_aleg_ack	When true, defers sending ACK on the B-leg until the A-leg's ACK arrives (3PCC-style coordination).
sip_watch_headers	Comma-separated list (up to 10) of SIP header names to watch; matching inbound headers are surfaced as events.
sip_gateway_name	Names a configured gateway to associate with the channel at hangup so its failure statistics are updated.
sip_use_gateway	Names a gateway whose credentials are used to answer an auth challenge on the outbound call.
sip_challenge_realm	Sets the realm used when responding to a call with a 401/407 challenge; falls back to sip_to_host.
sip_exclude_contact	Contact value to exclude when the sofia_contact function resolves a registration's contact.
sip_match_user_agent	User-Agent substring to match when sofia_contact resolves a registration's contact.
sip_refer_reply	The sipfrag reply string returned to a REFER before the transferred leg is hung up.
sip_invite_failure_status	Custom SIP status used in the sipfrag of a blind-transfer-failure NOTIFY.
sip_blind_transfer_event	The SIP Event header value used in the sipfrag NOTIFY that completes a blind transfer.
sip_call_tls_orq_connect_timeout	Numeric TLS outgoing-request connect timeout for the outbound INVITE (when supported by the linked sofia-sip).
sip_603plus_passthrough	When true, restores the 603+ Reason (from sip_603plus_reason) on outbound decline even when disable_q850_reason would suppress it.
sip_603plus_reason	The Reason-header string used with sip_603plus_passthrough on a 603 response.

STIR/SHAKEN

Variable	Purpose
sip_stir_shaken_attest	Attestation level (A/B/C) that triggers generation of a STIR/SHAKEN Identity (PASSporT) header on the outbound INVITE.
sip_stir_shaken_vs_hangup_on_fail	When true, the inbound verification service hangs up the call on missing/invalid Identity instead of only setting verstat.
sip_stir_shaken_vs_max_age	Maximum allowed PASSporT age in seconds for inbound verification (default 60).
sip_stir_shaken_vs_require_date	When true, requires a valid SIP Date within the freshness window for inbound verification.

Auto-Answer and MSRP

Variable	Purpose
sip_auto_answer	When true on an outbound leg, sends an Event: talk auto-answer NOTIFY on 180/183 (Polycom-style auto-answer).
sip_auto_answer_suppress_notify	When true, suppresses the auto-answer NOTIFY that sip_auto_answer would send.
sip_msrp_file_name	Filename used by MSRP file transfer to name the sent/received file.
sip_msrp_local_file_selector	Local file selector advertised for an MSRP file-transfer offer.
sip_msrp_offer_active	Controls the MSRP setup direction (active offer) in the generated SDP for MSRP.

Media Endpoints and SDP

These variables expose the negotiated media addresses and SDP bodies. They are set by the core media engine (switch_core_media.c) and are read-only during a live call.

Variable	Purpose
local_media_ip	IP address on which FreeSWITCH is listening for inbound RTP audio from the remote party. Set after SDP negotiation. Corresponds to SWITCH_LOCAL_MEDIA_IP_VARIABLE.
local_media_port	UDP port on which FreeSWITCH is listening for inbound RTP audio. Set after SDP negotiation. Corresponds to SWITCH_LOCAL_MEDIA_PORT_VARIABLE.
advertised_media_ip	IP address advertised in the local SDP for audio RTP. May differ from local_media_ip when NAT is in use or an ext-rtp-ip override is configured. Corresponds to SWITCH_ADVERTISED_MEDIA_IP_VARIABLE.
remote_media_ip	IP address of the remote party's audio RTP endpoint, extracted from the received SDP. Read-only. Corresponds to SWITCH_REMOTE_MEDIA_IP_VARIABLE.
remote_media_port	UDP port of the remote party's audio RTP endpoint. Read-only. Corresponds to SWITCH_REMOTE_MEDIA_PORT_VARIABLE.
local_video_ip	IP address on which FreeSWITCH is listening for inbound video RTP. Corresponds to SWITCH_LOCAL_VIDEO_IP_VARIABLE.
local_video_port	UDP port on which FreeSWITCH is listening for inbound video RTP. Corresponds to SWITCH_LOCAL_VIDEO_PORT_VARIABLE.
remote_video_ip	IP address of the remote party's video RTP endpoint. Read-only. Corresponds to SWITCH_REMOTE_VIDEO_IP_VARIABLE.
remote_video_port	UDP port of the remote party's video RTP endpoint. Read-only. Corresponds to SWITCH_REMOTE_VIDEO_PORT_VARIABLE.
local_text_ip	IP address on which FreeSWITCH is listening for inbound text (T.140/RED) RTP. Set for calls involving real-time text. Corresponds to SWITCH_LOCAL_TEXT_IP_VARIABLE.
local_text_port	UDP port on which FreeSWITCH is listening for inbound text RTP. Corresponds to SWITCH_LOCAL_TEXT_PORT_VARIABLE.
switch_r_sdp	The raw SDP body received from the remote party (the offer or answer, depending on call direction). Set by the media engine. Read-only. Corresponds to SWITCH_R_SDP_VARIABLE.
switch_l_sdp	The raw local SDP body that FreeSWITCH generated and sent to the remote party. Set by the media engine. Read-only. Corresponds to SWITCH_L_SDP_VARIABLE.
switch_m_sdp	The SDP body from the B-leg, stored on the A-leg for reference during media negotiation. Also called the "media SDP" or "B SDP". Corresponds to SWITCH_B_SDP_VARIABLE (switch_m_sdp) in switch_types.h.
passthru_ptime_mismatch	When true, allows a bridge to proceed even when the ptime (packetization interval) in the two SDPs does not match, rather than failing or renegotiating. Corresponds to SWITCH_PASSTHRU_PTIME_MISMATCH_VARIABLE.

---

SDP and Negotiation Controls

These influence the generated SDP, codec filtering, and early-media/redirect signaling.

Variable	Purpose
alert_info	Sets the SIP Alert-Info header value on outbound signaling.
early_use_180	When true, sends SIP 180 instead of 183 for early media/ringing.
outbound_redirect_info	Supplies the SIP Diversion/redirect info for outbound calls (presence suppresses the default).
ep_codec_prefer_sdp	When true, prefers the codec ordering from the received SDP over local preference.
filter_codec_string	Codec string used to filter the negotiated/proxied codec list.
sdp_m_per_ptime	Multiplier controlling m=/ptime grouping in the generated SDP.
verbose_sdp	When true, generates more verbose SDP output.
ndlb_sendrecv_in_session	No-default-lazy-behavior flag forcing a=sendrecv at the SDP session level.
exclude_outgoing_extra_header	Regex of sip_h_/extra header names to exclude from outbound SIP requests.
fs_send_unsupported_info	When true, sends SIP INFO even with unsupported content.
fs_send_unsupported_message	When true, sends SIP MESSAGE even with unsupported content.
ignore_sdp_ice	When true, ignores ICE candidates present in the received SDP.
add_ice_candidates	When true, adds ICE candidates to the generated SDP for the session.
disable_udptl_auto_adjust	When true, disables automatic UDPTL (T.38) remote-address auto-adjust.

Media and RTP

These variables control codec selection, RTP security, and media path behavior.

Variable	Purpose
codec_string	Comma-separated list of codec names to offer or accept during negotiation. FreeSWITCH intersects this list with the endpoint's capabilities. Example: PCMU,PCMA,G722. If unset, the profile default applies.
absolute_codec_string	Comma-separated list of codecs to use exactly as specified, with no intersection or modification by FreeSWITCH. Overrides codec_string when set. Useful to force a specific codec regardless of what the remote party offers.
media_mix_inbound_outbound_codecs	Boolean controlling which codecs are offered on the outbound B-leg. By default FreeSWITCH offers the B-leg exactly the codecs that were offered on the inbound A-leg. Set to true to instead offer the A-leg codecs mixed with the configured outbound codec list (the pre-FS-8321 behavior). Mixing can produce large codec lists that exceed the UDP MTU and cause call-setup failures, which is why the unmixed behavior is the default. Read in switch_core_media.c.
bypass_media	When true, RTP media flows directly between the two endpoints (peer-to-peer). FreeSWITCH continues to handle signaling but does not process media packets. Both endpoints must be reachable by each other.
bypass_media_after_bridge	When true, FreeSWITCH switches to bypass media mode after the bridge is established. Corresponds to SWITCH_BYPASS_MEDIA_AFTER_BRIDGE_VARIABLE in switch_types.h.
proxy_media	When true, RTP packets are forwarded through FreeSWITCH without parsing or processing. Lighter than full media handling but heavier than bypass_media. Requires late negotiation to be enabled in the SIP profile.
rtp_secure_media	Controls SRTP negotiation. Accepted values: mandatory (SAVP only), optional (prefer SAVP, accept AVP), forbidden (deny SAVP), default (accept SAVP if offered inbound). Optionally followed by a colon-delimited list of cipher suites (e.g., mandatory:AES_CM_256_HMAC_SHA1_80). The deprecated values true (equivalent to mandatory) and false (equivalent to forbidden) are still accepted.
rtp_secure_media_inbound	Applies rtp_secure_media semantics only to the inbound RTP direction.
rtp_secure_media_outbound	Applies rtp_secure_media semantics only to the outbound RTP direction.
jitterbuffer_msec	Activates the RTP jitter buffer. Format: length:max_length:max_drift, where each value is in milliseconds (numeric) or packet counts (numeric followed by p). Example: 60:200:20 or 2p:25p:4p. Can be set on the B-leg only using export nolocal:jitterbuffer_msec=60.
media_bug_answer_req	When true, media bugs (used by recording and other media-processing applications) are activated only after the channel is answered.

RTP and Media Statistics

FreeSWITCH populates a family of rtp_* channel variables with per-stream statistics during and after a call. These are read-only diagnostics; they cannot be set to influence behavior. Examples include:

• rtp_audio_in_raw_bytes, rtp_audio_in_media_bytes, rtp_audio_in_packet_count, rtp_audio_in_media_packet_count - inbound audio stream counters.
• rtp_audio_out_raw_bytes, rtp_audio_out_media_bytes, rtp_audio_out_packet_count - outbound audio stream counters.
• rtp_audio_in_skip_packet_count, rtp_audio_in_jitter_packet_count, rtp_audio_in_dtmf_packet_count - quality indicators for the inbound stream.
• rtp_use_codec_string - the codec string that was actually selected and in use for RTP, as opposed to what was offered.

These variables are written by switch_rtp.c and switch_core_media.c and are available for CDR templates and post-call reporting via api_hangup_hook or api_reporting_hook.

---

RTP and RTCP Tuning

Set before media is established, these tune RTP/RTCP transport, SSRC, payload types, and bug workarounds.

Variable	Purpose
rtcp_audio_interval_msec	RTCP sender-report interval (ms) for the audio stream; enables RTCP when set.
rtcp_video_interval_msec	RTCP sender-report interval (ms) for the video stream; enables RTCP when set.
rtcp_text_interval_msec	RTCP interval (ms) for the real-time text (T.140) stream.
rtcp_mux	When false, disables RTCP multiplexing on the RTP port (rtcp-mux is otherwise offered).
rtp_assume_rtcp	When true, assumes/auto-detects RTCP for audio and video even when not signaled.
rtp_remote_audio_rtcp_port	Overrides the remote RTCP port for the audio stream.
rtp_remote_video_rtcp_port	Overrides the remote RTCP port for the video stream.
rtp_remote_text_rtcp_port	Overrides the remote RTCP port for the text stream.
rtp_auto_adjust_threshold	Consecutive packets (1–65535) from a new source before RTP auto-adjust re-points the send address.
rtp_autoflush	When true, enables the RTP autoflush flag so buffered inbound audio is flushed.
rtp_autoflush_during_bridge	Overrides whether RTP autoflush is active while bridged.
rtp_rewrite_timestamps	When true, regenerates contiguous outbound RTP timestamps.
rtp_timer_name	Selects the soft-timer used for the RTP session, overriding the profile default.
rtp_use_ssrc	Forces a specific audio RTP SSRC (decimal).
rtp_use_video_ssrc	Forces a specific video RTP SSRC (decimal).
rtp_use_text_ssrc	Forces a specific text RTP SSRC (decimal).
rtp_nack_buffer_size	Video NACK retransmission buffer size in packets (1–499; default 100) when NACK is enabled.
rtp_2833_send_payload	Forces the outbound RFC 2833 (telephone-event) DTMF payload type (must be >64 in the Sofia path).
rtp_2833_recv_payload	Forces the inbound RFC 2833 DTMF payload type (must be >64 in the Sofia path).
rtp_info_when_no_2833	When not false (default true), if no telephone-event is in the SDP, DTMF switches to SIP INFO.
rtp_liberal_dtmf	When true, accepts DTMF more permissively (liberal-DTMF flag).
rtp_manual_rtp_bugs	Manually sets the audio RTP bug-workaround bitmask (bug-name list).
rtp_manual_video_rtp_bugs	Manually sets the video RTP bug-workaround list.
rtp_manual_text_rtp_bugs	Manually sets the text RTP bug-workaround list.

Jitter Buffer and Bridge Timing

Variable	Purpose
rtp_jitter_buffer_during_bridge	When true, keeps the jitter buffer active during a bridge (paused by default).
rtp_notimer_during_bridge	Overrides whether the RTP soft-timer is disabled while bridged.
jb_av_sync_msec	Target audio/video sync offset (ms) for the jitter buffer.
jb_use_timestamps	When true, the jitter buffer orders by RTP timestamps instead of sequence numbers.
jb_video_low_bitrate	Low-bitrate threshold (kbps) governing video jitter-buffer behavior.

Codec, fmtp, and Bandwidth Forcing

Variable	Purpose
rtp_codec_negotiation	Codec-negotiation strategy: generous, greedy, or scrooge (invalid values ignored).
rtp_force_audio_fmtp	Overrides the fmtp attribute emitted for the audio codec in the local SDP.
rtp_force_video_fmtp	Overrides the fmtp attribute emitted for the video codec in the local SDP.
rtp_mirror_fmtp	When true (and no forced fmtp), mirrors the configured video fmtp into the outbound SDP.
rtp_append_audio_sdp	Appends raw text to the generated audio m= section of the local SDP.
rtp_append_video_sdp	Appends raw text to the generated video m= section of the local SDP.
rtp_disable_byteswap	When true, disables automatic L16 byte-swapping on little-endian hosts.
rtp_video_max_bandwidth	Maximum video bandwidth (e.g. 1mb/256kb; default 1mb); falls back to rtp_video_max_bandwidth_out.
rtp_video_max_bandwidth_in	Maximum inbound video bandwidth advertised/applied for the video stream.
rtp_video_max_bandwidth_out	Maximum outbound video bandwidth for the video encoder.

SRTP, DTLS, and Secure Media

Variable	Purpose
rtp_use_dtls	When true, forces DTLS-SRTP on the audio engine even without AVPF.
rtp_dtls_mtu	DTLS handshake MTU in bytes (1 to max; default 1200).
rtp_allow_crypto_in_avp	When true, accepts a=crypto offered under RTP/AVP (instead of RTP/SAVP), contrary to RFC 3711.
srtp_allow_idle_gaps	When true, allows idle/silence gaps in the SRTP stream rather than forcing continuous send.
webrtc_enable_dtls	When explicitly false, disables DTLS for WebRTC media.
uuid_media_secure_media	Secure-media (SRTP) setting applied when re-establishing media via uuid_media.
media_webrtc	When true, treats the media session as WebRTC (enables WebRTC media defaults).
NDLB_support_asterisk_missing_srtp_auth	When true, tolerates Asterisk peers that omit SRTP auth parameters.

Bypass and Proxy Media

Variable	Purpose
bypass_keep_codec	When true, copies the current ep_codec_string to absolute_codec_string on entering bypass/proxy media to preserve the negotiated codec.
bypass_media_resume_on_hold	When true, gates bypass_media_after_hold so bypass-media behavior is re-evaluated on (un)hold.
bypass_media_after_hold	When true (with bypass_media_resume_on_hold), attempts to leave the media path after a hold/unhold.
bypass_media_after_bridge_oldschool	When true, uses the legacy code path for switching to bypass media after a bridge.
bypass_media_sdp_filter	SDP filter expression applied to the bypassed/proxied SDP before it is relayed to the other leg.

Voice Activity, Fax Tone, and Misc Media

Variable	Purpose
rtp_enable_vad_in	When true, enables inbound voice-activity detection.
rtp_enable_vad_out	When true, enables outbound voice-activity detection.
rtp_disable_vad_in	When true, disables inbound voice-activity detection.
rtp_disable_vad_out	When true, disables outbound voice-activity detection.
vad_thresh	VAD energy threshold for the vad detector.
vad_voice_ms	Minimum voice duration (ms) before the VAD detector declares speech.
suppress_cng	When true, suppresses generation/use of comfort noise (CNG).
rtp_disable_hold	When true, disables hold handling (suppresses sendonly/hold toggling) for the channel.
fax_tone_detect_expires	Expiry time (seconds) for inband fax (CNG/CED) tone detection.
fax_tone_detect_sleep	Quiet interval (seconds) between fax tone-detection attempts.
v18_mode	Selects V.18 TDD/text-telephone mode (e.g. 5BIT_45/baudot, 5BIT_50, DTMF, EDT, BELL103/ascii).
core_video_blank_image	Path to an image used as the blank/placeholder video frame.
stream_prebuffer	Prebuffer size (bytes) applied when opening a streaming file for playback.
media_reneg_after_broadcast	Controls media renegotiation after a broadcast (displace) ends.

Recording

These variables control the behavior of the record_session application and the record application. Variable names that are uppercase by convention must be set with the exact case shown.

Variable	Purpose
RECORD_STEREO	When true, records the A-leg audio to the left channel and the B-leg audio to the right channel of a stereo file. Default: false.
RECORD_STEREO_SWAP	When true, reverses the channel assignment of RECORD_STEREO: B-leg goes to the left channel and A-leg to the right.
RECORD_READ_ONLY	When true, only the read (incoming) audio is written to the recording file.
RECORD_WRITE_ONLY	When true, only the write (outgoing) audio is written to the recording file.
record_sample_rate	Integer sample rate (Hz) to use for the recording file. Example: 8000, 16000, 48000.
RECORD_MIN_SEC	Minimum recording duration in seconds. Recordings shorter than this value are deleted after the session ends. Default: 3.
RECORD_HANGUP_ON_ERROR	When true, the call is terminated if the recording file cannot be opened or written.
RECORD_APPEND	When true, audio is appended to an existing recording file rather than overwriting it.
RECORD_BRIDGE_REQ	When true, recording only begins when the channel enters a bridged state.
RECORD_TITLE	ID3-style title tag written into the recording file header where the format supports it (e.g., WAV, OGG).
RECORD_COPYRIGHT	ID3-style copyright tag written into the recording file header.
RECORD_SOFTWARE	ID3-style software tag written into the recording file header.
RECORD_ARTIST	ID3-style artist tag written into the recording file header.
RECORD_COMMENT	ID3-style comment tag written into the recording file header.
RECORD_DATE	ID3-style date tag written into the recording file header.
record_fill_cng	When true, comfort noise is inserted into the recording during periods of silence to prevent the file from containing dead air.
recording_follow_transfer	When true, an active record_session recording continues after the channel is transferred to a new leg, following the call rather than stopping at transfer.
record_post_process_exec_app	Dialplan application to execute after a recording completes. Format: app_name::app_args. Defined in switch_types.h as SWITCH_RECORD_POST_PROCESS_EXEC_APP_VARIABLE.
record_post_process_exec_api	API command to execute after a recording completes. Defined in switch_types.h as SWITCH_RECORD_POST_PROCESS_EXEC_API_VARIABLE.

---

Additional Recording Controls

Variable	Purpose
record_rate	Sample rate (Hz) for the record application's output file.
record_indication	Path to an indication/comfort file played into the recording read stream.
recording_follow_attxfer	When true, an active recording follows the leg through an attended transfer.
flip_record_on_hold	When true, swaps the recording channels when the call is placed on hold.
RECORD_TOGGLE_ON_REPEAT	When true, a repeated record DTMF binding toggles recording instead of restarting it.
native_backup_extension	Fallback file extension for the backup file in native-format playback/record (default wav).
failed_xml_cdr_prefix	Variable-name prefix for XML CDR data attached to failed origination legs.
failed_json_cdr_prefix	Variable-name prefix for JSON CDR data attached to failed origination legs.

Hangup and CDR

These variables are populated at hangup time and are commonly read in CDR templates and post-call dialplan logic.

Variable	Purpose
hangup_cause	Q.850 cause name string for the hangup of this channel (e.g., NORMAL_CLEARING, USER_BUSY). Set by the core state machine at hangup time. Available for CDR processing and in api_hangup_hook logic.
hangup_cause_q850	Numeric Q.850 cause code corresponding to hangup_cause. Set alongside hangup_cause in switch_core_state_machine.c.
bridge_hangup_cause	Q.850 cause name for the last B-leg that was bridged on this channel. Set by the core when a bridge terminates. Useful when continue_on_fail=true and hangup_after_bridge=false: inspect this to determine what caused the B-leg to disconnect before deciding the next dialplan action.
last_bridge_hangup_cause	Set on the A-leg by the core (switch_channel.c) to the cause of the most recently terminated B-leg. Useful after multiple sequential bridge attempts.
proto_specific_hangup_cause	Forces FreeSWITCH to use a specific SIP response code when hanging up, regardless of the Q.850 cause. Format: sip:NNN (e.g., sip:503). Setting this before hangup causes mod_sofia to send the specified code. Can also be read after a failed bridge to inspect the exact SIP response code received from the remote party.
sip_hangup_disposition	Set by mod_sofia to describe how the SIP session was terminated. Possible values: send_bye (FreeSWITCH sent BYE), recv_bye (remote party sent BYE), send_cancel (FreeSWITCH cancelled an unanswered outbound leg), recv_cancel (remote party cancelled), send_refuse (FreeSWITCH rejected with 4xx/5xx), recv_refuse (remote party rejected with 4xx/5xx). Read-only; set at hangup.
process_cdr	Controls CDR generation for this channel. Values: true (default, process CDR), false (suppress CDR), a_only (only generate CDR for the A-leg), b_only (only generate CDR for the B-leg). Unconditionally exported. Corresponds to SWITCH_PROCESS_CDR_VARIABLE.
skip_cdr_causes	Comma-separated list of Q.850 cause names. If the channel hangs up with one of these causes, CDR generation is suppressed. Corresponds to SWITCH_SKIP_CDR_CAUSES_VARIABLE.
force_process_cdr	When true, forces CDR processing even for channels that would normally be excluded (e.g., loopback legs). Corresponds to SWITCH_FORCE_PROCESS_CDR_VARIABLE.
copy_xml_cdr	When true, the A-leg XML CDR is copied to the B-leg at bridge time. Used to associate the CDR data of the originating leg with the bridged leg. Corresponds to SWITCH_COPY_XML_CDR_VARIABLE.
copy_json_cdr	When true, the A-leg JSON CDR is copied to the B-leg at bridge time. Functions like copy_xml_cdr but for the JSON CDR format. Corresponds to SWITCH_COPY_JSON_CDR_VARIABLE.
accountcode	Arbitrary account code attached to the channel. Used by CDR modules: if the value matches a template name in cdr_csv.conf.xml, that template is used for CSV CDR generation.

---

Session UUIDs

These variables implement RFC 7989 (Session-ID) tracking and other UUID-based session identification. They are managed by the core and are typically read-only in the dialplan.

Variable	Purpose
session_uuid	The RFC 7989 Session-ID for this call leg. Generated by the core and exchanged with the remote party via the Session-ID SIP header. Persists across transfers and bridges to provide end-to-end call correlation. Corresponds to SWITCH_RFC7989_SESSION_ID_VARIABLE.
remote_session_uuid	The RFC 7989 Session-ID received from the remote party. Populated by mod_sofia when the remote includes a Session-ID header. Corresponds to SWITCH_RFC7989_REMOTE_SESSION_ID_VARIABLE.
app_session_uuid	Application-layer session UUID, distinct from the RFC 7989 signaling UUID. Used when an application creates its own session correlation context. Corresponds to SWITCH_RFC7989_APP_SESSION_ID_VARIABLE.
generic_param_session_uuid	Carries a session UUID passed as a generic SIP parameter rather than as a dedicated Session-ID header. Used in interoperability scenarios where the Session-ID header is not supported. Corresponds to SWITCH_RFC7989_GENERIC_PARAM_VARIABLE.

---

Application Execution and CDR

These variables control per-channel application logging and speech handle caching.

Variable	Purpose
disable_app_log	When true, the core does not log application execution records for this channel (switch_core_session.c). Reduces log verbosity for high-volume automated channels. Corresponds to SWITCH_DISABLE_APP_LOG_VARIABLE.
current_application	Set by the core to the name of the dialplan application currently executing on this channel. Read-only; updated in switch_core_session.c before each application runs. Corresponds to SWITCH_CURRENT_APPLICATION_VARIABLE.
current_application_data	Set by the core to the argument string of the currently executing application. Read-only; updated alongside current_application. Corresponds to SWITCH_CURRENT_APPLICATION_DATA_VARIABLE.
current_application_response	Set by some applications to a string describing the outcome of their execution (e.g., SUCCESS, TIMEOUT, FAILURE). Available after the application returns. Corresponds to SWITCH_CURRENT_APPLICATION_RESPONSE_VARIABLE.
read_result	Set by the read application after it completes. Values: success (digits collected), timeout (no input within timeout), failure (channel error). Corresponds to SWITCH_READ_RESULT_VARIABLE.
read_terminator_used	Set by the read application to the terminator digit that stopped collection, or empty if the digit count was reached without a terminator. Corresponds to SWITCH_READ_TERMINATOR_USED_VARIABLE.
cache_speech_handles	When true, ASR/TTS engine handles opened during detect_speech or TTS playback are cached across multiple calls rather than torn down and reopened each time. Reduces latency for repeated speech operations. Corresponds to SWITCH_CACHE_SPEECH_HANDLES_VARIABLE.

---

Playback, TTS, and Application Controls

These tune playback, speak/TTS, and assorted dialplan applications.

Variable	Purpose
tts_engine	Default TTS engine used by speak/playback when none is specified.
tts_voice	Default TTS voice used by speak/playback when none is specified.
playback_timeout_sec	Per-file playback timeout in seconds.
playback_timeout_sec_cumulative	Cumulative playback timeout in seconds across files.
playback_timeout_as_success	When true, a playback timeout is treated as success rather than failure.
playback_delimiter	Delimiter character separating multiple files in a playback string.
playback_sleep_val	Sleep (ms) inserted between files when using playback_delimiter.
app_disable_expand_variables	When true, disables ${var} expansion in application argument strings.
ivr_menu_terminator	Terminator digit for IVR menu digit collection.
DISPLACE_HANGUP_ON_ERROR	Controls whether displace_session hangs up the channel on error.
hangup_after_conference	When false, the channel is not hung up after leaving a conference (default hangs up).
outcall_flags	Conference flags applied to legs dialed out via conference dial.
valet_ticket	Ticket/slot identifier used by mod_valet_parking.
python_script_path	Extra path appended to the Python module search path for mod_python3.
mutex_timeout	Timeout (seconds) a channel waits to acquire a mutex.
mutex_feedback	Audio/file (or silence) played to a channel waiting on a mutex.
mutex_orbit_exten	Extension to send a waiting mutex channel to on timeout (sets a default 60s timeout).
mutex_orbit_context	Dialplan context for the mutex orbit on timeout.
mutex_orbit_dialplan	Dialplan engine for the mutex orbit on timeout.

DTMF

These variables control DTMF handling for a channel.

Variable	Purpose
dtmf_type	Sets the DTMF signaling method for outbound legs. Accepted values: rfc2833 (in-band RTP telephone-event), info (SIP INFO messages), none (no DTMF). When not set, the negotiated method from the SDP is used. FreeSWITCH reads and writes this variable in switch_core_media.c. For inband detection, start_dtmf must also be applied in the dialplan.
drop_dtmf	When true, DTMF events received on the channel are discarded and not forwarded to the bridged party. Set on an inbound channel before answer, or on an outbound channel before bridge. Verified against RFC 4733 (in-band). May also work with SIP INFO and inband. Defined in switch_core_io.c.
drop_dtmf_masking_digits	When drop_dtmf=true, this string specifies a replacement digit sequence to write into the audio stream where DTMF tones would have been, masking the tones rather than leaving silence.
drop_dtmf_masking_file	When drop_dtmf=true, path to an audio file to splice into the audio stream to mask dropped DTMF tones.
sensitive_dtmf	When true, DTMF events are not logged in the application log. Useful for channels handling PIN entry. Corresponds to SWITCH_SENSITIVE_DTMF_VARIABLE.

---

DTMF Binding and Tone Detection

Variable	Purpose
bind_meta_key	DTMF digit used as the meta/trigger key for bind_meta_app (default *).
bind_digit_digit_timeout	Inter-digit timeout (ms) for the bind_digit_action dmachine (default 1500).
bind_digit_input_timeout	Overall input timeout (ms) for the bind_digit_action dmachine.
bda_terminators	Terminator digits for the dmachine created by bind_digit_action.
asr_intercept_dtmf	When true, DTMF detected by the ASR engine is intercepted/queued rather than passed through.
pass_rfc2833	When true, passes RFC 2833 (telephone-event) DTMF through transparently.
digits_dialed_filter	Regex; matching dialed digits are masked in the digits_dialed history.
sleep_eat_digits	When true, the sleep application consumes DTMF received during the sleep.
min_dup_digit_spacing_ms	Minimum spacing (ms) before a duplicate inband DTMF digit is accepted.
dtmf_verbose	When true, enables verbose logging of detected inband DTMF.
pound_replace	Digit string that replaces # in say/spell playback.
star_replace	Digit string that replaces * in say/spell playback.
tone_detect_expires	Expiry time (seconds) for a tone_detect detector.
tone_detect_hits	Number of hits required before tone_detect fires.
tone_detect_sleep	Quiet interval (seconds) between tone_detect evaluations.

Directory and Account

These variables are typically set in user directory XML entries and are loaded onto the channel when a user authenticates.

Variable	Purpose
user_context	The dialplan context to use when routing calls originating from this user. Set in the directory <variable> block. Example: default.
toll_allow	Comma-separated list of calling class names (e.g., local,domestic,international) granted to this user. The dialplan tests this variable against condition expressions to implement class-of-service routing.
vm-password	Voicemail PIN for this user. Set as a directory <param> (not a <variable>). Read by mod_voicemail during mailbox authentication.

---

Execution Hooks

These variables trigger dialplan applications or API commands automatically at defined call lifecycle points.

Variable	Purpose
execute_on_answer	Dialplan application to execute when the called party answers. Use export nolocal:execute_on_answer=app args to target the B-leg. The application runs only on channels not yet in the answered state.
execute_on_pre_answer	Dialplan application to execute when the channel enters pre-answer (early media) state.
execute_on_media	Dialplan application to execute when media is established on the channel.
execute_on_ring	Dialplan application to execute when the channel begins ringing.
execute_on_originate	Dialplan application to execute immediately after an originate succeeds (B-leg answered). Corresponds to SWITCH_CHANNEL_EXECUTE_ON_ORIGINATE_VARIABLE.
execute_on_pre_originate	Dialplan application to execute before origination begins. Corresponds to SWITCH_CHANNEL_EXECUTE_ON_PRE_ORIGINATE_VARIABLE.
execute_on_post_originate	Dialplan application to execute after origination is fully complete. Corresponds to SWITCH_CHANNEL_EXECUTE_ON_POST_ORIGINATE_VARIABLE.
execute_on_pre_bridge	Dialplan application to execute immediately before a bridge is established.
execute_on_post_bridge	Dialplan application to execute immediately after a bridge completes.
execute_on_tone_detect	Dialplan application to execute when a tone is detected by the tone_detect application. Corresponds to SWITCH_CHANNEL_EXECUTE_ON_TONE_DETECT_VARIABLE.
api_on_answer	API command to execute when the called party answers. Use export nolocal:api_on_answer=command args to target the B-leg. To execute a dialplan application instead, use execute_on_answer.
api_on_pre_answer	API command to execute when the channel enters pre-answer state.
api_on_media	API command to execute when media is established on the channel.
api_on_ring	API command to execute when the channel begins ringing.
api_on_originate	API command to execute after an originate succeeds. Corresponds to SWITCH_CHANNEL_API_ON_ORIGINATE_VARIABLE.
api_on_pre_originate	API command to execute before origination begins. Corresponds to SWITCH_CHANNEL_API_ON_PRE_ORIGINATE_VARIABLE.
api_on_post_originate	API command to execute after origination is fully complete. Corresponds to SWITCH_CHANNEL_API_ON_POST_ORIGINATE_VARIABLE.
api_on_tone_detect	API command to execute when a tone is detected by the tone_detect application. Corresponds to SWITCH_CHANNEL_API_ON_TONE_DETECT_VARIABLE.
api_before_bridge	API command to execute immediately before a bridge is established. Corresponds to SWITCH_API_BRIDGE_START_VARIABLE.
api_after_bridge	API command to execute after a bridge completes.
api_hangup_hook	API command to execute when the channel hangs up.
api_reporting_hook	API command to execute when the channel reaches the reporting state (post-hangup CDR phase). Corresponds to SWITCH_API_REPORTING_HOOK_VARIABLE.
session_in_hangup_hook	When true, the session remains available during api_hangup_hook execution, allowing the API command to access channel variables. Corresponds to SWITCH_SESSION_IN_HANGUP_HOOK_VARIABLE.

---

Event and Logging Hooks

Variable	Purpose
fire_talk_events	When true, fires "talking" events from RTP VAD.
fire_not_talk_events	When true, fires "not talking" events from RTP VAD.
fire_asr_events	When true, fires ASR detection events to the event system.
verbose_presence	When true, enables verbose presence event generation for the session.
heartbeat_fire_on_set	When true, fires a session heartbeat event immediately when the heartbeat is (re)set.
heartbeat_use_scheduler	When true, drives the session heartbeat via the scheduler instead of inline.
session_copy_loglevel	When true, copies the session log level to a newly originated child session.
log_audio_stats_on_hangup	When true, logs RTP audio statistics on hangup.
hangup_complete_with_xml	When true, includes the channel XML CDR in hangup-complete handling.

Module Reference Variables

Variables introduced by the optional modules documented in Part 9: Module Reference. Each module page carries the authoritative table (what sets the variable, what reads it, and accepted values); the index below maps each variable to its module so it can be found from here. Generic core variables that these modules merely read (such as caller_id_number, destination_number, language, or the directory variables) are documented in the sections above and are not repeated here.

Module	Variables	Reference
mod_avmd	avmd_detect, avmd_total_time, execute_on_avmd_beep	mod_avmd
mod_bert	bert_window_ms, bert_timeout_ms, bert_max_err, bert_hangup_on_error, bert_debug_io_file, bert_timer_name, bert_stats_sync_lost, bert_stats_sync_lost_count	mod_bert
mod_cidlookup	original_caller_id_name, cidlookup_source, cidlookup_area	mod_cidlookup
mod_curl	curl_response_data, curl_response_code, curl_method, curl_connect_timeout, curl_timeout, curl_sendfile_url, curl_sendfile_filename_element, curl_sendfile_filename, curl_sendfile_extrapost, curl_sendfile_report, curl_sendfile_identifier	mod_curl
mod_cv	execute_on_cv_detect_primary, execute_on_cv_detect_off_primary, execute_on_cv_detect_nested, execute_on_cv_detect_off_nested	mod_cv
mod_directory	directory_group_selection, directory_voicemail_profile, directory_search_order	mod_directory
mod_distributor	DISTRIBUTOR	mod_distributor
mod_easyroute	easy_destnum, easy_dialstring, easy_group, easy_limit, easy_acctcode	mod_easyroute
mod_fsk	fsk_phone_num, fsk_phone_name, fsk_datetime, fsk_uri, execute_on_fsk, fsk_simplify_profile, fsk_simplify_context	mod_fsk
mod_lcr	intrastate, intralata, lrn, max_rate, lcr_auto_route, lcr_route_count, lcr_route_N, lcr_rate_N, lcr_carrier_N, lcr_codec_N, lcr_carrier, lcr_rate, lcr_user_rate, lcr_rate_field, lcr_user_rate_field, lcr_query_digits, lcr_query_profile, lcr_query_expanded_digits, lcr_query_expanded_lrn_digits, lcr_lrn	mod_lcr
mod_nibblebill	nibble_rate, nibble_account, nibble_increment, nibble_rounding, nibble_minimum, nobal_amt, lowbal_amt, nibble_bill, nibble_total_billed, nibble_current_balance	mod_nibblebill
mod_osp	osp_source_device, osp_source_nid, osp_custom_info_1 … osp_custom_info_8, osp_networkid_userparam, osp_networkid_uriparam, osp_outstring_userparam, osp_outstring_uriparam, osp_user_phone, osp_outbound_proxy, osp_profile_name, osp_transaction_handle, osp_transaction_id, osp_lookup_status, osp_next_status, osp_route_total, osp_route_count, osp_auto_route, osp_termination_cause	mod_osp
mod_translate	translated, translate_profile, country, default_country, areacode, default_areacode	mod_translate
mod_vmd	vmd_detect, vmd_min_time	mod_vmd
mod_voicemail_ivr	voicemail_authorized	mod_voicemail_ivr
mod_h323	progress-indication, alerting-indication, fax_enable_t38_insist	mod_h323
mod_opal	has_t38, opal_execute_on_t38, opal_api_on_t38	mod_opal
mod_vlc	vlc_force_width, vlc_force_height, vlc_capture_offset, vlc_interval, vlc_rate, vlc_channels	mod_vlc
mod_webm	webmv2_video_offset	mod_webm
mod_smpp	smpp_gateway, smpp_from_user, smpp_to_user	mod_smpp
mod_format_cdr	format_cdr_base, force_process_cdr	mod_format_cdr
mod_json_cdr	json_cdr_base, force_process_cdr	mod_json_cdr
mod_odbc_cdr	odbc-cdr-ignore-leg	mod_odbc_cdr
mod_hiredis	hiredis_raw_response, hiredis_limit_exceeded	mod_hiredis