start call

class UASCallChannel
start_call(call_to, call_from='', codecs=None, live_speaker_detect=None, lsd_timeout_milliseconds=7000)

Start making an outbound call.

Required argument:
  • call_to

    the call destination.

Optional arguments:
  • call_from

    the origin of this call. Required for PSTN calls.

  • 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 7000.

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.

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

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 - 10000 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 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