The call channel methods are:
Make a call.
the call destination.
the origin of this call. Required for PSTN calls.
time allocated to make the call. Default is 120. None means no timeout.
list of codecs to use on this call. Default is None (use the default).
live speaker detection settings. Default is None.
live speaker detection timeout. Default is 2000.
This is the function used to place an outbound call to the destination call_to. For details on specifying PSTN or SIP destinations please see the documentation for outbound calls on the CWP.
The originating address call_from is compulsory for PSTN calls. In order to ensure appropriate use of Aculab’s outbound PSTN providers, for all outbound PSTN calls placed through them we check that the call from is in your list of validated Caller ID numbers, and will fail call attempts where it’s not. Please see the documentation for outbound calls on the CWP.
If seconds_timeout is not None, a timeout will apply for making the call. The call is abandoned if the timeout is reached and the call has not been made. The default is 120 seconds.
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 on the CWP.
The option live_speaker_detect allows the user to enable a live speaker detection algorithm. This algorithm will indicate whether the call was answered by a live speaker, or by a machine. Look here for the options on enabling live speaker detection, and here for the detection result types.
This function will block until the call has been answered, the timeout has been reached, or the call state has returned to IDLE.
This function should be called when the call state is IDLE; otherwise, it will raise an Error exception.
This function will return the current call state.
Usage example PSTN:
state = channel.call("tel:441908273800", call_from="441234567890")
if state != channel.State.ANSWERED:
# check whether the call was rejected due to BUSY
if state == channel.Cause.BUSY:
# do something here for busy calls
pass
else:
# the call has been answered, carry on
pass
The are a number of rules that go with making outbound PSTN calls. Please read the information provided on the Aculab Cloud website.
Usage example SIP:
state = channel.call('sip:3301@127.0.0.1:5060;user=phone', call_from='bob@1234')
if state != channel.State.ANSWERED:
# check whether the call was rejected due to BUSY
if state == channel.Cause.BUSY:
# do something here for busy calls
pass
else:
# the call has been answered, carry on
pass
Start making an outbound call.
the call destination.
the origin of this call. Required for PSTN calls.
list of codecs to use on this call. Default is None (use the default).
live speaker detection settings. Default is None.
live speaker detection timeout. Default is 2000.
This is the function used to begin placing an outbound call to the destination call_to. For details on specifying PSTN or SIP destinations please see the documentation for outbound calls on the CWP.
The originating address call_from is compulsory for PSTN calls. In order to ensure appropriate use of Aculab’s outbound PSTN providers, for all outbound PSTN calls placed through them we check that the call from is in your list of validated Caller ID numbers, and will fail call attempts where it’s not. Please see the documentation for outbound calls on the CWP.
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 on the CWP.
The option live_speaker_detect allows the user to enable a live speaker detection algorithm. This algorithm will indicate whether the call was answered by a live speaker, or by a machine.
This function will block until an acknowledgement has been received that the call has started, or a timeout occurs. If the timeout does occur, the function will return False and the call cause will be TIMEOUT.
This function should be called when the call state is IDLE; otherwise, it will raise an Error exception.
This function will return True on success, else False.
Usage example:
if channel.start_call('sip:3301@127.0.0.1:5060;user=phone', call_from='bob@1234') is True:
# we have started an outbound call
pass
Wait for an outbound call to be answered.
time allocated to wait for the ANSWERED state. Default is 120 seconds.
if True, this function will return when the call is in the RING_OUTGOING state, otherwise it will wait until it is connected.
This is the function used to wait for an outbound call, which was started using the start_call function, to go to the ANSWERED or RING_OUTGOING state.
This function will block until the call has been connected, the timeout has been reached, or the call state has returned to IDLE. If seconds_timeout is None, this function will not time out.
This function should be called when the call state is CALL_OUTGOING, however, it is also safe to call it if the state is already ANSWERED or RING_OUTGOING; any other state will cause this function to raise an Error exception.
This function will return the current call state.
Usage example:
state = channel.start_call('sip:3301@127.0.0.1:5060;user=phone')
if state == channel.State.CALL_OUTGOING:
# do some other processing
if channel.wait_for_outgoing_call() != channel.State.ANSWERED:
# not answered, could be timeout or IDLE
pass
Wait until an answering machine is ready to record.
- milliseconds_min_beep_duration
the minimum duration of a beep for it to be recognised. Default value is 180ms.
- milliseconds_post_beep_silence
the period of silence after a beep. Default value is 1000ms.
- milliseconds_no_beep_silence
the period of silence without a beep Default value is 4000ms.
- seconds_timeout
the amount of time allocated to wait for the answer machine to be ready. None means no timeout. Default is 10 seconds.
This method looks for a combination of beeps and silence to identify a suitable moment at which to begin playing a file to an answering machine. Further details on playing files are available here.
This function should only be used when the far end has been identified as an answering machine, for more information on this go here.
The dafault values for this function will cause it to return True if one of the following is true:
- A beep at least 180 milliseconds long is followed by a 1000 millisecond silence.
- An uninterrupted 4000 millisecond silence is heard.
If neither of the above is true within the seconds_timeout limit, this function will return False.
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.
This function will block until confirmation has been received that the answer machine is ready to record or a timeout has expired.
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 an answer machine
if channel.Details.far_end_type == channel.CallFarEndType.ANSWER_MACHINE:
# play a message to the answer machine
if channel.wait_for_answer_machine() is True:
cause = channel.FilePlayer.play('my_message')
# NOTE: the file to play must not have any leading silence
# as the answer machine may hang up the call on silence
# detection, it is up to the user to trim leading silence.
Upon success, this function will return True, else False.
Signal a ringing indication.
the duration of the ring tone. Default is 2 seconds.
This function signals a ringing indication to the far end (it does not actually supply in-band ringtone).
If seconds_ringtime is greater than zero (it may be an integer or a float) this function will block for the duration.
This function must be called when the call is in the CALL_INCOMING state.
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 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
state = channel.answer()
if state != channel.State.ANSWERED:
# it may already have gone to IDLE
pass
Answer a call.
the codecs to offer on this call. Default is None (use the default).
The list of codecs offered by the incoming call can be retrieved by looking at Details after an incoming call has been detected. One or more of these codecs can be chosen and offered here in a semi-colon delimited list (in priority order) of codec names; for example, g711a;g711u.
This function should be called when the call state is CALL_INCOMING or RING_INCOMING. If, when the function is called, the call state is IDLE, it will raise a Hangup exception; otherwise, if called whilst in an inappropriate state, this function will raise an Error exception.
This function will block until the call is in the ANSWERED state (which is normally only an extremely short delay), a timeout has been reached, or the call state has returned to IDLE. If the call does timeout, the call will be abandoned. If the call state returns to IDLE, a Hangup exception will be raised.
This function will return the current call state.
Usage example:
state = channel.answer() # answer the call
if state != channel.State.ANSWERED:
raise Hangup('state is {0}'.format(state))
Hang up a call.
This function causes a currently connected call (a call that is not IDLE) to be released. It is safe to call this function on a channel that is already IDLE.
The NORMAL clearing cause will be used. This function will block until the call is actually cleared and the call state has returned to IDLE, or a timeout has been reached. The timeout for this function is 60 seconds.
Note that an inbound call might take quite a while to clear, as it is only actually fully released when the caller hangs up (or the network times out waiting for the caller to do so). Accordingly, if this function times out, the call channel will still not be available for another call until after the call state has returned to IDLE. The application can wait for this by calling the wait_for_idle function.
This function will return the current call state.
Usage example:
# hangup the call
if channel.hang_up() != channel.State.IDLE:
# wait for channel to go to idle
channel.wait_for_idle()
Reject up a call.
clearing cause. Default is REJECTED.
raw clearing cause. Default is None.
This function causes a currently connected call to be released, or an incoming call to be rejected.
Default behaviour is for the REJECTED clearing cause to be used. The other valid options are:
- BUSY
- NOANSWER
- UNOBTAINABLE
- CHANGED
- OUTOFORDER
- BARRED
- REJECTED
- NOCHANNELS
- CONGESTION
A raw_cause clearing cause, in the form of a string, may be supplied. This gives the opportunity to send a message that is specific to the underlying call control protocol, e.g., SIP. This will override cause.
See the relevant SIP documentation for a list of clearing causes and their meanings.
This function will block until the call is actually cleared and the call state has returned to IDLE. This function will wait 60 seconds for the call state to return to IDLE.
Note that an inbound call might take quite a while to clear, as it is only actually fully released when the caller hangs up (or the network times out waiting for him to do so). Accordingly, if this function times out, the call channel will still not be available for another call until after the call state has returned to IDLE. The application can wait for this by calling the wait_for_idle function.
Please note that SIP redirection is not supported, so raw causes in the 300 range cannot be used. The call reject will fail with channel.State.ERROR if a raw cause is supplied which is not supported. And the user should send a different reject message.
This function will return the current call state.
Usage examples:
# reject the call with BUSY
state = channel.reject(cause=channel.Cause.BUSY)
if state != channel.State.IDLE:
# wait for channel to go to idle
channel.wait_for_idle()
# reject the call fails
state = channel.reject(raw_cause=301)
if state != channel.State.IDLE:
if state == channel.State.ERROR:
channel.reject()
# wait for channel to go to idle
channel.wait_for_idle()
Wait until the call has returned to IDLE.
time allocated to wait for the call to go to IDLE. Default is 120 seconds.
This function will block until the call state has returned to IDLE, or the timeout has expired.
This function will not raise a Hangup exception.
This function will return the call state. If the returned value is not IDLE, the timeout has occurred.
Setting seconds_timeout to None will allow an infinite wait.
Usage example:
# reject the call with BUSY and then wait for IDLE
if channel.reject(cause=channel.Cause.BUSY) != channel.State.IDLE:
# wait for channel to go to idle
channel.wait_for_idle()
Return the call state.
option to raise a hangup exception on IDLE. Default is False.
This function returns the current call state.
The check_for_hangup parameter is provided as an explicit method of raising a Hangup exception on IDLE.
Usage example:
# reject the call and then and raise a Hangup
# exception on IDLE
try:
if channel.reject(cause=channel.Cause.BUSY) != channel.State.IDLE:
# wait for channel to go to idle
channel.wait_for_idle(None)
# will throw Hangup
channel.state(check_for_hangup=True)
except Hangup:
# call is IDLE
pass
Return the latest call cause.
Usage example:
# place a call. If it does not return ANSWERED try again if the
# cause is BUSY
state = channel.call('sip:3301@127.0.0.1:5060;user=phone')
if state != channel.State.ANSWERED:
if channel.cause() == channel.Cause.BUSY:
# call is busy, wait a minute then try again
time.sleep(60)
state = channel.call('sip:3301@127.0.0.1:5060;user=phone')
Connect two calls together.
an instance of the call channel to which to connect.
This function is used to invoke a full-duplex connection between the lines owned by two active calls.
The argument other_call is an instance of the call channel being connected to the current call. Both channels must be in ANSWERED state. If the local call channel state is IDLE, this function will raise a Hangup exception; otherwise, if either call state is not ANSWERED it will raise an Error exception.
When connected in this manner, the call channels will return the connected call channel ID in the Details property: connected_id = channel.Details.connected_id.
Once connected, the two call channels should be kept alive since quitting either of them will break the connection between the two calls.
While the call channels are connected they are permitted to use receiver functions such as record() and detect_dtmf(); however, they may not use transmitter functions such as play() or play_dtmf(). Additionally, a call channel may not connect if it is part of a conference or if it has been added to a music on hold resource.
If this function is called while either the local or the remote call channel is already transmitting or connected; or if it has already been added to a conference or music on hold; it will raise an Error exception.
This function will block until confirmation has been received that the call channels are connected, or that the connection has failed, or the timeout has expired.
This function will return True if successful, otherwise False.
Usage example:
if channel.connect(channel2) is False:
print("could not connect the calls")
Disconnect two call channels which were previously connected using connect()
An existing connection between the two call channels will be broken.
If the local call channel state is IDLE, this function will raise a Hangup exception (the connection will have been automatically broken).
If there is no connection to break because the remote call has gone to IDLE, this function will simply return True. But, if there is no connection to break because no connection was ever made, or disconnect has already been called, an Error exception will be raised.
This function will block until confirmation has been received that the call channels are disconnected, or that the disconnect has failed, or a timeout has expired.
This function will return True if successful, otherwise False.
Usage example:
if channel.disconnect() is False:
print("could not disconnect the calls")
Perform a retrievable transfer to a new outbound call.
the call channel instance to be used for the outbound leg.
the target for the transfer.
the ringback tone to play when the outbound leg is ringing. Default is RINGBACK.
the amount of time to allow for the transfer to be accomplished. Default is 120 seconds. None means no timeout.
The remote address of the call being transferred.
This function is used to transfer a connected call channel to another destination. This function will allow the application to retain control over the call channel and retrieve it when the transfer is no longer required - for example, when the far end hangs up.
The argument other_call is the call channel instance used for the transfer’s outbound leg. This call channel must be in the IDLE state.
An originating address call_from may be supplied. Setting this parameter to an empty string will result in a default value being used.
The primary channel must be in ANSWERED state. If it is IDLE, this function will raise a Hangup exception; otherwise, if it is not ANSWERED it will raise an Error exception.
The argument ringback_tone is the ringback tone to play when the outbound call channel is in the RING_OUTGOING state. Valid options for ringback_tone are listed in the server’s ToneManager resource. If ringback_tone is None a default tone will be used. For the channel to play a tone it must have a tone player object. It is essential that a tone player is created on the channel before a transfer is attempted.
The argument seconds_timeout is the amount of time allowed for the transfer to be completed. If the timeout is None, no time limit will be imposed.
When successfully transferred in this manner, this call channel will be in the TRANSFERRED state.
If unsuccessful, the cause of the failure can be retrieved from transfer_cause() function.
After the transfer has completed successfully, this channel cannot be used to play or record audio (the audio path is no longer available, it has been transferred), it can be used only to hang up the call or to call either the retrieve_transferred_call function or the wait_for_transferred_call_retrieval function.
This function will block until confirmation has been received that the channel has been transferred, or that the transfer request has failed, or a timeout has expired.
This function will return the channel state.
Usage example:
state = channel.retrievable_transfer(other_call, 'sip:3301@127.0.0.1:5060;user=phone')
if state != channel.State.TRANSFERRED:
cause = channel.transfer_cause()
print("could not transfer the calls, reason is {0}".format(cause))
Retrieve a channel that was transferred using the retrievable_transfer function. The audio path to the channel will be restored.
The channel should be in the TRANSFERRED state. If it is IDLE, this function will raise a Hangup exception.
This function will block until confirmation has been received that the transfer has been broken, or a timeout has expired.
If the call is successfully retrieved, its state will have returned to ANSWERED. If the state does not return to ANSWERED a cause can be retrieved by calling the transfer_cause() function.
This function will return the channel state.
Usage example:
if channel.retrieve_transferred_call() != channel.State.ANSWERED:
cause = channel.transfer_cause()
print("could not retrieve the channel, reason is {0}".format(cause))
the amount of time to wait for the transfer to end. If seconds_timeout is None, there is no timeout. Default is two minutes.
Wait for a call channel that was transferred using the retrievable_transfer function to return to IDLE or ANSWERED.
The channel will return to ANSWERED if the far end hangs up, in which case the audio path to the channel will be restored.
The channel state will go to IDLE if the call is hung up, in which case this function will raise a Hangup exception.
When this function is called, the channel should be in the TRANSFERRED state.
This function will block while the call channel state remains in the TRANSFERRED state or until the timeout expires.
This function will return the channel state. If the channel state is ANSWERED that indicates that the call has been retrieved.
Usage example:
if channel.wait_for_transferred_call_retrieval() == channel.State.TRANSFERRED:
print("wait for transferred call timed out")
Perform a retrievable transfer of an existing call to a named conference room.
the call channel instance to be used for the outbound leg to the conference room.
the name of the conference room to which to add this party
whether the party is allowed to talk, as well as listen, in the conference. Default is True.
whether the conference should start/end when this party enters/leaves.
file and TTS play options, mute options.
the amount of time to wait before the party enters the conference room and the transfer is accomplished. Default is 120 seconds. None means no timeout.
This function is used to transfer a connected call channel to a named conference room, in which parties can talk with each other subject to the arguments, e.g. talker_and_listener provided when each entered.
The argument conference_room_name is the name of the conference room to which to add this party. If the conference room does not exist when this function is called, it will be created. When choosing a name for the conference room, it is strongly advised to choose a new name for each new conference. This avoids various potential issues, for example the case where a caller stays in one conference longer than expected and is suddenly introduced into a supposedly new conference as new callers ring in. The name is a string containing only alpha-numeric characters. It uniquely describes the conference room in the Cloud. Thus, all parties who wish to join a given conference must supply the same conference_room_name, and parties joining other conferences must supply different conference_room_name values.
The argument conference_lifetime_control controls whether the conference starts or stops when this party joins and leaves.
The argument conference_party_media_settings defines the audio that will be played to the conference at various times.
The argument seconds_timeout is the amount of time allowed for the transfer to be completed. If the timeout is None, no time limit will be imposed.
When this function is called, a new outbound call is placed to the named conference room. The call will ring until the conference is started; or until timeout expires or the original call hangs up. Once the conference starts (or if it has already started) the call is answered and the party is transferred to the conference.
This function will block until the call has been successfully transferred to the conference, the call had hung up or seconds_timeout has expired.
The transfer to the conference room is a retrievable transfer which means that the call will be retrieved when it leaves the conference room.
After the transfer has completed successfully, this channel cannot be used to play or record audio (the audio path is no longer available, it has been transferred), it can be used only to hang up the call or to call either the retrieve_transferred_call function or the wait_for_transferred_call_retrieval function.
This function will return the channel state.
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")
else:
channel.wait_for_transferred_call_retrieval()
Return the latest transfer cause.
The transfer causes are described here.
Usage example:
# transfer a call. If it does not succeed, try again if the
# cause is BUSY
ret = channel.managed_transfer('sip:3301@127.0.0.1:5060;user=phone')
if ret is False:
if channel.transfer_cause() == channel.Cause.TARGETREJECT:
# call is busy, wait a minute then try again
time.sleep(60)
ret = channel.managed_transfer('sip:3301@127.0.0.1:5060;user=phone')
Place a call to a named conference room.
the name of the conference room to which to add this party
whether the party is allowed to talk, as well as listen, in the conference. Default is True.
whether the conference should start when this party enters.
file and TTS play options, mute options.
time allocated to make the call. Default is 120. None means no timeout.
This function is used to place a call to a named conference room, in which parties can talk with each other subject to the arguments, e.g. talker_and_listener provided when each entered.
The argument conference_room_name is the name of the conference room to which to add this party. If the conference room does not exist when this function is called, it will be created. When choosing a name for the conference room, it is strongly advised to choose a new name for each new conference. This avoids various potential issues, for example the case where a caller stays in one conference longer than expected and is suddenly introduced into a supposedly new conference as new callers ring in. The name is a string containing only alpha-numeric characters. It uniquely describes the conference room in the Cloud. Thus, all parties who wish to join a given conference must supply the same conference_room_name, and parties joining other conferences must supply different conference_room_name values.
The argument conference_lifetime_control controls whether the conference starts or stops when this party joins and leaves.
The argument conference_party_media_settings defines the audio that will be played to the conference at various times.
The argument seconds_timeout is the amount of time allowed for the call to be made. If the timeout is None, no time limit will be imposed.
When this function is called, a new outbound call is placed to the named conference room. If the named conference does not already exist, it will be created. The call will ring until the conference is started; or until timeout expires or the original call hangs up. Once the conference starts (or if it has already started) the call is answered and the party is transferred to the conference.
This function will block until the call has been answered, the timeout has been reached, or the call state has returned to IDLE.
This function should be called when the call state is IDLE; otherwise, it will raise an Error exception.
This function will return the current call state.
Usage example:
state = channel.call_conference_room(conference_room_name)
if state == channel.State.ANSWERED:
# the call has been answered, we're in the conference room
Start a call to a named conference room.
the name of the conference room to which to add this party
whether the party is allowed to talk, as well as listen, in the conference. Default is True.
whether the conference should start/end when this party enters/leaves.
file and TTS play options, mute options.
This function is used to start a call to a named conference room, in which parties can talk with each other subject to the arguments, e.g. talker_and_listener provided when each entered.
The argument conference_room_name is the name of the conference room to which to add this party. If the conference room does not exist when this function is called, it will be created. When choosing a name for the conference room, it is strongly advised to choose a new name for each new conference. This avoids various potential issues, for example the case where a caller stays in one conference longer than expected and is suddenly introduced into a supposedly new conference as new callers ring in. The name is a string containing only alpha-numeric characters. It uniquely describes the conference room in the Cloud. Thus, all parties who wish to join a given conference must supply the same conference_room_name, and parties joining other conferences must supply different conference_room_name values.
The argument conference_lifetime_control controls whether the conference starts or stops when this party joins and leaves.
The argument conference_party_media_settings defines the audio that will be played to the conference at various times.
When this function is called, a new outbound call is placed to the named conference room. If the named conference does not already exist, it will be created. The call will ring until the conference is started; or until timeout expires or the original call hangs up. Once the conference starts (or if it has already started) the call is answered and the party is transferred to the conference.
This function will block until an acknowledgement has been received that the outgoing call has started, the global timeout has been reached, or the call state has returned to IDLE.
This function should be called when the call state is IDLE; otherwise, it will raise an Error exception.
This function will return True on success, else False.
Usage example:
if channel.start_call_conference_room(conference_room_name) is True:
# the outgoing call has started
# do something and then wait for the call to go to answered
if channel.wait_for_outgoing_call() != channel.State.ANSWERED:
# not answered, could be timeout or IDLE
pass
Make a call to an inbound service name.
the name of the inbound service, as entered on the CWP.
the origin of this call.
time allocated to make the call. Default is 120. None means no timeout.
list of codecs to use on this call. Default is None (use the default).
This is the function used to place an outbound call to an inbound service registered on the CWP. call_to must be a valid inbound service name; for example MyVoicemailRecorder.
An originating address call_from may be supplied. Setting this parameter to an empty string will result in a default value being used.
If seconds_timeout is not None, a timeout will apply for making the call. The call is abandoned if the timeout is reached and the call has not been made. The default is 120 seconds.
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.
This function will block until the call has been answered, the timeout has been reached, or the call state has returned to IDLE.
This function should be called when the call state is IDLE; otherwise, it will raise an Error exception.
This function will return the current call state.
Usage example:
state = channel.call_inbound_service('MyVoicemailRecorder', call_from='bob@1234')
if state != channel.State.ANSWERED:
# check whether the call was rejected due to BUSY
if state == channel.Cause.BUSY:
# do something here for busy calls
pass
else:
# the call has been answered, carry on
pass
Start a call to an inbound service name.
the name of the inbound service, as entered on the CWP.
the origin of this call.
list of codecs to use on this call. Default is None (use the default).
This is the function used to start an outbound call to an inbound service registered on the CWP. call_to must be a valid inbound service name; for example MyVoicemailRecorder.
An originating address call_from may be supplied. Setting this parameter to an empty string will result in a default value being used.
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.
This function will block until the call has started, the timeout has been reached, or the call state has returned to IDLE.
This function should be called when the call state is IDLE; otherwise, it will raise an Error exception.
This function will return True on success, else False.
Usage example:
if channel.start_call('MyVoicemailRecorder', call_from='bob@1234') is True:
# we have started an outbound call
pass
Perform a retrievable transfer to an inbound service.
the call channel instance to be used for the outbound leg.
the name of an inbound service registered on the CWP.
The remote address of the call being transferred.
the ringback tone to play when the outbound leg is ringing. Default is RINGBACK.
the amount of time to allow for the transfer to be accomplished. Default is 120 seconds. None means no timeout.
This function is used to transfer a connected call channel to an inbound service name as registered on the CWP. This function will allow the application to retain control over the call channel and retrieve it when the transfer is no longer required - for example, when the far end hangs up.
The argument other_call is the call channel instance used for the transfer’s outbound leg. This call channel must be in the IDLE state.
An originating address call_from may be supplied. Setting this parameter to an empty string will result in a default value being used.
This channel must be in ANSWERED state. If it is IDLE, this function will raise a Hangup exception; otherwise, if it is not ANSWERED it will raise an Error exception.
The argument ringback_tone is the ringback tone to play when the outbound call channel is in the RING_OUTGOING state. Valid options for ringback_tone are listed in the server’s ToneManager resource. If ringback_tone is None a default tone will be used. For the channel to play a tone it must have a tone player object. It is essential that a tone player is created on the channel before a transfer is attempted.
The argument seconds_timeout is the amount of time allowed for the transfer to be completed. If the timeout is None, no time limit will be imposed.
When successfully transferred in this manner, this call channel will be in the TRANSFERRED state.
If unsuccessful, the cause of the failure can be retrieved from transfer_cause() function.
After the transfer has completed successfully, this channel cannot be used to play or record audio (the audio path is no longer available, it has been transferred), it can be used only to hang up the call or to call either the retrieve_transferred_call function or the wait_for_transferred_call_retrieval function.
This function will block until confirmation has been received that the channel has been transferred, or that the transfer request has failed, or a timeout has expired.
This function will return the channel state.
Usage example:
state = channel.transfer_to_inbound_service(other_call, 'MyVoicemailRecorder')
if state != channel.State.TRANSFERRED:
cause = channel.transfer_cause()
print("could not transfer the call, reason is {0}".format(cause))
Create a tone player for the call channel to use during call transfer.
a tone manager object that contains a list of known tones.
The call channel requires a tone player to enable it to play tones during a call transfer (if this is required). This function will create a tone player on the call channel. To create a tone player we need to provide a tone manager. Please see the tone manager for more information.
This function always returns True.
Usage example:
# create a tone manager
tone_manager = ToneManager()
channel.create_tone_player(tone_manager)