Signal a ringing indication.
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.
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 is of type PlayableMedia, i.e. a file to play or some text to say.
This will be played if Early Media is negotiated.
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()