The DTMFDetector property

class DTMFDetector

A class that provides an API for detecting DTMF digits.

The call channel object uses this class to provide DTMF detection functionality. The call channel object has a public property called DTMFDetector of this type. Please see the tutorial for examples on how to use this class.

class Cause

Once a DTMF detect job has ended, the cause will be one of these.

DTMF detect termination causes:

HANGUP

DTMF detection terminated due to a call hang-up

COUNT

the required number of DTMF digits has been received.

END

the end DTMF digit has been recognised.

TIMEOUT

a timeout has occurred whilst waiting for DTMF.

ERROR

an error occurred during DTMF detection.

NONE

DTMF digit collection is in progress, or has not yet occurred.

Usage example:

dtmf = channel.DTMFDetector.get_digits(count=5,
                                       seconds_predigits_timeout=30,
                                       seconds_interdigit_timeout=1)
cause = channel.DTMFDetector.cause()
if cause == channel.DTMFDetector.Cause.COUNT:
    # DTMF detection terminated because the required
    # number of digits has been returned.
    pass
cause()

Return the current cause.

clear_digits()

Clear the DTMF buffer.

DTMF digits that are already present in the DTMF digit buffer will not trigger a barge-in on record or play jobs. Barge-in is activated on the media server, it is not done in the Python API. It is therefore not necessary to call this function before starting a record or play job that has barge-in enabled.

When re-using a call channel object between calls, the digit buffer is automatically cleared between calls.

get_digits(clear=False, count=0, seconds_predigits_timeout=0, seconds_interdigit_timeout=5, end=None, seconds_timeout=None)

Returns a string containing any DTMF digits collected.

Optional arguments:
  • clear

    clear the DTMF buffer. Default is False.

  • count

    number of DTMF digits to get. Default is 0 (no limit).

  • seconds_predigits_timeout

    maximum time allocated to wait for first digit. Default is 0 seconds (return immediately). None - signifies that this timeout is disabled.

  • seconds_interdigit_timeout

    maximum time allocated to wait between digits. Default is 5 seconds. None - signifies that this timeout is disabled.

  • end

    string of end-digits. Default is None.

  • seconds_timeout

    maximum overall time allocated to wait for sufficient digits and/or end digit

By default, this function simply returns a string containing the DTMF digits already detected and present in the digit buffer. If this happens, the cause will remain NONE.

DTMF digits that may be received are the complete set, comprising 0123456789ABCD*#.

If the call channel state is IDLE when this function is called, it will raise a Hangup exception. If the call channel state is not IDLE but also not ANSWERED, this function will raise an Error exception.

If clear is set to True, this function will clear the DTMF buffer of any digits before waiting for the first digit. Please note that DTMF detection is active throughout the lifetime of a call, the implication being that DTMF digits can be added to the digit buffer at any time, not just when this function is active. It is also important to note that digits that are already in the digit buffer will not trigger a barge-in on a play or record job.

If digits are supplied in the end string (e.g. end = "*#") and one of these is encountered, the digits that have already been collected will be returned, along with the detected end digit; and a cause of END will be given. The valid set of end digits is 0123456789ABCD*#, if any other digit is given this function will raise an Error exception.

If count is set to an integer value greater than 0, this function will block until that number of digits has been collected, or a timeout occurs. Upon success, the digits will be returned along with a cause of COUNT. If count is 0, the maximum number of digits will be collected, currently the maximum is 32. If count is set to a value greater than 32, this function will raise an Error exception.

Note that count and end can be set at the same time, whichever condition is met first will cause the function to return. In the event of a tie, END will be the cause.

If seconds_predigits_timeout is not None or 0, this function will return with cause TIMEOUT if that time has expired while waiting for the first DTMF digit. If this timeout is zero, the function will work on the digits that are already present in the DTMF buffer, but it will not wait for any new digits. Set this to None to have an infinite timeout.

If seconds_interdigit_timeout is not None or 0, this function will return with cause TIMEOUT (and any digits already received) if that time has expired between digits. This timeout restarts every time a digit is detected. Set this to None to have an infinite timeout, set to zero to return immediately.

If a hang-up occurs whilst waiting for DTMF digits, this function will return any digits already collected with the cause HANGUP.

The digits that are returned are automatically removed from the digit buffer.

Usage example:

# Collect five DTMF digits. Maximum wait between digits is 1 second.
# Maximum wait for first digit is 30 seconds.
dtmf = channel.DTMFDetector.get_digits(count=5, seconds_predigits_timeout=30,
                                       seconds_interdigit_timeout=1)