Connect Telnyx

Put your number on a Telnyx SIP connection, with LiveKit running your agent. Telnyx carries out the transfer itself, so your agent leaves the call before the caller reads their card. Read Connect your phone system first for how the handoff works and what every setup needs.

Temporary workaround. Telnyx sends calls created by a SIP REFER unencrypted, ignoring the connection’s SRTP setting, and Natural refuses those calls. Until Telnyx fixes this confirmed bug, transfer through a Telnyx SIP subdomain, as in Create the handoff connection. Natural will tell you when the fix ships, and then you:

Transfer to dialUri exactly as returned, without swapping the host.
Delete the handoff connection.

Put your number on a SIP connection

Your Telnyx account must be on a paid tier, because trial accounts refuse unverified callers and can’t place the transfer leg. Your number must be on a SIP connection, not a Call Control or TeXML application (why). Connect an FQDN connection to LiveKit with LiveKit’s Telnyx guide, using LiveKit’s secure trunking steps for TLS, then check these settings:

Setting	Value	API field
Connection SIP transport protocol	TLS	`transport_protocol`
Connection encrypted media	SRTP	`encrypted_media`
Connection FQDN	Your LiveKit SIP host, port `5061`
Connection conversation persistence	Off (the default)	`conversation_persistence`
Number inbound call recording	Off	`call_recording.inbound_call_recording_enabled`
Outbound voice profile call recording	None	`call_recording.call_recording_type`

With the API, set these through Update an FQDN connection, Update a phone number with voice settings, and Update an outbound voice profile. Keep SIPREC, media streaming, and transcription off on the number and connection. A connection webhook is fine, since it only reports when calls start, are answered, and end, and where they were transferred.

Create the LiveKit inbound trunk

One inbound trunk takes both new calls and returning callers, so list your number and the return user from your returnTarget.

{
  "trunk": {
    "name": "Main line",
    "numbers": ["+14155550100", "pay-return"],
    "media_encryption": "SIP_MEDIA_ENCRYPT_ALLOW"
  }
}

Media encryption must be SIP_MEDIA_ENCRYPT_ALLOW, not REQUIRE, because Telnyx’s bug also affects the transfer back. Returning callers arrive unencrypted and REQUIRE would drop them, though that leg carries no card data. Add a dispatch rule that sends calls on this trunk to your agent. If you restrict the trunk’s allowed_addresses, allow every Telnyx signaling IP, because Telnyx picks the region per call.

Create the handoff connection (temporary)

Create a second FQDN connection that points at Natural, with a SIP subdomain that only your own connections can call.

Setting	Value
FQDN	`sip.natural.com`, port `5061`. In Sandbox, `sip.sandbox.natural.com`.
SIP transport protocol	TLS
Encrypted media	SRTP
SIP subdomain	Your choice, for example `acme-natural`
Receive subdomain calls from	Only my connections
Conversation persistence	Off (the default)

Leave its webhook empty, and skip the outbound voice profile, which it doesn’t need. Use one handoff connection per environment, each with its own subdomain. With the API, create the connection, then its FQDN:

cURL

curl -X POST https://api.telnyx.com/v2/fqdn_connections \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_name": "natural-handoff",
    "transport_protocol": "TLS",
    "encrypted_media": "SRTP",
    "inbound": {
      "sip_subdomain": "acme-natural",
      "sip_subdomain_receive_settings": "only_my_connections"
    }
  }'

curl -X POST https://api.telnyx.com/v2/fqdns \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "<handoff connection id>",
    "fqdn": "sip.natural.com",
    "port": 5061,
    "dns_record_type": "a"
  }'

Transfer the caller

When the caller is ready to pay, create the voice session with your returnTarget, swap the host in its dialUri for your subdomain, and cold transfer the caller there.

sip:vos_019d…@sip.natural.com;transport=tls
sip:vos_019d…@acme-natural.sip.telnyx.com;transport=tls

import re
import uuid
from livekit import api

session = client.voice_sessions.create(
    kind="payment",
    payment_intent_id=payment_intent_id,
    caller_phone=caller_phone,
    return_target="sip:pay-return@<your-livekit-sip-host>;transport=tls",
    idempotency_key=str(uuid.uuid4()),
)
# Temporary: route through the handoff connection until Telnyx encrypts REFER legs.
target = re.sub(r"@[^;]+", "@acme-natural.sip.telnyx.com", session.data.attributes.dial_uri)

async with api.LiveKitAPI() as livekit:
    result = await livekit.sip.transfer_sip_participant(
        api.TransferSIPParticipantRequest(
            room_name=room_name,
            participant_identity=caller_identity,
            transfer_to=target,
            play_dialtone=False,
        )
    )
if result.status != api.STS_TRANSFER_SUCCESSFUL:
    ...  # Offer the checkout link.

import { SipClient } from "livekit-server-sdk";

const session = await client.voiceSessions.create(
  {
    kind: "payment",
    paymentIntentId,
    callerPhone,
    returnTarget: "sip:pay-return@<your-livekit-sip-host>;transport=tls",
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId },
);
const { dialUri } = session.data.attributes;
if (!dialUri) throw new Error("Voice session has no dialUri");
// Temporary: route through the handoff connection until Telnyx encrypts REFER legs.
const target = dialUri.replace(/@[^;]+/, "@acme-natural.sip.telnyx.com");

const sip = new SipClient(LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET);
try {
  await sip.transferSipParticipant(roomName, callerIdentity, target, { playDialtone: false });
} catch {
  // Offer the checkout link.
}

Change only the host and keep the rest of dialUri as returned. If creating the session or the transfer fails, offer the caller the checkout link instead. Your agent leaves the call only once Telnyx accepts the transfer.

Recognize returning callers

When the payment is done, Natural asks Telnyx to transfer the caller to your returnTarget. The caller arrives in a new room, addressed to pay-return instead of your phone number, and LiveKit puts that address in the caller’s sip.trunkPhoneNumber attribute. Use the caller’s own number, in sip.phoneNumber, to find the conversation, and accept the match only if you handed that caller to Natural within the last 30 minutes, the longest a payment call can run, since caller ID alone can be faked.

returned = participant.attributes.get("sip.trunkPhoneNumber") == "pay-return"
caller_phone = participant.attributes.get("sip.phoneNumber")

const returned = participant.attributes["sip.trunkPhoneNumber"] === "pay-return";
const callerPhone = participant.attributes["sip.phoneNumber"];

Before offering anything, read the session’s payment.outcome, and if it’s paid, don’t offer another transfer. If the caller’s number is withheld or matches no conversation, greet them as a new caller.

Why not Call Control or TeXML

A number on a Call Control or TeXML application stays under that application for the whole call. Telnyx’s transfer command and TeXML’s <Dial> bridge the caller to Natural, so your application keeps the caller’s leg while they read their card. On Call Control, Telnyx also sends every key press on that leg to your webhook, card digits included. A Call Control refer hands the transfer to the caller’s phone carrier instead, which refused it or dropped the caller in Natural’s tests.

Test it

Place a test call in Sandbox and run the go-live checks.

Overview

Common use cases

Guides