Skip to main content

Dial

POST 
/calls

Dial a number from a given connection. A successful response will include a call_leg_id which can be used to correlate the command with subsequent webhooks.

Expected Webhooks:

  • Call initiated
  • You will receive either a Call answered](/docs/api/v1/call-control/Call%20Webhooks#call-answered) webhook or a [Call hangup webhook.
  • Answering Machine Detection Result if answering_machine_detection set to detect, greeting_end or detect_words.
  • Answering Machine Greeting Ended if answering_machine_detection set to greeting_end or detect_words and machine detected initially.

Request​

Body

required

    to stringrequired

    The DID or SIP URI to dial out to.

    from stringrequired

    The 'from' number to be used as the caller id presented to the destination ('to' number). The number should be in +E164 format. This attribute will default to the 'from' number of the original call if omitted.

    connection_id stringrequired

    The ID of the Call Control App (formerly ID of the connection) to be used when dialing the destination.

    audio_url string

    The URL of a file to be played back to the callee when the call is answered. The URL can point to either a WAV or MP3 file.

    timeout int32

    Default value: 30

    The number of seconds that Telnyx will wait for the call to be answered by the destination to which it is being called. If the timeout is reached before an answer is received, the call will hangup and a 'call_hangup' webhook with a 'hangup_cause' of 'timeout' will be sent. Minimum value is 5 seconds. Maximum value is 120 seconds.

    time_limit int32

    Default value: 14400

    Sets the maximum duration of a Call Control Leg in seconds. If the time limit is reached, the call will hangup and a 'call_hangup' webhook with a 'hangup_cause' of 'time_limit' will be sent. For example, by setting a time limit of 120 seconds, a Call Leg will be automatically terminated two minutes after being answered. The default time limit is 14400 seconds or 4 hours and this is also the maximum allowed call length.

    answering_machine_detection string

    Possible values: [detect, detect_beep, detect_words, greeting_end, disabled]

    Default value: disabled

    Enables Answering Machine Detection. When a call is answered, Telnyx runs real-time detection to determine if it was picked up by a human or a machine and sends an 'answering_machine_detection_result' webhook with the analysis result. If 'greeting_end' or 'detect_words' is used and a 'machine' is detected, you will receive another 'amd_greeting_ended' webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive 'amd_greeting_ended' if a beep is detected.

    answering_machine_detection_config

    object

    Optional configuration parameters to modify 'answering_machine_detection' performance.

    total_analysis_time_millis int32

    Default value: 3500

    Maximum timeout threshold for overall detection.

    after_greeting_silence_millis int32

    Default value: 800

    Silence duration threshold after a greeting message or voice for it be considered human.

    between_words_silence_millis int32

    Default value: 50

    Maximum threshold for silence between words.

    greeting_duration_millis int32

    Default value: 3500

    Maximum threshold of a human greeting. If greeting longer than this value, considered machine.

    initial_silence_millis int32

    Default value: 3500

    If initial silence duration is greater than this value, consider it a machine.

    maximum_number_of_words int32

    Default value: 5

    If number of detected words is greater than this value, consder it a machine.

    maximum_word_length_millis int32

    Default value: 3500

    If a single word lasts longer than this threshold, consider it a machine.

    silence_threshold int32

    Default value: 256

    Minimum noise threshold for any analysis.

    greeting_total_analysis_time_millis int32

    Default value: 5000

    If machine already detected, maximum timeout threshold to determine the end of the machine greeting.

    greeting_silence_duration_millis int32

    Default value: 1500

    If machine already detected, maximum threshold for silence between words. If exceeded, the greeting is considered ended.

    Optional configuration parameters to modify 'answering_machine_detection' performance.

    custom_headers

    object[]

    Custom headers to be added to the SIP INVITE.

  • Array [

    • name stringrequired

    The name of the header to add.

    value stringrequired

    The value of the header.

  • ]

    • Custom headers to be added to the SIP INVITE.

    client_state string

    Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.

    command_id string

    Use this field to avoid duplicate commands. Telnyx will ignore commands with the same "command_id".

    link_to string

    Use another call's control id for sharing the same call session id

    sip_auth_username string

    SIP Authentication username used for SIP challenges.

    sip_auth_password string

    SIP Authentication password used for SIP challenges.

Responses​

200: Successful response

Schema

    result stringrequired

422: Error response

Schema

    code stringrequired
    title stringrequired
    detail stringrequired
Loading...