Set up an inbound phone agent via SIP

Point a Twilio number you already own at AssemblyAI over a SIP trunk and attach a voice agent. Inbound only.

Twilio passes inbound calls to AssemblyAI over SIP, so there’s no media server, audio bridge, or webhook to run.

Caller → your Twilio number → SIP trunk → AssemblyAI → your agent

You need:

• A Twilio account (Account SID + Auth Token from the Console home page) with a phone number you already own
• An AssemblyAI API key
• An agent_id. Don’t have one? Create an agent first.
• The Twilio CLI installed and logged in (twilio login), plus curl, jq, and uuidgen

Prefer clicking? You can do every Twilio step in the Console under Voice → Manage → Elastic SIP Trunking. The CLI just makes it scriptable.

Five steps, three on Twilio and two on AssemblyAI:

1. Create a SIP trunk
2. Route its origination to sip:sip.assemblyai.com
3. Attach your number to the trunk
4. Register the number with AssemblyAI
5. Bind your agent to it

1. Set your details

Save these in a .env file in your working directory:

.env

AAI_API_KEY="your-assemblyai-api-key"
AGENT_ID="7ad24396-b822-4dca-871a-be9cc4781cf9"    # the agent that answers
NUMBER="+1..."                                     # your Twilio number, E.164
TRUNK_DOMAIN="my-company-agent.pstn.twilio.com"    # you invent this

Load it into your shell:

set -a && source .env && set +a

TRUNK_DOMAIN doesn’t exist yet. You’re naming the trunk you create in the next step, and it must end in .pstn.twilio.com and be unique across Twilio, so include your company name.

2. Point Twilio at AssemblyAI

Creates the trunk, points its origination at sip:sip.assemblyai.com, and attaches your number to the trunk.

setup-trunk.sh

#!/usr/bin/env bash
set -euo pipefail

# 1. Create the trunk
TRUNK_SID=$(twilio api:trunking:v1:trunks:create \
  --friendly-name "AssemblyAI voice agent" \
  --domain-name "$TRUNK_DOMAIN" -o json | jq -r '.[0].sid')
echo "Trunk: $TRUNK_SID"

# 2. Route incoming calls to AssemblyAI
twilio api:trunking:v1:trunks:origination-urls:create \
  --trunk-sid "$TRUNK_SID" --friendly-name "AssemblyAI SIP" \
  --sip-url "sip:sip.assemblyai.com" --priority 1 --weight 1 --enabled >/dev/null

# 3. Attach your number to the trunk
NUMBER_SID=$(twilio api:core:incoming-phone-numbers:list \
  --phone-number "$NUMBER" -o json | jq -r '.[0].sid')
twilio api:trunking:v1:trunks:phone-numbers:create \
  --trunk-sid "$TRUNK_SID" --phone-number-sid "$NUMBER_SID" >/dev/null
echo "Number $NUMBER attached to trunk"

The trunk now controls the number. Any Voice webhook set on the number itself no longer applies.

Reusing a trunk that already has an origination URL? Delete the old one before running this, or calls may go to the wrong place:

twilio api:trunking:v1:trunks:origination-urls:list --trunk-sid "$TRUNK_SID"
twilio api:trunking:v1:trunks:origination-urls:remove --trunk-sid "$TRUNK_SID" --sid "OUxxxx"

3. Attach your agent to the number

Registers the number with AssemblyAI against your trunk, binds AGENT_ID to it, and prints the result.

register-number.sh

#!/usr/bin/env bash
set -euo pipefail

AAI="https://agents.us.assemblyai.com/v1"
AUTH=(-H "Authorization: Bearer $AAI_API_KEY" -H "Content-Type: application/json")

# 4. Register the number
curl -fsS -X POST "$AAI/phone-numbers/import" "${AUTH[@]}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"phone_number\":\"$NUMBER\",\"termination_uri\":\"$TRUNK_DOMAIN\"}" >/dev/null

# 5. Bind the agent
curl -fsS -X PUT "$AAI/phone-numbers/$NUMBER/agent" "${AUTH[@]}" \
  -d "{\"agent_id\":\"$AGENT_ID\"}" >/dev/null

# Verify
curl -fsS "$AAI/phone-numbers/$NUMBER" "${AUTH[@]}" | jq

The final jq output should show your agent_id with "type": "imported".

To point the number at a different agent later, re-run only the PUT. Twilio needs no changes, and editing the agent itself changes nothing here: the number is bound to the ID, so updates to that agent take effect on the next call.

4. Call it

Ring the number. You should hear the greeting, then have a real-time conversation with the agent.

Twilio bills the inbound minutes and AssemblyAI bills the session, so a live number draws on both accounts.

If it does not work

Symptom	Cause
Nothing happens when you call	The number isn’t on the trunk, the origination URL isn’t exactly sip:sip.assemblyai.com and enabled, or no agent is attached. A number with a Voice webhook still set in the Console is not going through the trunk.
Call connects, then silence	The origination URL is wrong or disabled.
is attached to a different trunk	Detach it in the Twilio Console, then re-run.
Twilio POST /v1/Trunks failed (400)	The SIP domain is taken or malformed. Choose another *.pstn.twilio.com.
404 agent_not_found	Wrong AGENT_ID.
409 number already registered	Already imported. Safe to ignore on a re-run.
422 phone_number_has_no_agent	Re-run the PUT in step 3.
Twilio command not recognised	Names change between CLI versions. Run twilio api:trunking:v1 --help, or use the Console.

Want it scripted?

The Python and JavaScript starters run all five steps as one idempotent command, publishing the agent along the way:

Python

python deployment/telephony/connect.py

Next steps

• Configure your agent: Customize the system prompt, greeting, and turn detection.
• Choose a voice: Pick a voice for your agent.
• Add tools to your agent: Give your agent the ability to call functions.