The DTMFPlayer property

class DTMFPlayer

A class that provides an API for playing DTMF tones.

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 hangup.

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 DTMFPlayer.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

DTMFPlayer.cause()

This function will return a cause.

When a play job terminates, the reason why can be requested by calling this function. If this function is called while a play job is still running, the cause will be NONE.

DTMFPlayer.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*#.

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 timout has expired.

Upon return, this function will return a termination cause.

Usage example:

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

DTMFPlayer.state()

This function will return the current state.

When a play job is busy, its state can be tracked by calling this function. If this function is called while when no play job is in progress, the state will be IDLE.