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

Path Parameters

call_control_id stringrequired

Unique identifier and token for controlling the call

application/json

Body

required

Transfer call request

to stringrequired

The DID or SIP URI to dial out to.

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

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.

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 headers to be added to the SIP INVITE. Currently only User-to-User header is supported.

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

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

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.

application/json

Schema

data

object

result string

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

default: Unexpected error

application/json

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

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Callbacks

Request samples

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

Response samples

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

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Transfer call

Request ​

Path Parameters

Body

Responses ​

Callbacks ​

Request

Responses

Callbacks