Twilio Flex AI voice agent integration

Your TwiML can dial a ThunderPhone AI voice agent's SIP address with the call's CallSid in a header. When the caller needs a person, the agent sends a SIP REFER. Twilio passes the transfer address, with the hand-off inside it, to your referUrl handler, and the TwiML your handler returns decides where the caller goes next, such as a Flex queue with the hand-off as task attributes.

Flex is optional. The same setup works for any Twilio Programmable Voice app.

This page is about running the AI agent inside your Twilio call flow. To bring Twilio phone numbers into ThunderPhone and let ThunderPhone answer them directly, see Twilio (bring your own number).

Setup guide: Connect from Twilio has the TwiML, the transfer entry and a Twilio Function that enqueues the caller to Flex.

What it does for Twilio and Flex teams

Twilio stays your phone system, and your code stays in charge of the call. The AI agent is a <Dial> in your TwiML. When it's done, your own handler decides what happens: enqueue to Flex, dial a number, or anything else TwiML can do. The hand-off id and intent arrive in that request, so routing on the agent's decision takes a few lines of code, and the Flex worker sees the summary as task attributes.

Because the handler is yours, you can route on the address the agent picked too. The address's user part, such as support or billing, is yours to choose, so you can give the agent one transfer entry per destination.

How the call flows

In. Twilio's <Sip> takes a username and password, so the agent gets a standard SIP endpoint. Your TwiML returns <Dial answerOnBridge="true" referUrl="…"><Sip …> with the endpoint's SIP address, ;transport=tls, and X-Call-ID set to the CallSid. Twilio doesn't document a call-id header of its own, so this one is how ThunderPhone links the call; it's stored as the call's external_call_id. More context goes the same way, such as X-Account-Id, which reaches the prompt as {{sip_x_account_id}}.

Back. The agent transfers with a REFER to an address on Twilio, with X-Handoff-Id and X-Handoff-Intent inside that address. Twilio sends the whole address to your referUrl as ReferTransferTarget. Your handler reads the two values out of it, can look up the summary by hand-off id, and returns TwiML such as <Enqueue> to a Flex workflow with the hand-off as task attributes. With answerOnBridge="true", the caller stays connected until the new destination answers.

Setup at a glance

Create a standard SIP endpoint for the agent and store its password.
Return the <Dial><Sip> TwiML for calls the agent should take, with X-Call-ID and a referUrl.
Add a transfer entry with your Twilio SIP address and the hand-off headers inside it.
Deploy the referUrl handler, for example the Twilio Function from the guide, with your API key in its environment variables.
Call in, ask for a person, and check that the handler receives both headers and the caller reaches the queue.

Limits and prerequisites

referUrl is required. Without it the agent's transfer fails with Twilio error 13802.
Short addresses. Twilio limits Refer-To to 256 characters. ThunderPhone keeps the address to 254 and leaves out a header that doesn't fit, so keep header names and values short.
<Dial><Sip> only. Twilio doesn't accept a REFER on a call connected through <Conference> or <Queue>.
Studio needs TwiML. Studio's Connect Call To widget doesn't document custom headers or referUrl, so hand the call to this TwiML with a TwiML Redirect widget. Studio's HTTP Request widget can't send the Authorization header, so the lookup runs in a Function.
Use TLS. Twilio uses UDP unless told otherwise, and the endpoint refuses UDP. Add ;transport=tls.

Frequently asked questions

Can I use ThunderPhone as the AI voice agent in Twilio Flex?

Yes. Your TwiML dials the agent over SIP, and when the caller needs a person, your referUrl handler enqueues them to a Flex workflow with the agent's hand-off as task attributes. The docs guide includes a Twilio Function that does this.

Do I need Flex?

No. Any Twilio Programmable Voice app works. Flex is one place your referUrl handler can send the caller.

How is this different from ThunderPhone's Twilio number import?

Number import connects a Twilio account so ThunderPhone answers your Twilio numbers directly. This integration leaves the call in your Twilio app and dials the AI agent from your TwiML, so your code decides what happens before and after the agent.

How do Flex workers see what the AI collected?

The referUrl handler reads the hand-off id and intent from ReferTransferTarget, fetches the summary from ThunderPhone's hand-off lookup, and adds all three to the Flex task as attributes.

Can I start the AI agent from Twilio Studio?

Yes, with a TwiML Redirect widget that hands the call to the <Dial><Sip> TwiML. Studio's Connect Call To widget doesn't document custom headers or referUrl.