Skip to main content

Transfer call

POST 

/calls/:call_control_id/actions/transfer

Transfer a call to a new destination. If the transfer is unsuccessful, a call.hangup webhook for the other call (Leg B) will be sent indicating that the transfer could not be completed. The original call will remain active and may be issued additional commands, potentially transfering the call to an alternate destination.

Expected Webhooks:

  • call.initiated
  • call.bridged to Leg B
  • call.answered or call.hangup
  • call.machine.detection.ended if answering_machine_detection was requested
  • call.machine.greeting.ended if answering_machine_detection was requested to detect the end of machine greeting
  • call.machine.premium.detection.ended if answering_machine_detection=premium was requested
  • call.machine.premium.greeting.ended if answering_machine_detection=premium was requested and a beep was detected

Request

Path Parameters

    call_control_id stringrequired

    Unique identifier and token for controlling the call

Body

required

Transfer call request

    to

    object

    required

    The DID or SIP URI to dial out to. Multiple DID or SIP URIs can be provided using an array of strings

    oneOf

    string

    from string

    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 to number of the original call if omitted.

    from_display_name string

    The from_display_name string to be used as the caller id name (SIP From Display Name) presented to the destination (to number). The string should have a maximum of 128 characters, containing only letters, numbers, spaces, and -_~!.+ special characters. If ommited, the display name will be the same as the number in the from field.

    audio_url string

    The URL of a file to be played back when the transfer destination answers before bridging the call. The URL can point to either a WAV or MP3 file. media_name and audio_url cannot be used together in one request.

    media_name string

    The media_name of a file to be played back when the transfer destination answers before bridging the call. The media_name must point to a file previously uploaded to api.telnyx.com/v2/media by the same user/organization. The file must either be a WAV or MP3 file.

    timeout_secs 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 transferred. 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_secs int32

    Possible values: >= 30 and <= 14400

    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: [premium, 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 call.machine.detection.ended webhook with the analysis result. If 'greeting_end' or 'detect_words' is used and a 'machine' is detected, you will receive another 'call.machine.greeting.ended' webhook when the answering machine greeting ends with a beep or silence. If detect_beep is used, you will only receive 'call.machine.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.

    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.

  • ]

  • client_state string

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

    target_leg_client_state string

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

    command_id string

    Use this field to avoid duplicate commands. Telnyx will ignore any command with the same command_id for the same call_control_id.

    media_encryption string

    Possible values: [disabled, SRTP]

    Default value: disabled

    Defines whether media should be encrypted on the new call leg.

    sip_auth_username string

    SIP Authentication username used for SIP challenges.

    sip_auth_password string

    SIP Authentication password used for SIP challenges.

    sip_headers

    object[]

    SIP headers to be added to the SIP INVITE. Currently only User-to-User header is supported.

  • Array [

  • name stringrequired

    Possible values: [User-to-User]

    The name of the header to add.

    value stringrequired

    The value of the header.

  • ]

  • sip_transport_protocol string

    Possible values: [UDP, TCP, TLS]

    Default value: UDP

    Defines SIP transport protocol to be used on the call.

    sound_modifications

    object

    Use this field to modify sound effects, for example adjust the pitch.

    pitch double

    Set the pitch directly, value should be > 0, default 1 (lower = lower tone)

    semitone double

    Adjust the pitch in semitones, values should be between -14 and 14, default 0

    octaves double

    Adjust the pitch in octaves, values should be between -1 and 1, default 0

    track string

    Default value: outbound

    The track to which the sound modifications will be applied. Accepted values are inbound or outbound

    webhook_url string

    Use this field to override the URL for which Telnyx will send subsequent webhooks to for this call.

    webhook_url_method string

    Possible values: [POST, GET]

    Default value: POST

    HTTP request type used for webhook_url.

Responses

200: Successful response upon making a call control command.

Schema

    data

    object

    result string

default: Unexpected error

Schema

    errors

    Error[]

  • Array [

  • code integerrequired
    title stringrequired
    detail string

    source

    object

    pointer json-pointer

    JSON pointer (RFC6901) to the offending entity.

    parameter string

    Indicates which query parameter caused the error.

    meta object
  • ]

Callbacks

Loading...