Connect Twilio

Put your number on a Twilio Elastic SIP trunk, with LiveKit running your agent. Twilio 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.

Create the trunk

Your number must be on an Elastic SIP trunk, not Programmable Voice (why). Connect a trunk to LiveKit with LiveKit’s Twilio guide, then set these on it:

Setting	Value	Trunk API parameter
Secure Trunking	On	`Secure=true`
Call Transfer (SIP REFER)	Enabled	`TransferMode=enable-all`
Caller ID for Transfer Target	Transferee (the default), so the caller’s number comes through	`TransferCallerId=from-transferee`
Call recording	Do Not Record (the default)

cURL

curl -X POST "https://trunking.twilio.com/v1/Trunks/$TWILIO_TRUNK_SID" \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  --data-urlencode "Secure=true" \
  --data-urlencode "TransferMode=enable-all" \
  --data-urlencode "TransferCallerId=from-transferee"

Set the Origination URI to sip:<your-livekit-sip-host>;transport=tls, using your LiveKit SIP host. With Secure Trunking on, Twilio refuses any unencrypted call.

Never turn on trunk recording, because it records the whole call, card entry included. Record with LiveKit Egress instead, which can’t capture card entry because the caller’s audio leaves the room at the transfer.

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, and turn on media encryption.

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

Add a dispatch rule that sends calls on this trunk to your agent.

Transfer the caller

When the caller is ready to pay, create the voice session with your returnTarget, then cold transfer the caller to its dialUri.

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

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=session.data.attributes.dial_uri,
            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");

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

Pass dialUri exactly as returned. If creating the session or the transfer fails, offer the caller the checkout link instead. Your agent leaves the call only once your carrier accepts the transfer.

Recognize returning callers

When the payment is done, Natural asks Twilio 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 Programmable Voice

A number on Programmable Voice (TwiML or a Twilio voice app) can’t hand a phone caller to Natural without staying on the call. Twilio’s <Refer> only works on calls that arrived over SIP, so a caller from the phone network can only be connected with <Dial>, which bridges the caller through your app. Your app then stays on the line and can record or stream the call while the caller reads their card.

Test it

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

Overview

Common use cases

Guides

Create the trunk

Create the LiveKit inbound trunk

Transfer the caller

Recognize returning callers

Why not Programmable Voice

Test it