Call channel settings and states¶

The call channel settings and states are accessed through the following exposed properties:

State
Cause
TransferCause
CallFarEndType
LiveSpeakerDetectionSettings
ConferenceLifetimeControl
ConferencePartyMediaSettings

class UASCallChannel¶

class State¶

The call states can be used to track the progress of a particular call. Once a call has hung up, the call cause can be checked to find the reason why.

Call states:

WAITING: waiting for an incoming call.
CALL_INCOMING: an incoming call has been detected.
RING_INCOMING: an incoming call is ringing.
ANSWERING: an incoming call is being answered.
ANSWERED: a call has been answered.
CALL_OUTGOING: an outbound call has been placed.
RING_OUTGOING: an outbound call is ringing.
HOLDING: a call is being placed on hold.
ON_HOLD: a call is on hold
TRANSFERRING: a call is being transferred
TRANSFERRED: a call has been transferred
RECONNECTING: a previously transferred call is being retrieved
ERROR: the call channel is in an error state.
IDLE: the call channel is idle, assumed to be due to a hangup.

Usage example:

state = channel.call('sip:1234@127.0.0.1:5060;user=phone')
if state != channel.State.ANSWERED:
    # might be busy
    pass

class UASCallChannel.Cause¶

Once a call has hung up the call state will return to IDLE and the clearing cause will be one of these.

If an incoming call is rejected, a subset of these causes can be given as the cause for the rejection in the reject function.

Call clearing causes:

TIMEOUT: a timeout has happened whilst waiting for a call event.
ERROR: an error has caused the call to clear.
NORMAL: a normal hangup.
BUSY: the destination address acknowledged the connection request, but is unable to accept the call because it is in use.
NOANSWER: the destination responded to the connection request, but failed to complete the connection within the prescribed time.
UNOBTAINABLE: the destination address is unobtainable.
CHANGED: the destination address is no longer assigned in the system.
OUTOFORDER: the destination cannot be reached because the interface to the destination is not functioning correctly and a signalling message cannot be delivered to the remote equipment. It may be a temporary condition, but it could last for an extended period of time. It may indicate that the remote equipment is turned off.
BARRED: the destination cannot be reached because incoming calls are barred.
REJECTED: the destination is capable of accepting the call and is not busy. The call is rejected for an unknown reason.
NOCHANNELS: there are no appropriate circuits/channels presently available to handle the call.
CONGESTION: the destination cannot be reached becaused the network is experiencing a period of high traffic.
FAILED: the call failed. A raw cause is indicated in CallChannel.Details.raw_cause.
OTHER: the call cleared for an undefined reason. A raw cause is indicated in CallChannel.Details.raw_cause.

Usage example:

state = channel.call('sip:3301@127.0.0.1:5060;user=phone')
if state != channel.State.ANSWERED:
    if channel.cause() == channel.Cause.BUSY:
        print("Busy, try again")

class UASCallChannel.TransferCause¶

Calling any of the transfer functions results in one of these transfer causes being set.

Transfer causes:

NONE: no transfer cause is currently available, no transfer function has yet been called, or one has but hasn’t yet finished
NORMAL: the call was transferred successfully.
TIMEOUT: the transfer took longer than allowed to complete.
HANGUP: the call being transferred was hung up before transfer occurred.
TARGETREJECT: the transfer target rejected the call, for example it may have been busy.
TARGETHANGUP: the transfer target was hung up before transfer occurred.
FAIL: the transfer failed.

Usage example:

ret = channel.managed_transfer('sip:3301@127.0.0.1:5060;user=phone')
if res is False:
    if channel.transfer_cause() == channel.TransferCause.TARGETREJECT:
        print("Busy, try again later")

class UASCallChannel.CallFarEndType¶

The call connection type indicates whether the connection is probably to a live speaker or to a machine. The far end type is returned in the call details.

Call connection types:

LIVE: probably connected to a live speaker.
ANSWER_MACHINE: probably connected to a answering machine.
FAX_MACHINE: probably connected to a fax machine.
UNKNOWN: the classification could not be made in time. This is also the default setting.

Usage example:

state = channel.call('sip:1234@127.0.0.1:5060;user=phone'
                     live_speaker_detect=channel.LiveSpeakerDetectionSettings.DEFAULT)
if state == channel.State.ANSWERED:
    # might be a fax machine
    if channel.Details.far_end_type == channel.CallFarEndType.FAX_MACHINE:
        pass

class UASCallChannel.LiveSpeakerDetectionSettings¶

The type of live speaker detection to use, used when placing and outbound call. The default option is DEFAULT. Live speaker detection is used in conjuntion with a timeout, lsd_timeout_milliseconds, which determines how long to wait for the live speaker detection algorithm to categorise the call.

Live speaker detection types:

The value below determines the point in the call at which live speaker detection is carried out, and hence from what point the lsd_timeout_milliseconds argument is measured.

DEFAULT: Use default settings to detect whether the call is answered by a live speaker or not. The timer begins as soon as the network reports that the call is connected.
TIMEOUT_FROM_NETWORK_CONNECT: The same as DEFAULT.
TIMEOUT_FROM_ANSWER_DETECT: The same as DEFAULT except that the timer begins once the call has been answered. The live speaker detection algorithm attempts to cater for automated call tones that may be generated in advance of a callee actually answering the call. For example, a common scenario is where a PBX connects then plays a ringing tone until the call is answered.

Usage example:

state = channel.call('sip:1234@127.0.0.1:5060;user=phone'
                     live_speaker_detect=channel.LiveSpeakerDetectionSettings.DEFAULT)
if state == channel.State.ANSWERED:
    # might be a fax machine
    if channel.Details.far_end_type == channel.CallFarEndType.FAX_MACHINE:
        pass

class UASCallChannel.ConferenceLifetimeControl(start_on_entry=True, destroy_on_exit=False)¶

Conference lifetime control. The options are to start the conference when the caller enters the conference room, and to destroy the conference room when the caller exits the room.

Optional arguments:

start_on_entry:

whether the conference should start when this party enters the room. Default is True.
destroy_on_exit:

whether the conference room should be destroyed when this party exits the room. Default is False.

The argument start_on_entry indicates whether the conference should start when this party enters the room. All other callers will hear a ring tone until the conference has started. So, if only one participant can cause the conference to start, all others will hear ringing (and not be able to talk to each other) until he enters the room.

Usage example:

conf_media_settings = channel.ConferencePartyMediaSettings(exit_on_dtmf_digit='#')
conf_media_settings.MuteOnDTMFDigits.set_digits(mute='0', unmute='1')
conf_media_settings.PrefixMedia.text_to_say('george')
conf_media_settings.OnEntryMedia.text_to_say('has joined')
conf_media_settings.OnExitMedia.text_to_say('has left')

conf_lifetime_settings = channel.ConferenceLifetimeControl(start_on_entry=True, destroy_on_exit=True)

if channel.transfer_to_conference_room(other_call, conference_room_name,
                                       conference_lifetime_control=conf_lifetime_settings,
                                       conference_party_media_settings=conf_media_settings) != channel.State.TRANSFERRED:
    print("could not transfer the call to the conference")

class UASCallChannel.ConferencePartyMediaSettings(ringback_tone=None, on_conference_stopped_file=None, beep_on_entry=True, exit_on_dtmf_digit=None, two_party_optimisation=False)¶

Conference media control. This class defines several parameters that let you fine-tune the behaviour of your conference.

Optional arguments:

ringback_tone:

to play a tone to the party while waiting to enter the conference room. Default is RINGBACK.
on_conference_stopped_file:

on the party entering a conference room, play a file (in an endless loop) until the conference has started.
beep_on_entry:

option to play a beep to the conference when this party enters. Default is True.
exit_on_dtmf_digit:

option to leave the conference by hitting a DTMF digit. Default is None which disables this option.
two_party_optimisation:

If True, indicates that the conference room that this party is entering should be optimised for two talking parties. If the conference room will not have more than two talkers, then having optimisation turned on will enhance the quality of the audio. Other parties can enter as listeners without affecting the optimisation. This option should not be used if more than two talking parties will be entering the conference room as this can have adverse affects on the audio quality. Default is False.

The argument ringback_tone defines the audio played to the party while waiting to enter the conference room. Valid options for ringback_tone are listed in the ToneManager resource; or the argument can be left at its default value.

This class exposes the public properties OnEntryMedia, OnExitMedia and PrefixMedia which are classes of the type PlayableMedia. Use the functions provided by PlayableMedia to set some audio to play on entering and leaving the conference room. The audio can be either some text to say as TTS or the name of a file. The audio provided by PrefixMedia will be played before OnEntryMedia and after OnExitMedia.

This class exposes the public propery MuteOnDTMFDigits to optionally set DTMF digits for muting and unmuting a party when the corresponding digit is pressed.

Usage example:

conf_media_settings = channel.ConferencePartyMediaSettings(exit_on_dtmf_digit='#')
conf_media_settings.MuteOnDTMFDigits.set_digits(mute='0', unmute='1')
conf_media_settings.PrefixMedia.text_to_say('george')
conf_media_settings.OnEntryMedia.text_to_say('has joined')
conf_media_settings.OnExitMedia.text_to_say('has left')

conf_lifetime_settings = channel.ConferenceLifetimeControl(start_on_entry=True, destroy_on_exit=True)

if channel.transfer_to_conference_room(other_call, conference_room_name,
                                       conference_lifetime_control=conf_lifetime_settings,
                                       conference_party_media_settings=conf_media_settings) != channel.State.TRANSFERRED:
    print("could not transfer the call to the conference")

class CMuteControl¶

Conference mute control. Allows the user to set the DTMF digits that will mute or unmute the party.

set_digits(mute, unmute=None)¶: Two DTMF characters can be supplied. The set of individual DTMF digits permitted is: 1234567890*#. If unmute is not supplied, it will be the same digit as mute.

class UASCallChannel.ConferencePartyMediaSettings.CPlayableMedia¶

Conference media parameters. The options are to set the name of a file to play, or to set some text to speak using TTS.

The public properties OnEntryMedia, OnExitMedia and PrefixMedia are of this type.

file_to_play(filename)¶

Set a file name to play.

Setting this option will replace any options that may have been previously set by text_to_say.

text_to_say(text)¶

Set some text to say as TTS. The | (pipe) character is not permitted.

Setting this option will replace any options that may have been previously set by file_to_play.

Call channel settings and states¶

Previous topic

Next topic

Navigation

Call channel settings and states¶

Previous topic

Next topic

Quick search

Navigation