ringΒΆ

class UASCallChannel
ring(seconds_ringtime=0, negotiate_early_media=False, custom_ringtone=None, loop_ringtone=False, codecs=None)

Signal a ringing indication.

Optional argument:
  • seconds_ringtime

    specifies the amount of time to ring. Default is 0.

  • negotiate_early_media

    negotiate early media if available. Default is False.

  • custom_ringtone

    a tone name or a PlayableMedia object to play if early media is negotiated. Default is None.

  • loop_ringtone

    continuously loop the file to play. Default is False.

  • codecs

    the codecs to offer on this call. Default is None (use the default).

This function signals a ringing indication to the far end. Or, if early media is negotiated, it can play a custom ringtone which is supplied as a PlayableMedia object or a tone name.

seconds_ringtime specifies the amount of time to ring.

If it is 0, this function will not block.
If it is None, it will block for the duration of custom_ringtone.
If it is greater than 0, it will block for the specified number of seconds.

use_early_media will negotiate Early Media if it is available.

If Early Media is not available or is False, custom_ringtone will be ignored.
If Early Media is not available or is False and seconds_ringtime is None, seconds_ringtime=0 will be used instead.

custom_ringtone specifies the ringtone to play if Early Media is negotiated.

If it is of type PlayableMedia, it specifies a file to play or some text to say.
If a string is given, it is a tone name. For the channel to play a tone it must have a tone player object. The tone must be known to the tone manager passed when creating the tone player object.
If None, then nothing is played.

loop_ringtone, if True, will cause custom_ringtone playback to be played in a loop.

If seconds_timeout is None, loop_ringtone will be set to False.

For SIP calls, codecs is an optional parameter to specify a semi-colon delimited list (in priority order) of codecs to offer for the call; for example, g711a;g711u. Please see the documentation for protocols and formats.

This function should be called when the call is in the CALL_INCOMING state, however, it is safe to call it if the state is already RING_INCOMING.

If this function is called when the call state is IDLE, it will raise a Hangup exception; otherwise, if the call state is not CALL_INCOMING or RING_INCOMING it will raise an Error exception.

After ringing successfully, the call state will be set to RING_INCOMING.

This function will return the current call state.

Usage example:

# an incoming call is detected
if channel.state() == channel.State.CALL_INCOMING:
    # we have a call, ring for a second
    state = channel.ring(1)
    if state == channel.State.RING_INCOMING:
        # after ringing, answer the call
        channel.answer()

Usage example with Early Media:

# an incoming call is detected
if channel.state() == channel.State.CALL_INCOMING:
    # we have a call, create and play a custom ring tone
    my_ring_tone = PlayableMedia(text_to_say="Thank you for calling.", channel=channel)
    state = channel.ring(seconds_ringtime=None,        # to block for the duration of the text
                         negotiate_early_media=True,   # to negotiate early media, if available
                         custom_ringtone=my_ring_tone) # the media object to play is Early Media is negotiated
    if state == channel.State.RING_INCOMING:
        # after the first Early Media message, we can play another one
        my_next_ring_tone = PlayableMedia(file_to_play="some_music.wav", channel=channel)
        channel.ring(seconds_ringtime=10,               # play for ten seconds
                     custom_ringtone=my_next_ring_tone) # the media to play
        channel.answer()