Skip to content

CHANNEL()

Synopsis

Gets/sets various pieces of information about the channel.

Description

Gets/sets various pieces of information about the channel, additional item may be available from the channel driver; see its documentation for details. Any item requested that is not available on the current channel will return an empty string.

Example: Standard CHANNEL item examples
; Push a hangup handler subroutine existing at dialplan
; location default,s,1 onto the current channel
same => n,Set(CHANNEL(hangup_handler_push)=default,s,1)

; Set the current tonezone to Germany (de)
same => n,Set(CHANNEL(tonezone)=de)

; Set the allowed maximum number of forwarding attempts
same => n,Set(CHANNEL(max_forwards)=10)

; If this channel is ejected from its next bridge, and if
; the channel is not hung up, begin executing dialplan at
; location default,after-bridge,1
same => n,Set(CHANNEL(after_bridge_goto)=default,after-bridge,1)

; Log the current state of the channel
same => n,Log(NOTICE, This channel is: ${CHANNEL(state)})
The following channel variables are available as special built-in dialplan channel variables. These variables cannot be set or modified and are read-only.

  • CALLINGPRES - Caller ID presentation for incoming calls (PRI channels)

  • CALLINGANI2 - Caller ANI2 (PRI channels)

  • CALLINGTON - Caller Type of Number (PRI channels)

  • CALLINGTNS - Transit Network Selector (PRI channels)

  • EXTEN - Current extension

  • CONTEXT - Current context

  • PRIORITY - Current priority

  • CHANNEL - Current channel name

  • UNIQUEID - Current call unique identifier

  • HANGUPCAUSE - Asterisk cause of hangup (inbound/outbound)

  • Technology: PJSIP

    Example: PJSIP specific CHANNEL examples
    ; Log the current Call-ID
same => n,Log(NOTICE, ${CHANNEL(pjsip,call-id)})

; Log the destination address of the audio stream
same => n,Log(NOTICE, ${CHANNEL(rtp,dest)})

; Store the round-trip time associated with a
; video stream in the CDR field video-rtt
same => n,Set(CDR(video-rtt)=${CHANNEL(rtcp,rtt,video)})

Syntax

CHANNEL(item)
Arguments

  • item - Standard items (provided by all channel technologies) are:

    • amaflags - R/W the Automatic Message Accounting (AMA) flags on the channel. When read from a channel, the integer value will always be returned. When written to a channel, both the string format or integer value is accepted.

      • 1 - OMIT

      • 2 - BILLING

      • 3 - DOCUMENTATION

    • accountcode - R/W the channel's account code.

    • audioreadformat - R/O format currently being read.

    • audionativeformat - R/O format used natively for audio.

    • audiowriteformat - R/O format currently being written.

    • dtmf_features - R/W The channel's DTMF bridge features. May include one or more of 'T' 'K' 'H' 'W' and 'X' in a similar manner to options in the 'Dial' application. When setting it, the features string must be all upper case.

    • callgroup - R/W numeric call pickup groups that this channel is a member.

    • pickupgroup - R/W numeric call pickup groups this channel can pickup.

    • namedcallgroup - R/W named call pickup groups that this channel is a member.

    • namedpickupgroup - R/W named call pickup groups this channel can pickup.

    • channeltype - R/O technology used for channel.

    • checkhangup - R/O Whether the channel is hanging up (1/0)

    • digitdetect - R/W Enable or disable DTMF detection on channel drivers that support it.
      If set on a DAHDI channel, this will only disable DTMF detection, not pulse dialing detection. To disable pulse dialing, use the 'dialmode' option.
      On DAHDI channels, this will disable DSP if it is not needed for anything else. This will prevent DTMF detection regardless of the 'dialmode' setting.

    • faxdetect - R/W Enable or disable fax detection on channel drivers that support it.

    • after_bridge_goto - R/W the parseable goto string indicating where the channel is expected to return to in the PBX after exiting the next bridge it joins on the condition that it doesn't hang up. The parseable goto string uses the same syntax as the 'Goto' application.

    • hangup_handler_pop - W/O Replace the most recently added hangup handler with a new hangup handler on the channel if supplied. The assigned string is passed to the Gosub application when the channel is hung up. Any optionally omitted context and exten are supplied by the channel pushing the handler before it is pushed.

    • hangup_handler_push - W/O Push a hangup handler onto the channel hangup handler stack. The assigned string is passed to the Gosub application when the channel is hung up. Any optionally omitted context and exten are supplied by the channel pushing the handler before it is pushed.

    • hangup_handler_wipe - W/O Wipe the entire hangup handler stack and replace with a new hangup handler on the channel if supplied. The assigned string is passed to the Gosub application when the channel is hung up. Any optionally omitted context and exten are supplied by the channel pushing the handler before it is pushed.

    • onhold - R/O Whether or not the channel is onhold. (1/0)

    • language - R/W language for sounds played.

    • musicclass - R/W class (from musiconhold.conf) for hold music.

    • name - The name of the channel

    • parkinglot - R/W parkinglot for parking.

    • relaxdtmf - W/O Enable or disable relaxed DTMF detection for channel drivers that support it, overriding any setting previously defaulted by the channel driver.

    • rxgain - R/W set rxgain level on channel drivers that support it.

    • secure_bridge_signaling - Whether or not channels bridged to this channel require secure signaling (1/0)

    • secure_bridge_media - Whether or not channels bridged to this channel require secure media (1/0)

    • state - R/O state of the channel

    • tdd - R/W Enable or disable TDD mode on channel drivers that support it.
      When reading this option, 1 indicates TDD mode enabled, 0 indicates TDD mode disabled, and 'mate' indicates TDD mate mode.

    • tonezone - R/W zone for indications played

    • transfercapability - R/W ISDN Transfer Capability, one of:

      • SPEECH

      • DIGITAL

      • RESTRICTED_DIGITAL

      • 3K1AUDIO

      • DIGITAL_W_TONES

      • VIDEO

    • txgain - R/W set txgain level on channel drivers that support it.

    • videonativeformat - R/O format used natively for video

    • hangupsource - R/W returns the channel responsible for hangup.

    • appname - R/O returns the internal application name.

    • appdata - R/O returns the application data if available.

    • exten - R/O returns the extension for an outbound channel.

    • context - R/O returns the context for an outbound channel.

    • lastexten - R/O returns the last unique extension for an outbound channel.

    • lastcontext - R/O returns the last unique context for an outbound channel.

    • channame - R/O returns the channel name for an outbound channel.

    • uniqueid - R/O returns the channel uniqueid.

    • linkedid - R/O returns the linkedid if available, otherwise returns the uniqueid.

    • tenantid - R/W The channel tenantid.

    • max_forwards - R/W The maximum number of forwards allowed.

    • callid - R/O Call identifier log tag associated with the channel e.g., '[C-00000000]'.

    • Technology: DAHDI

      • dahdi_channel - R/O DAHDI channel related to this channel.

      • dahdi_span - R/O DAHDI span related to this channel.

      • dahdi_group - R/O DAHDI logical group related to this channel.

      • dahdi_type - R/O DAHDI channel type, one of:

        • analog

        • mfc/r2

        • pri

        • pseudo

        • ss7

      • keypad_digits - R/O PRI Keypad digits that came in with the SETUP message.

      • reversecharge - R/O PRI Reverse Charging Indication, one of:

        • -1 - None

        • 1 - Reverse Charging Requested

      • no_media_path - R/O PRI Nonzero if the channel has no B channel. The channel is either on hold or a call waiting call.

      • buffers - W/O Change the channel's buffer policy (for the current call only)
        This option takes two arguments:
        Number of buffers,
        Buffer policy being one of:
        'full'
        'immediate'
        'half'

      • echocan_mode - W/O Change the configuration of the active echo canceller on the channel (if any), for the current call only.
        Possible values are:
        'on'Normal mode (the echo canceller is actually reinitialized)
        'off'Disabled
        'fax'FAX/data mode (NLP disabled if possible, otherwise completely disabled)
        'voice'Voice mode (returns from FAX mode, reverting the changes that were made)

      • dialmode - R/W Pulse and tone dialing mode of the channel.
        Disabling tone dialing using this option will not disable the DSP used for DTMF detection. To do that, also set the 'digitdetect' option. If digit detection is disabled, DTMF will not be detected, regardless of the 'dialmode' setting. The 'digitdetect' setting has no impact on pulse dialing detection.
        If set, overrides the setting in 'chan_dahdi.conf' for that channel.

        • both

        • pulse

        • dtmf

        • tone

        • none

      • waitfordialtone - W/O Duration in ms for which to wait for dial tone on the current call.
        This setting is will temporarily override the 'waitfordialtone' setting in 'chan_dahdi.conf' (typically if that setting is disabled). You must call this in a pre-dial handler when making a call on an analog trunk (e.g. FXS-signalled interface).
        This allows, for example, being able to barge in on an in-use trunk, if dialed specifically, but allows skipping the trunk when routing calls if dial tone is not present on a channel.
        This setting will only apply to the current (next) call made on the DAHDI channel, and will not persist for future calls.
        Please keep in mind that due to the way that chan_dahdi implements dial tone detection, DTMF digits on an in-use channel will temporarily relay to any other channels attempting to use the channel for a call. However, voice transmission will not leak.

    • Technology: IAX

      • osptoken - R/O Get the peer's osptoken.

      • peerip - R/O Get the peer's ip address.

      • peername - R/O Get the peer's username.

      • secure_signaling - R/O Get the if the IAX channel is secured.

      • secure_media - R/O Get the if the IAX channel is secured.

    • Technology: OOH323

      • faxdetect - R/W Fax Detect
        Returns 0 or 1
        Write yes or no

      • t38support - R/W t38support
        Returns 0 or 1
        Write yes or no

      • h323id_url - R/O Returns caller URL

      • caller_h323id - R/O Returns caller h323id

      • caller_dialeddigits - R/O Returns caller dialed digits

      • caller_email - R/O Returns caller email

      • callee_email - R/O Returns callee email

      • callee_dialeddigits - R/O Returns callee dialed digits

      • caller_url - R/O Returns caller URL

      • max_forwards - R/W Get or set the maximum number of call forwards for this channel. This number describes the number of times a call may be forwarded by this channel before the call fails. "Forwards" in this case refers to redirects by phones as well as calls to local channels. Note that this has no relation to the SIP Max-Forwards header.

    • Technology: PJSIP

      • rtp - R/O Retrieve media related information.

        • type - When rtp is specified, the 'type' parameter must be provided. It specifies which RTP parameter to read.

          • src - Retrieve the local address for RTP.

          • dest - Retrieve the remote address for RTP.

          • direct - If direct media is enabled, this address is the remote address used for RTP.

          • secure - Whether or not the media stream is encrypted.

            • 0 - The media stream is not encrypted.

            • 1 - The media stream is encrypted.

          • hold - Whether or not the media stream is currently restricted due to a call hold.

            • 0 - The media stream is not held.

            • 1 - The media stream is held.

        • media_type - When rtp is specified, the 'media_type' parameter may be provided. It specifies which media stream the chosen RTP parameter should be retrieved from.

          • audio - Retrieve information from the audio media stream.

            Note

            If not specified, 'audio' is used by default.

          • video - Retrieve information from the video media stream.

      • rtcp - R/O Retrieve RTCP statistics.

        • statistic - When rtcp is specified, the 'statistic' parameter must be provided. It specifies which RTCP statistic parameter to read.

          • all - Retrieve a summary of all RTCP statistics.
            The following data items are returned in a semi-colon delineated list:

            • ssrc - Our Synchronization Source identifier

            • themssrc - Their Synchronization Source identifier

            • lp - Our lost packet count

            • rxjitter - Received packet jitter

            • rxcount - Received packet count

            • txjitter - Transmitted packet jitter

            • txcount - Transmitted packet count

            • rlp - Remote lost packet count

            • rtt - Round trip time

            • txmes - Transmitted Media Experience Score

            • rxmes - Received Media Experience Score

          • all_jitter - Retrieve a summary of all RTCP Jitter statistics.
            The following data items are returned in a semi-colon delineated list:

            • minrxjitter - Our minimum jitter

            • maxrxjitter - Our max jitter

            • avgrxjitter - Our average jitter

            • stdevrxjitter - Our jitter standard deviation

            • reported_minjitter - Their minimum jitter

            • reported_maxjitter - Their max jitter

            • reported_avgjitter - Their average jitter

            • reported_stdevjitter - Their jitter standard deviation

          • all_loss - Retrieve a summary of all RTCP packet loss statistics.
            The following data items are returned in a semi-colon delineated list:

            • minrxlost - Our minimum lost packets

            • maxrxlost - Our max lost packets

            • avgrxlost - Our average lost packets

            • stdevrxlost - Our lost packets standard deviation

            • reported_minlost - Their minimum lost packets

            • reported_maxlost - Their max lost packets

            • reported_avglost - Their average lost packets

            • reported_stdevlost - Their lost packets standard deviation

          • all_rtt - Retrieve a summary of all RTCP round trip time information.
            The following data items are returned in a semi-colon delineated list:

            • minrtt - Minimum round trip time

            • maxrtt - Maximum round trip time

            • avgrtt - Average round trip time

            • stdevrtt - Standard deviation round trip time

          • all_mes - Retrieve a summary of all RTCP Media Experience Score information.
            The following data items are returned in a semi-colon delineated list:

            • minmes - Minimum MES based on us analysing received packets.

            • maxmes - Maximum MES based on us analysing received packets.

            • avgmes - Average MES based on us analysing received packets.

            • stdevmes - Standard deviation MES based on us analysing received packets.

            • reported_minmes - Minimum MES based on data we get in Sender and Receiver Reports sent by the remote end

            • reported_maxmes - Maximum MES based on data we get in Sender and Receiver Reports sent by the remote end

            • reported_avgmes - Average MES based on data we get in Sender and Receiver Reports sent by the remote end

            • reported_stdevmes - Standard deviation MES based on data we get in Sender and Receiver Reports sent by the remote end

          • txcount - Transmitted packet count

          • rxcount - Received packet count

          • txjitter - Transmitted packet jitter

          • rxjitter - Received packet jitter

          • remote_maxjitter - Their max jitter

          • remote_minjitter - Their minimum jitter

          • remote_normdevjitter - Their average jitter

          • remote_stdevjitter - Their jitter standard deviation

          • local_maxjitter - Our max jitter

          • local_minjitter - Our minimum jitter

          • local_normdevjitter - Our average jitter

          • local_stdevjitter - Our jitter standard deviation

          • txploss - Transmitted packet loss

          • rxploss - Received packet loss

          • remote_maxrxploss - Their max lost packets

          • remote_minrxploss - Their minimum lost packets

          • remote_normdevrxploss - Their average lost packets

          • remote_stdevrxploss - Their lost packets standard deviation

          • local_maxrxploss - Our max lost packets

          • local_minrxploss - Our minimum lost packets

          • local_normdevrxploss - Our average lost packets

          • local_stdevrxploss - Our lost packets standard deviation

          • rtt - Round trip time

          • maxrtt - Maximum round trip time

          • minrtt - Minimum round trip time

          • normdevrtt - Average round trip time

          • stdevrtt - Standard deviation round trip time

          • local_ssrc - Our Synchronization Source identifier

          • remote_ssrc - Their Synchronization Source identifier

          • txmes - Current MES based on us analyzing rtt, jitter and loss in the actual received RTP stream received from the remote end. I.E. This is the MES for the incoming audio stream.

          • rxmes - Current MES based on rtt and the jitter and loss values in RTCP sender and receiver reports we receive from the remote end. I.E. This is the MES for the outgoing audio stream.

          • remote_maxmes - Max MES based on data we get in Sender and Receiver Reports sent by the remote end

          • remote_minmes - Min MES based on data we get in Sender and Receiver Reports sent by the remote end

          • remote_normdevmes - Average MES based on data we get in Sender and Receiver Reports sent by the remote end

          • remote_stdevmes - Standard deviation MES based on data we get in Sender and Receiver Reports sent by the remote end

          • local_maxmes - Max MES based on us analyzing the received RTP stream

          • local_minmes - Min MES based on us analyzing the received RTP stream

          • local_normdevmes - Average MES based on us analyzing the received RTP stream

          • local_stdevmes - Standard deviation MES based on us analyzing the received RTP stream

        • media_type - When rtcp is specified, the 'media_type' parameter may be provided. It specifies which media stream the chosen RTCP parameter should be retrieved from.

          • audio - Retrieve information from the audio media stream.

            Note

            If not specified, 'audio' is used by default.

          • video - Retrieve information from the video media stream.

      • endpoint - R/O The name of the endpoint associated with this channel. Use the PJSIP_ENDPOINT function to obtain further endpoint related information.

      • contact - R/O The name of the contact associated with this channel. Use the PJSIP_CONTACT function to obtain further contact related information. Note this may not be present and if so is only available on outgoing legs.

      • aor - R/O The name of the AOR associated with this channel. Use the PJSIP_AOR function to obtain further AOR related information. Note this may not be present and if so is only available on outgoing legs.

      • pjsip - R/O Obtain information about the current PJSIP channel and its session.

        • type - When pjsip is specified, the 'type' parameter must be provided. It specifies which signalling parameter to read.

          • call-id - The SIP call-id.

          • secure - Whether or not the signalling uses a secure transport.

            • 0 - The signalling uses a non-secure transport.

            • 1 - The signalling uses a secure transport.

          • target_uri - The contact URI where requests are sent.

          • local_uri - The local URI.

          • local_tag - Tag in From header

          • remote_uri - The remote URI.

          • remote_tag - Tag in To header

          • request_uri - The request URI of the incoming 'INVITE' associated with the creation of this channel.

          • t38state - The current state of any T.38 fax on this channel.

            • DISABLED - T.38 faxing is disabled on this channel.

            • LOCAL_REINVITE - Asterisk has sent a 're-INVITE' to the remote end to initiate a T.38 fax.

            • REMOTE_REINVITE - The remote end has sent a 're-INVITE' to Asterisk to initiate a T.38 fax.

            • ENABLED - A T.38 fax session has been enabled.

            • REJECTED - A T.38 fax session was attempted but was rejected.

          • local_addr - On inbound calls, the full IP address and port number that the 'INVITE' request was received on. On outbound calls, the full IP address and port number that the 'INVITE' request was transmitted from.

          • remote_addr - On inbound calls, the full IP address and port number that the 'INVITE' request was received from. On outbound calls, the full IP address and port number that the 'INVITE' request was transmitted to.

Generated Version

This documentation was generated from Asterisk branch 21 using version GIT