Skip to main content
External transfers move an inbound PSTN call to an external destination while preserving the original caller’s identity.

​
Call flow

  1. Caller A dials Telnyx number B
  2. Telnyx routes the call to the SIP endpoint (A → B)
  3. The endpoint initiates a transfer to external number C
  4. Telnyx places a new outbound call (A → C)

​
Validation requirements

Telnyx validates external transfers to prevent unauthorized call spoofing:
  • Active call verification: An active inbound call must exist from the original caller to the Telnyx number
  • Diversion header: The outbound call leg must include a SIP Diversion header containing the Telnyx number
Required Diversion header format: 
Diversion: <sip:[email protected]>
Transfers are rejected when no active call can be matched, the Diversion header is missing, or the header contains an unauthorized number.

​
Transfer types

​
Blind transfer

Immediate transfer without announcement: 
REFER sip:[email protected] SIP/2.0
Refer-To: <sip:[email protected]>

​
Attended transfer

  1. Place the original call on hold
  2. Dial the transfer destination
  3. Announce the transfer
  4. Complete with SIP REFER

​
Programmable Voice implementation

​
Transfer command

POST /v2/calls//actions/transfer: 
{
  "to": "+13035559876",
  "from": "+12125551234"
}

​
Dial with bridge

POST /v2/calls with link_to and bridge_intent: 
{
  "connection_id": "1234567890",
  "to": "+13035559876",
  "from": "+12125551234",
  "link_to": "v3:abc123def456",
  "bridge_intent": true
}

​
TeXML Dial

<Dial> verb: 
<Response>
  <Dial callerId="+12125551234">
    <Number>+13035559876</Number>
  </Dial>
</Response>

​
Troubleshooting

If transfers fail, verify:
  1. An active inbound call exists on the Telnyx number
  2. The Diversion header includes the correct Telnyx number
  3. The outbound voice profile allows calls to the destination
  4. The destination number is in E.164 format