Telnyx Call Control handoff

If you already run your inbound calls on Telnyx Call Control — your own webhook app answering calls, doing IVR, routing, and business logic — you don't have to move that to Speko. Instead, at the moment you want a Speko voice agent to take over, your app transfers the live call to a per-agent SIP address. The Speko agent answers and handles the rest of the conversation with its full prompt, tools, and knowledge base.

How it works

Your Call Control app keeps the call until you decide to hand it off. When it does, it issues a standard Telnyx transfer (full handoff — your leg drops) or dial+bridge (you stay on the leg) to the agent's SIP URI.

1. Your Call Control app handles the inbound call as it does today.
2. When you want the Speko agent, you call the Telnyx transfer action with to set to the agent's handoff SIP URI and an X-Speko-Handoff custom header carrying the agent's token.
3. Telnyx sends the INVITE to Speko's LiveKit SIP endpoint from Telnyx's SIP signaling IPs — the same ones Speko already allowlists for its inbound trunk, so no SIP auth is required. Speko reads the per-agent handoff token off the header and dispatches that agent into the call.
4. From there the pipeline — speech-to-text, your model, text-to-speech, tools, recording, transcripts, and the post-call report — is identical to a phone call. The caller's number and any Diversion (forwarded-from) header carry through.

Because it's the same agent runtime, an agent you already built for the phone works over a handoff with no changes.

Enable it on an agent

1. Open the agent, go to the Telnyx handoff tab, and click Enable handoff.
2. Copy the SIP URI (sip:<token>@<your-sip-host>) — that's everything you need.

The token is both the routing key and a bearer secret — treat it like an API key. Only calls arriving from Telnyx's signaling IPs can reach the endpoint, and the token identifies the agent, so keep it private. If it leaks, click Rotate token; the old URI stops routing immediately.

Transfer a call

From your Call Control app, on the leg you want to hand off:

POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/transfer
Authorization: Bearer <YOUR_TELNYX_API_KEY>
Content-Type: application/json

{
  "to": "sip:<agent-handoff-token>@<your-sip-host>",
  "custom_headers": [
    { "name": "X-Speko-Handoff", "value": "<agent-handoff-token>" }
  ]
}

Notes:

• No SIP auth is needed. The INVITE reaches Speko over your Telnyx SIP connection, and Telnyx's signaling IPs are already allowlisted on Speko's inbound trunk — the same path your Speko phone numbers use.
• X-Speko-Handoff is required. Its value is the agent's handoff token; it's how Speko selects the agent (the token also appears in the URI user-part for readability).
• To stay on the call (e.g. to listen or take it back) instead of fully handing off, dial a new leg to the same SIP URI and bridge it rather than using transfer.

Getting the analysis back

After the handoff call ends, Speko delivers the transcript, summary, and any extracted fields to matching workspace endpoints subscribed to call.report, exactly as it does for phone calls — so your system can pick up where the agent left off. See Workspace webhooks for setup.

Choosing handoff vs. porting your number

Use Call Control handoff when you want to keep your existing Telnyx call flow and only delegate part of a call to a Speko agent. If instead you want Speko to own the whole inbound number, point the number at Speko directly — talk to us about number setup.