Transfer call

POST

/calls/{call_control_id}/actions/transfer

Call Commands

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 (see callback schema below):

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 Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/calls//actions/transfer' \
--header 'Content-Type: application/json' \
--data-raw '{
    "answering_machine_detection": "detect",
    "answering_machine_detection_config": {
        "after_greeting_silence_millis": 1000,
        "between_words_silence_millis": 1000,
        "greeting_duration_millis": 1000,
        "greeting_silence_duration_millis": 2000,
        "greeting_total_analysis_time_millis": 50000,
        "initial_silence_millis": 1000,
        "maximum_number_of_words": 1000,
        "maximum_word_length_millis": 2000,
        "silence_threshold": 512,
        "total_analysis_time_millis": 5000
    },
    "audio_url": "http://www.example.com/sounds/greeting.wav",
    "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
    "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
    "custom_headers": [
        {
            "name": "head_1",
            "value": "val_1"
        },
        {
            "name": "head_2",
            "value": "val_2"
        }
    ],
    "early_media": true,
    "from": "+18005550101",
    "from_display_name": "Company Name",
    "media_encryption": "SRTP",
    "sip_auth_password": "password",
    "sip_auth_username": "username",
    "sip_headers": [
        {
            "name": "User-to-User",
            "value": "value"
        }
    ],
    "sip_transport_protocol": "TLS",
    "stream_track": "both_tracks",
    "stream_url": "wss://www.example.com/websocket",
    "timeout_limit_secs": 60,
    "timeout_secs": 60,
    "to": "+18005550100 or sip:username@sip.telnyx.com",
    "webhook_url": "https://www.example.com/server-b/",
    "webhook_url_method": "POST"
}'

Response Example

200 - Example 1

{
    "data": {
        "result": "ok"
    }
}

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

call_control_id

string

required

Unique identifier and token for controlling the call

Body Params application/json

answering_machine_detection

enum<string>

optional

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.

Allowed values:

premiumdetectdetect_beepdetect_wordsgreeting_enddisabled

Default:

disabled

answering_machine_detection_config

object

optional

Optional configuration parameters to modify 'answering_machine_detection' performance.

after_greeting_silence_millis

integer <int32>

optional

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

Default:

800

Example:

1000

between_words_silence_millis

integer <int32>

optional

Maximum threshold for silence between words.

Default:

Example:

100

greeting_duration_millis

integer <int32>

optional

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

Default:

3500

Example:

1500

greeting_silence_duration_millis

integer <int32>

optional

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

Default:

1500

Example:

2000

greeting_total_analysis_time_millis

integer <int32>

optional

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

Default:

5000

Example:

7500

initial_silence_millis

integer <int32>

optional

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

Default:

3500

Example:

1800

maximum_number_of_words

integer <int32>

optional

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

Default:

Example:

maximum_word_length_millis

integer <int32>

optional

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

Default:

3500

Example:

2000

silence_threshold

integer <int32>

optional

Minimum noise threshold for any analysis.

Default:

256

Example:

512

total_analysis_time_millis

integer <int32>

optional

Maximum timeout threshold for overall detection.

Default:

3500

Example:

5000

audio_url

string

optional

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.

Example:

http://example.com/message.wav

client_state

string

optional

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

Example:

aGF2ZSBhIG5pY2UgZGF5ID1d

command_id

string

optional

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

Example:

891510ac-f3e4-11e8-af5b-de00688a4901

custom_headers

array[object (Custom SIP Header) {2}]

optional

Custom headers to be added to the SIP INVITE.

Example:

[{"name":"head_1","value":"val_1"},{"name":"head_2","value":"val_2"}]

name

string

required

The name of the header to add.

Example:

head_1

value

string

required

The value of the header.

Example:

val_1

early_media

boolean

optional

If set to false, early media will not be passed to the originating leg.

Default:

true

Example:

false

from

string

optional

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.

Example:

+18005550101

from_display_name

string

optional

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.

Example:

Company Name

media_encryption

enum<string>

optional

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

Allowed values:

disabledSRTPDTLS

Default:

disabled

media_name

string

optional

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.

Example:

my_media_uploaded_to_media_storage_api

mute_dtmf

enum<string>

optional

When enabled, DTMF tones are not passed to the call participant. The webhooks containing the DTMF information will be sent.

Allowed values:

nonebothselfopposite

Default:

none

Example:

opposite

sip_auth_password

string

optional

SIP Authentication password used for SIP challenges.

Example:

password

sip_auth_username

string

optional

SIP Authentication username used for SIP challenges.

Example:

username

sip_headers

array[object (SIP Header) {2}]

optional

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

Example:

[{"name":"User-to-User","value":"value"}]

name

enum<string>

required

The name of the header to add.

Allowed value:

User-to-User

Example:

User-to-User

value

string

required

The value of the header.

Example:

value

sip_transport_protocol

enum<string>

optional

Defines SIP transport protocol to be used on the call.

Allowed values:

UDPTCPTLS

Default:

UDP

sound_modifications

object (Sound modifications)

optional

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

Example:

{"octaves":0.1,"pitch":"0.8","semitone":-2,"track":"both"}

octaves

number <double>

optional

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

Example:

-0.5

pitch

number <double>

optional

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

Example:

0.8

semitone

number <double>

optional

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

Example:

-10

track

string

optional

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

Default:

outbound

Example:

inbound

target_leg_client_state

string

optional

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

Example:

aGF2ZSBhIG5pY2UgZGF5ID1d

time_limit_secs

integer <int32>

optional

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.

>= 30<= 14400

Default:

14400

Example:

600

timeout_secs

integer <int32>

optional

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 600 seconds.

Default:

Example:

string

required

The DID or SIP URI to dial out to.

Example:

+18005550100 or sip:username@sip.telnyx.com

webhook_url

string

optional

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

Example:

https://www.example.com/server-b/

webhook_url_method

enum<string>

optional

HTTP request type used for webhook_url.

Allowed values:

POSTGET

Default:

POST

Example:

GET

Examples

Responses

🟢200OK

application/json

Successful response upon making a call control command.

Body

data

object (Call Control Command Result)

optional

Example:

{"result":"ok"}

result

string

optional

Example:

🔴500Server Error

Modified at 2025-06-16 19:14:41

Transcription stop

Retrieve a call status