call

class UASCallChannel

call(call_to, call_from='', seconds_timeout=120, codecs=None, live_speaker_detect=None, lsd_timeout_milliseconds=5000)

Make a call.

Required argument:

• call_to

  the call destination.

Optional arguments:

• call_from

  the origin of this call. Required for PSTN calls.

• seconds_timeout

  time allocated to make the call. Default is 120. None means no timeout.

• codecs

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

• live_speaker_detect

  live speaker detection settings. Default is None.

• lsd_timeout_milliseconds

  live speaker detection timeout. Default is 5000.

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.

The originating address call_from is compulsory for PSTN calls. For further information please see the documentation for outbound calls.

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.

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 (a fax machine or answering machine).

If live speaker detection is used, the result will be made available in the Details property: channel.Details.far_end_type. Look here for the options on enabling live speaker detection, and here for the detection result types.

If the far end is an answering machine, you can leave a message by playing a file. However, in order for the message to be recorded correctly, you will have to wait for the answering machine’s message to complete. You can call the wait_for_answer_machine method to do this.

lsd_timeout_milliseconds is the time in milliseconds allowed for the live speaker detection algorithm to attempt to categorise the far end. The allowable range is 500 - 5000 ms. Please note that this setting is particularly critical and may be strictly limited by the regulations for the country in which it is being used.

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
    cause = channel.cause()
    if cause == 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 see the documentation for outbound calls.

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
    cause = channel.cause()
    if cause == channel.Cause.BUSY:
        # do something here for busy calls
        pass
else:
    # the call has been answered, carry on
    pass