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 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
- 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_detectionset todetect,greeting_endordetect_words. - Answering Machine Greeting Ended if
answering_machine_detectionset togreeting_endordetect_wordsandmachinedetected initially.
Request
Path Parameters
Unique identifier and token for controlling the call
- application/json
Body
required
Array [
]
The DID or SIP URI to dial out and bridge to the given call.
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.
Audio URL to be played back when the transfer destination answers before bridging the call. The URL can point to either a WAV or MP3 file.
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.
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.
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.
Default value: 3500
Maximum timeout threshold for overall detection.
Default value: 800
Silence duration threshold after a greeting message or voice for it be considered human.
Default value: 50
Maximum threshold for silence between words.
Default value: 3500
Maximum threshold of a human greeting. If greeting longer than this value, considered machine.
Default value: 3500
If initial silence duration is greater than this value, consider it a machine.
Default value: 5
If number of detected words is greater than this value, consder it a machine.
Default value: 3500
If a single word lasts longer than this threshold, consider it a machine.
Default value: 256
Minimum noise threshold for any analysis.
Default value: 5000
If machine already detected, maximum timeout threshold to determine the end of the machine greeting.
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.
The name of the header to add.
The value of the header.
Custom headers to be added to the SIP INVITE.
Use this field to add state to every subsequent webhook. It must be a valid Base-64 encoded string.
Use this field to add state to every subsequent webhook for the new leg. It must be a valid Base-64 encoded string.
Use this field to avoid duplicate commands. Telnyx will ignore commands with the same "command_id".
SIP Authentication username used for SIP challenges.
SIP Authentication password used for SIP challenges.
Responses
200: Successful response
- application/json
422: Error response
- application/json
Request samples
curl -L 'https://api.telnyx.com/calls/:call_control_id/actions/transfer' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
--data-raw '{
"to": "+13129457420 or SIP:username@sip.telnyx.com",
"from": "+35319605860",
"audio_url": "http://www.example.com/sounds/greeting.wav",
"timeout": 60,
"time_limit": 600,
"answering_machine_detection": "disabled",
"answering_machine_detection_config": {
"total_analysis_time_millis": 5000,
"after_greeting_silence_millis": 1000,
"between_words_silence_millis": 100,
"greeting_duration_millis": 1500,
"initial_silence_millis": 1800,
"maximum_number_of_words": 3,
"maximum_word_length_millis": 2000,
"silence_threshold": 512,
"greeting_total_analysis_time_millis": 7500,
"greeting_silence_duration_millis": 2000
},
"custom_headers": [
{
"name": "head_1",
"value": "val_1"
},
{
"name": "head_2",
"value": "val_2"
}
],
"client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"target_leg_client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
"command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
"sip_auth_username": "string",
"sip_auth_password": "string"
}'
Response samples
{
"result": "ok"
}
{
"code": "90015",
"title": "Invalid Call Control ID",
"detail": "The call_control_id provided was not valid."
}