FS Channel Variables
See Channel Variables
This duplicate page is being merged with __Channel Variables . Please refer to that page.
About
There are a number of channel variables that can be set in the dialplan or your application to affect the progress or settings for a call. Channel variables can also be set in dialstrings (see below).
Click here to expand Table of Contents
- 1 See Channel Variables
- 2 Channel Variables in the XML Dialplan
- 2.1 Scoped Variables
- 3 Channel Variables in Dial strings
- 4 Exporting Channel Variables in Bridge Operations
- 5 Using Channel Variables in Dialplan Condition Statements
- 6 Custom Channel Variables
- 7 Channel Variable Manipulation
- 8 Channel Variable Scope with Example
- 9 Info Application Variable Names (variable_xxxx)
- 10 ${variable} vs. $${variable}
- 11 CDR Related
- 11.1 process_cdr
- 11.2 accountcode
- 11.3 hold_events
- 11.4 hangup_complete_with_xml
- 11.5 skip_crd_causes
- 11.6 transfer_to
- 12 Hangup Causes
- 12.1 bridge_hangup_cause
- 12.2 disable_q850_reason
- 12.3 hangup_causes
- 12.4 hangup_cause_q850
Channel Variables in the XML Dialplan
Channel variables are set, appropriately enough, with the set application like this:
<action application="set" data="var_name=var value"/>
Accessing channel variables requires the ${} syntax:
<action application="log" data="INFO The value in the var_name chan var is ${var_name}"/>
<condition field="${var_name}" expression="some text">
Scoped Variables
- Channel variables used to be global to the session.
- With Scoped variables, you can now set variables that only exist for the duration of that single application execution and any subsequent applications under it.
- Applications can leverage this concept to use named input params
As of June 15 (git commit b2c3199f) you may now have scoped variables that will stay in effect only for the duration of a given dialplan application. Example:
<action application="log" data="INFO myvar is '${myvar}'"/>
<action application="log" data="%[myvar=Hello]INFO myvar is '${myvar}'"/>
<action application="log" data="INFO myvar is '${myvar}'"/>
<action application="myapp" data="%[var1=val1,var2=val2]mydata"/>
Channel Variables in Dial strings
The syntax of using { } versus < > versus [] is explained below.
- {foo=bar} is only valid at the beginning of the dial string. It will set the same variables on every channel, but does not do so for enterprise bridging/originate.
- <foo=bar> is only valid at the beginning of the dial string. It will set the same variables on every channel, including all those in an enterprise bridging/originate.
- [foo=bar] goes before each individual dial string and will set the variable values specified for only this channel.
- The following example sets the foo variable for all channels implemented and chan=1 is specific to blah, while chan=2 is specific to blah2
{foo=bar}[chan=1]sofia/default/blah@baz.com,[chan=2]sofia/default/blah2@baz.com
- Setting multiple variables can be accomplished by comma delimiting:
[var1=abc,var2=def,var3=ghi]sofia/default/blah@baz.com
- If you would like to have variables in [] override the same variables set in {}, you may set 'local_var_clobber=true' inside {}. For example:
{local_var_clobber=true,sip_secure_media=true}sofia/default/blah1@baz.com|sofia/default/johndoe@example.com|[sip_secure_media=false]sofia/default/janedoe@acme.com
You must also set this local_var_clobber variable to true when you want to override channel variables that have been exported to your b-legs in your dialplan.
In this example, the legs for blah1@baz.com and johndoe@example.com would be set to offer SRTP (RTP/SAVP) while janedoe@acme.com would not receive an SRTP offer (she would see RTP/AVP instead).
Handling Variables With Commas
Since commas are the default delimiter inside of {} and [] it is necessary to have an alternate means of delimiting values that actually contain commas.
To set a variable with a "," inside of it (e.g. the absolute_codec_string), you must tell FreeSWITCH what delimiter to use instead for THIS value.
The syntax is to put a prefix of ^^: at the start of the value and replace the commas in the value with ":". Then, FreeSWITCH will substitute commas back in when setting the value for the channel.
You can use (almost) any character you like though, it uses the one after the initial "^^"
{absolute_codec_string=^^:PCMA@8000h@20i@64000b:PCMU@8000h@20i@64000b:G729@8000h@20i@8000b,leg_time_out=10,process_cdr=b_only}
This approach however does not work when you are setting sip_h_, sip_rh_ and sip_ph headers. If you want to pass a comma into the contents of a private header then you must escape the comma with a preceding backslash:
{sip_h_X-My-Header=one\,two\,three,leg_time_out=10,process_cdr=b_only}
Exporting Channel Variables in Bridge Operations
You can export a variable from one call leg (A) to the other call leg (B) by using the 'export_vars' variable which is a comma separated list of variables that you wish to propagate across calls. Usage:
<action application="set" data="export_vars=myvar,myvar2,foo,bar"/>
You can also set a variable on the (A) leg and add it to the export list in one step with the export application:
<action application="export" data="myvar=true"/>
Using Channel Variables in Dialplan Condition Statements
Channel variables can be used in conditions:
- See dialplan conditions for specifics. <MISSING LINK>
- Keep in mind that some channel variables may not be set during the dialplan parsing phase. See inline actions section of Dialplan_XML for more information. <MISSING LINK>
Custom Channel Variables
Additionally, you may set any number of unique channel variables for your own purposes and even elect to log them to the CDR. In order to set any channel variable, use the application "set" to effect the setting. You can also set channel variables on the command issued via XML-RPC or Event Socket by adding {myvar=myval,myvar1=myval1} e.g.
originate {ignore_early_media=true}sofia/mydomain.com/18005551212@1.2.3.4 15555551212
If the value you are setting has a space in it then you will need to enclose the value in quotes. For example:
originate {fax_ident=1231231234,fax_header='Fax Test'}sofia/gateway/outbound.fax/1004 &txfax(/tmp/fax.tiff)
Channel Variable Manipulation
Channel variables can be manipulated for varied results. For example, you can trim bits and pieces of a channel variable, perhaps to get the first three digits of a phone number. See Manipulating Channel Variables for more information. <MISSING LINK>
Channel Variable Scope with Example
Consider the following example that shows where each application sets it's variable:
<extension name="test" continue="false">
<condition field="destination_number" expression="^test([0-9]+)$">
<action application="set" data="fruit=tomato" /> <!-- Set variable in local channel -->
<action application="export" data="veggie=tomato" /> <!-- Set variable in local channel and export it to new channels we bridge to -->
<action application="bridge" data="{meat=tomato},sofia/gateway/testaccount/1234" /><!-- bridge new channel and set variable only in new channel -->
</condition>
</extension>
Leg A (the channel that called the dialplan) will have the following variable set:
fruit: tomato
veggie: tomato
Leg B (the channel created with sofia/gateway/testaccount/1234) will have the following variables set:
veggie: tomato
meat: tomato
Info Application Variable Names (variable_xxxx)
Some variables, as shown from the info app, may have variable_ in front of their names. For example, if you pass a header variable called 'type' from the proxy server, it will get displayed as 'variable_sip_h_type' in FreeSWITCH. To access that variable, you should strip off the variable_, and just do ${sip_h_type}. Other variables shown in the info app are prepended with channel, which should be stripped as well. The example below show a list of info app variables and the corresponding channel variable names:
| Info variable name | channel variable name | Description |
|---|---|---|
| Channel-State | state | Current state of the call |
| Channel-State-Number | state_number | Integer |
| Channel-Name | channel_name | Channel name |
| Unique-ID | uuid | uuid of this channel's call leg |
| Call-Direction | direction | Inbound or Outbound |
| Answer-State | state | . |
| Channel-Read-Codec-Name | read_codec | the read codec variable mean the source codec |
| Channel-Read-Codec-Rate | read_rate | the source rate |
| Channel-Write-Codec-Name | write_codec | the destination codec same to write_codec if not transcoded |
| Channel-Write-Codec-Rate | write_rate | destination rate same to read rate if not transcoded |
| Caller-Username | username | . |
| Caller-Dialplan | dialplan | user dialplan like xml, lua, enum, lcr |
| Caller-Caller-ID-Name | caller_id_name | . |
| Caller-Caller-ID-Number | caller_id_number | . |
| Caller-ANI | ani | ANI of caller, frequently the same as caller ID number |
| Caller-ANI-II | aniii | ANI II Digits (OLI - Originating Line Information), if available. Refer to:http://www.nanpa.com/number%5Fresource%5Finfo/ani%5Fii%5Fdigits.html |
| Caller-Network-Addr | network_addr | IP address of calling party |
| Caller-Destination-Number | destination_number | Destination (dialed) number |
| Caller-Unique-ID | uuid | This channel's uuid |
| Caller-Source | source | Source module, i.e. mod_sofia, mod_openzap, etc. |
| Caller-Context | context | Dialplan context |
| Caller-RDNIS | rdnis | Redirected DNIS info. See transfer application |
| Caller-Channel-Name | channel_name | . |
| Caller-Profile-Index | profile_index | . |
| Caller-Channel-Created-Time | created_time | . |
| Caller-Channel-Answered-Time | answered_time | . |
| Caller-Channel-Hangup-Time | hangup_time | . |
| Caller-Channel-Transfer-Time | transfer_time | . |
| Caller-Screen-Bit | screen_bit | . |
| Caller-Privacy-Hide-Name | privacy_hide_name | . |
| Caller-Privacy-Hide-Number | privacy_hide_number | This variable tells you if the inbound call is asking for CLIR[Calling Line ID presentation Restriction] (either with anonymous method or Privacy:id method) |
| variable_sip_received_ip | sip_received_ip | . |
| variable_sip_received_port | sip_received_port | . |
| variable_sip_authorized | sip_authorized | . |
| variable_sip_mailbox | sip_mailbox | . |
| variable_sip_auth_username | sip_auth_username | . |
| variable_sip_auth_realm | sip_auth_realm | . |
| variable_mailbox | mailbox | . |
| variable_user_name | user_name | . |
| variable_domain_name | domain_name | . |
| variable_record_stereo | record_stereo | . |
| variable_accountcode | accountcode | Accountcode for the call. This is an arbitrary value. It can be defined in the user variables in the directory, or it can be set/modified from dialplan. The accountcode may be used to force a specific CDR CSV template for the call. |
| variable_user_context | user_context | . |
| variable_effective_caller_id_name | effective_caller_id_name | . |
| variable_effective_caller_id_number | effective_caller_id_number | . |
| variable_caller_domain | caller_domain | . |
| variable_sip_from_user | sip_from_user | . |
| variable_sip_from_uri | sip_from_uri | . |
| variable_sip_from_host | sip_from_host | . |
| variable_sip_from_user_stripped | sip_from_user_stripped | . |
| variable_sip_from_tag | sip_from_tag | . |
| variable_sofia_profile_name | sofia_profile_name | . |
| variable_sofia_profile_domain_name | sofia_profile_domain_name | . |
| variable_sip_full_route | sip_full_route | The complete contents of the Route: header. |
| variable_sip_full_via | sip_full_via | The complete contents of the Via: header. |
| variable_sip_full_from | sip_full_from | The complete contents of the From: header. |
| variable_sip_full_to | sip_full_to | The complete contents of the To: header. |
| variable_sip_req_params | sip_req_params | . |
| variable_sip_req_user | sip_req_user | . |
| variable_sip_req_uri | sip_req_uri | . |
| variable_sip_req_host | sip_req_host | . |
| variable_sip_to_params | sip_to_params | . |
| variable_sip_to_tag | sip_to_tag | . |
| variable_sip_to_user | sip_to_user | . |
| variable_sip_to_uri | sip_to_uri | . |
| variable_sip_to_host | sip_to_host | . |
| variable_sip_contact_params | sip_contact_params | . |
| variable_sip_contact_user | sip_contact_user | . |
| variable_sip_contact_port | sip_contact_port | . |
| variable_sip_contact_uri | sip_contact_uri | . |
| variable_sip_contact_host | sip_contact_host | . |
| variable_sip_invite_domain | sip_invite_domain | . |
| variable_channel_name | channel_name | . |
| variable_sip_call_id | sip_call_id | . |
| variable_sip_user_agent | sip_user_agent | . |
| variable_sip_via_host | sip_via_host | . |
| variable_sip_via_port | sip_via_port | . |
| variable_sip_via_rport | sip_via_rport | . |
| variable_presence_id | presence_id | . |
| variable_sip_h_P-Key-Flags | sip_h_p-key-flags | This will contain the optional P-Key-Flags header(s) that may be received from calling endpoint. |
| variable_switch_r_sdp | switch_r_sdp | The whole SDP received from calling endpoint. |
| variable_remote_media_ip | remote_media_ip | . |
| variable_remote_media_port | remote_media_port | . |
| variable_write_codec | write_codec | . |
| variable_write_rate | write_rate | . |
| variable_endpoint_disposition | endpoint_disposition | . |
| variable_dialed_ext | dialed_ext | . |
| variable_transfer_ringback | transfer_ringback | . |
| variable_call_timeout | call_timeout | . |
| variable_hangup_after_bridge | hangup_after_bridge | . |
| variable_continue_on_fail | continue_on_fail | . |
| variable_dialed_user | dialed_user | . |
| variable_dialed_domain | dialed_domain | . |
| variable_sip_redirect_contact_user_0 | sip_redirect_contact_user_0 | . |
| variable_sip_redirect_contact_host_0 | sip_redirect_contact_host_0 | . |
| variable_sip_h_Referred-By | sip_h_referred-by | . |
| variable_sip_refer_to | sip_refer_to | The full SIP URI received from a SIP Refer-To: response |
| variable_max_forwards | max_forwards | . |
| variable_originate_disposition | originate_disposition | . |
| variable_read_codec | read_codec | . |
| variable_read_rate | read_rate | . |
| variable_open | open | . |
| variable_use_profile | use_profile | . |
| variable_current_application | current_application | . |
| variable_ep_codec_string | ep_codec_string | This variable is only available if late negotiation is enabled on the profile. It's a readable string containing all the codecs proposed by the calling endpoint. This can be easily parsed in the dialplan. |
| variable_disable_hold | disable_hold | This variable when set will disable the hold feature of the phone. |
| variable_sip_acl_authed_by | sip_acl_authed_by | This variable holds what ACL rule allowed the call. |
| variable_curl_response_data | curl_response_data | This variable stores the output from the last curl made. |
| variable_drop_dtmf | drop_dtmf | Set on a channel to drop DTMF events on the way out. |
| sip_codec_negotiation | sip_codec_negotiation | sip_codec_negotiation is basically a channel variable equivalent of inbound-codec-negotiation.sip_codec_negotiation accepts "scrooge" & "greedy" as values.This means you can change codec negotiation on a per call basis. |
| Caller-Callee-ID-Name | - | - |
| Caller-Callee-ID-Number | - | - |
| Caller-Channel-Progress-Media-Time | - | - |
| Caller-Channel-Progress-Time | - | - |
| Caller-Direction | - | - |
| Caller-Profile-Created-Time | profile_created | - |
| Caller-Transfer-Source | - | - |
| Channel-Call-State | - | - |
| Channel-Call-UUID | - | - |
| Channel-HIT-Dialplan | - | - |
| Channel-Read-Codec-Bit-Rate | - | - |
| Channel-Write-Codec-Bit-Rate | - | - |
| Core-UUID | - | - |
| Event-Calling-File | - | - |
| Event-Calling-Function | - | - |
| Event-Calling-Line-Number | - | - |
| Event-Date-GMT | - | - |
| Event-Date-Local | - | - |
| Event-Date-Timestamp | - | - |
| Event-Name | - | - |
| Event-Sequence | - | - |
| FreeSWITCH-Hostname | - | - |
| FreeSWITCH-IPv4 | - | - |
| FreeSWITCH-IPv6 | - | - |
| FreeSWITCH-Switchname | - | - |
| Hunt-ANI | - | - |
| Hunt-Callee-ID-Name | - | - |
| Hunt-Callee-ID-Number | - | - |
| Hunt-Caller-ID-Name | - | - |
| Hunt-Caller-ID-Number | - | - |
| Hunt-Channel-Answered-Time | - | - |
| Hunt-Channel-Created-Time | - | - |
| Hunt-Channel-Hangup-Time | - | - |
| Hunt-Channel-Name | - | - |
| Hunt-Channel-Progress-Media-Time | - | - |
| Hunt-Channel-Progress-Time | - | - |
| Hunt-Channel-Transfer-Time | - | - |
| Hunt-Context | - | - |
| Hunt-Destination-Number | - | - |
| Hunt-Dialplan | - | - |
| Hunt-Direction | - | - |
| Hunt-Network-Addr | - | - |
| Hunt-Privacy-Hide-Name | - | - |
| Hunt-Privacy-Hide-Number | - | - |
| Hunt-Profile-Created-Time | profile_created | - |
| Hunt-Profile-Index | - | - |
| Hunt-RDNIS | - | - |
| Hunt-Screen-Bit | - | - |
| Hunt-Source | - | - |
| Hunt-Transfer-Source | - | - |
| Hunt-Unique-ID | - | - |
| Hunt-Username | - | - |
| Presence-Call-Direction | - | - |
| variable_DIALSTATUS | - | - |
| variable_absolute_codec_string | - | - |
| variable_advertised_media_ip | - | - |
| variable_bridge_channel | - | - |
| variable_bridge_hangup_cause | - | - |
| variable_bridge_uuid | - | - |
| variable_call_uuid | - | - |
| variable_current_application_response | - | - |
| variable_direction | - | - |
| variable_inherit_codec | - | - |
| variable_is_outbound | - | - |
| variable_last_bridge_to | - | - |
| variable_last_sent_callee_id_name | - | - |
| variable_last_sent_callee_id_number | - | - |
| variable_local_media_ip | - | - |
| variable_local_media_port | - | - |
| variable_number_alias | - | - |
| variable_originate_early_media | - | - |
| variable_originating_leg_uuid | - | - |
| variable_originator | - | - |
| variable_originator_codec | - | - |
| variable_outbound_caller_id_number | - | - |
| variable_recovery_profile_name | - | - |
| variable_rtp_use_ssrc | - | - |
| variable_session_id | - | - |
| variable_sip_2833_recv_payload | - | - |
| variable_sip_2833_send_payload | - | - |
| variable_sip_P-Asserted-Identity | - | - |
| variable_sip_Privacy | - | - |
| variable_sip_audio_recv_pt | - | - |
| variable_sip_cid_type | - | - |
| variable_sip_cseq | - | - |
| variable_sip_destination_url | - | - |
| variable_sip_from_display | - | - |
| variable_sip_from_port | - | - |
| variable_sip_gateway | - | - |
| variable_sip_gateway_name | - | - |
| variable_sip_h_P-Charging-Vector | - | - |
| variable_sip_local_network_addr | - | - |
| variable_sip_local_sdp_str | - | - |
| variable_sip_network_ip | - | - |
| variable_sip_network_port | - | - |
| variable_sip_number_alias | - | - |
| variable_sip_outgoing_contact_uri | - | - |
| variable_sip_ph_P-Charging-Vector | - | - |
| variable_sip_profile_name | - | - |
| variable_sip_recover_contact | - | - |
| variable_sip_recover_via | - | - |
| variable_sip_reply_host | - | - |
| variable_sip_reply_port | - | - |
| variable_sip_req_port | - | - |
| variable_sip_to_port | - | - |
| variable_sip_use_codec_name | - | - |
| variable_sip_use_codec_ptime | - | - |
| variable_sip_use_codec_rate | - | - |
| variable_sip_use_pt | - | - |
| variable_sip_via_protocol | - | - |
| variable_switch_m_sdp | - | - |
| variable_transfer_history | - | - |
| variable_transfer_source | - | - |
| variable_uuid | - | - |
${variable} vs. $${variable}
${variables} are channel variables that may be set in the dialplan, application or directory that affect call progress or settings.
$${variables} are expanded when the master freeswitch.xml is compiled. This happens when you start FreeSWITCH, or when reloadxml is called.
The key is that $${variables} are evaluated *once* by the pre-processor, and ${variables} are evaluated fresh each time they are executed (for example when a call connects).
CDR Related
<multiple missing links, remove maybe?>
process_cdr
Indicates how to process CDR records.
Can be undefined or set to "false", "true", "a_only", "b_only"
false - indicates to not process the record.
true - or undefined indicates the default behavior which is to process all CDR records.
a_only - indicates to only process CDR records on the inbound leg of a call.
b_only - indicates to only process CDR records on the outbound leg of a call.
This variable is unconditionally exported.
Usage:
<action application="set" data="process_cdr=a_only"/>
accountcode
Account code is mostly an arbitrary value that you can assign on a per leg basis. An important feature of accountcode is that if its value matches one of the CDR CSV templates defined in cdr_csv.conf.xml then that CDR template will be used when generating a CSV CDR.
Usage:
<action application="set" data="accountcode=custom"/>
hold_events
It's a variable that display start and stop times for each hold.
Example:
This CDR shows that the phone was put on hold twice with hold start and stop time.
variable_hold_events: [{{1347487292379229,1347487293856872},{1347487288539686,1347487290757780}}]
hangup_complete_with_xml
Variable hangup complete with xml
skip_crd_causes
This is a list of call hangup causes that should not trigger cdr proccessing.
transfer_to
<missing description>
Example:
<missing example>
Hangup Causes
bridge_hangup_cause
This is set to the hangup cause of the last bridged B leg of the call. If you have continue_on_fail=true and hangup_after_bridge=false you can do checks on this to see what "really" happened to the call. You can for instance do execute_extension after bridge, do a condition check on ${bridge_hangup_cause} to see if it contains MEDIA_TIMEOUT and then trigger a redial of the call or transfer to a cell phone. For a list of hangup causes, see Hangup Causes.
Usage:
<action application="log" data="1 B-leg hangup cause: ${bridge_hangup_cause}"/>
disable_q850_reason
When set to true, this disables sending of the Reason header, which includes the Q.850 reason code, in responses and BYEs. For a list of hangup causes and their Q.850 codes, see Hangup Causes. This is available as of revision 15850 committed 12/8/2009.
Usage:
<action application="set" data="disable_q850_reason=true"/>
hangup_causes
This is set to the hangup cause of the A leg of the call (note that as such it doesn't make much sense before the end of the call). Often this will take the hangup cause from the B leg of the call, if there is one. For a list of hangup causes, see Hangup Causes.
Usage:
<action application="log" data="1 A-leg hangup cause: ${hangup_cause}"/>
hangup_cause_q850
This is set to the Q850 numeric code of the hangup cause of the A leg of the call (note that as such it doesn't make much sense before the end of the call). Often this will take the hangup cause from the B leg of the call, if there is one. For a list of hangup causes, see Hangup Causes.
Usage:
<action application="log" data="1 A-leg hangup Q850 cause: ${hangup_cause_q850}"/>