The DTMFPlayer property

class DTMFPlayer

A class that provides an API for playing DTMF tones.

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

class Cause

Once a play job has ended and the play state has returned to idle or error, the cause will be one of these.

Play termination causes are:

ERROR

play has stopped due to an error.

NORMAL

play has stopped normally.

HANGUP

play ended due to a call hang-up.

TIMEOUT

play failed because a timer has expired.

NONE

play is in progress, or no play has occurred.

Usage example:

state = channel.DTMFPlayer.state()
if state != channel.DTMFPlayer.State.PLAYING:
    cause = channel.DTMFPlayer.cause()
    if cause == channel.DTMFPlayer.Cause.NORMAL:
        # DTMF replay finished normally
        pass

class State

The play state can be checked to determine whether a DTMF play job is in progress. When a play job ends, the play termination cause can be checked to find the reason why.

Play states are:

PLAYING

a play job is in progress.

IDLE

no play job is in progress.

ERROR

a play job failed.

Usage example:

state = channel.DTMFPlayer.state()
if state == channel.DTMFPlayer.State.ERROR:
    # a DTMF replay job failed due to an error.
    pass

cause()

This function will return a cause.

When a particular job terminates, the reason why can be requested by calling this function.

If this function is called while a job is still running, the cause will be NONE.

play(digits)

This function will send DTMF characters.

Required argument:

• digits

  the digit string to send.

This function will send the DTMF characters supplied by the string digits, each of which may be any one of the set 0123456789ABCD*# or a comma.

Each comma will delay the subsequent digits by half a second.

Note that the DTMF digits you play may be eliminated by some parts of the telephone network. If you’d like to play a general purpose beep to the far end, consider using the TonePlayer or playing a WAV file.

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

If the play state is already PLAYING, this function will raise an Error exception.

If the call channel already has an external audio source, e.g, it is connected to another call channel, this function will raise an Error exception.

The maximum length allowed for the digit string is 32. If a longer string is given, this function will raise an Error exception.

If the digit string contains an invalid character, this function will raise an Error exception.

The function will block until the digits have been sent or a timeout has expired.

Upon return, this function will return a termination cause.

Usage example:

cause = channel.DTMFPlayer.play(digits='1234#')

state()

This function will return the current state.

When a particular job is busy, its state can be tracked by calling this function.

If this function is called while when no job is in progress, the state will be IDLE.