SIP trunking

Connect your own carrier or PBX to Aethex over SIP for inbound and outbound calls with your voice agents.

Overview

A SIP trunk connects your telephony carrier or PBX directly to Aethex, so inbound and outbound calls run through your voice agents over SIP instead of a managed number. Aethex terminates SIP at a dedicated, globally reachable edge and bridges the call into the same agent pipeline used by WebRTC and Twilio.There are two ways a call can reach Aethex:Your carrier delivers to us. Your carrier sends inbound calls to the Aethex SIP edge. This is the most common setup and works with most SIP-trunk providers and PBXs.Aethex registers to your carrier. For trunks that only deliver to a registered endpoint (REGISTER-gated trunks), Aethex registers to your carrier on your behalf and relays inbound calls. Used by some hosted PBX and softphone providers.

SIP ENDPOINT

The Aethex SIP endpoint

Point your carrier or SIP trunk at the Aethex SIP edge. The hostname resolves to stable Elastic IPs, so carriers that authenticate by source IP can allowlist the addresses directly.SIP is not served through a CDN. Connect straight to the hostname or IPs below on the SIP ports.

Heads up

SIP and RTP cannot be proxied. Send signaling to port 5060 and allow RTP/SRTP media on UDP 10000–60000 to and from the edge IPs. If your carrier filters by destination IP, allowlist both edge IPs.

Production SIP edge

text

Hostname     sip.aethexai.com
Edge IPs     13.63.135.167, 51.21.123.34
Signaling    5060/udp, 5060/tcp
Media        10000-60000/udp  (RTP/SRTP)

OUTBOUND

Outbound: dial through your carrier

For BYO-carrier outbound calling, create an outbound SIP trunk and register the caller ID numbers that Aethex is allowed to use. The one-shot `POST /sip-trunks/onboard` endpoint is the default path: it creates the trunk, creates the phone-number rows, and can set the trunk as your tenant default in one transaction.

Tip

Register every outbound caller ID when you onboard or create the trunk. To add more later, create a replacement trunk with the full set of numbers and switch your tenant default to it. POST /phone-numbers/sip/register attaches a number to an existing trunk for routing and billing, but it does not reprovision the outbound trunk itself, and outbound numbers cannot be changed in place (replacement-only), so a number added that way is not usable as an outbound from_number.

Onboard the outbound trunk

Send your carrier SIP host, authentication mode, credentials if your carrier uses digest auth, and the E.164 caller IDs you own. Set set_as_tenant_default when this trunk should be the fallback for outbound calls.

POST /sip-trunks/onboard request body

bash

curl -X POST https://api.aethexai.com/api/v1/sip-trunks/onboard \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production carrier",
    "outbound_address": "sip.carrier.example.com:5060",
    "numbers": ["+14155551234"],
    "auth_mode": "digest",
    "auth_username": "aethex_outbound",
    "auth_password": "<from your carrier>",
    "outbound_dial_format": "e164",
    "set_as_tenant_default": true
  }'

Place calls from a registered SIP number

After onboard returns, pass one of the registered SIP numbers as from_number on POST /calls/trigger. Aethex resolves the number to its trunk and sends the SIP INVITE through your carrier.

POST /calls/trigger body

bash

curl -X POST https://api.aethexai.com/api/v1/calls/trigger \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "to_number": "+14155550199",
    "from_number": "+14155551234"
  }'

OUTBOUND DIALING

Match your carrier's dialing format

Carriers disagree on how the destination should appear on the outbound SIP INVITE. Set outbound_dial_format on the outbound trunk to match what your carrier expects, and Aethex applies it to every call on that trunk just before dialing. Your API request, caller-ID ownership checks, and toll-fraud allowlists always stay in E.164, so this only changes what your carrier sees on the wire.

Heads up

national is for single-country carriers. It renders each destination in that number's own national format, so a foreign number placed over a national trunk would lose its country code and could misroute. Keep e164 or digits for carriers that terminate international calls. If a destination cannot be parsed, national automatically falls back to digits.

outbound_dial_format options

text

FORMAT     SENT TO CARRIER     USE WHEN
e164       +15551234567        default; carrier accepts +E.164
digits     15551234567         carrier rejects the leading +
national   05551234567         carrier needs national format (1 country)

MOST COMMON

Inbound: your carrier delivers to Aethex

Configure your carrier to send inbound calls for your number to sip.aethexai.com (port 5060). Then register the trunk with Aethex so the edge authenticates your carrier and routes the call. Creating an inbound trunk automatically provisions the routing rule that hands the call to your agent.List the numbers the carrier will deliver in numbers, and the carrier's source IPs in allowed_addresses (or set auth_username and auth_password for digest authentication). Finally, map each number to an agent. See Phone numbers.

Note

SIP trunking is self-serve: every API key carries the sip_trunks:read / sip_trunks:write scopes by default, so the examples on this page work with your key out of the box. Only keys minted with a custom narrow scope list need the scopes added explicitly.

Create an inbound SIP trunk

bash

curl -X POST https://api.aethexai.com/api/v1/sip-trunks \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme inbound",
    "type": "inbound",
    "numbers": ["+15551234567"],
    "allowed_addresses": ["198.51.100.10"]
  }'

Your carrier's IPs are allowlisted automatically.

Carrier IP allowlisting

The platform's SIP edge only accepts signaling from known carrier addresses. The allowed_addresses you set on an inbound trunk drive both layers automatically: the Aethex SIP edge uses them to authenticate the carrier's INVITEs and opens its firewall to the same addresses, no support ticket needed. Provide up to 10 public IPv4 addresses or CIDR blocks (/24–/32) per trunk; accounts have a shared budget across trunks; contact us to raise it. Changes typically apply within seconds.

Tip

Inbound trunks that rely on digest credentials alone (no allowed_addresses) can only receive traffic from carriers whose ranges are already permitted at the edge. If your carrier cannot provide stable signaling IPs, contact us.

Inbound: Aethex registers to your carrier

Some carriers only deliver inbound calls to a SIP endpoint that has registered with them (a REGISTER-gated trunk). Aethex operates a registration bridge that registers to your carrier on your behalf and relays the inbound call into your agent pipeline, with no change to how your agents are built.This is self-serve: create an inbound trunk with auth_mode set to register, supplying the carrier's registrar address (outbound_address), SIP username and password (auth_username / auth_password), your number, and the carrier's signaling IP in allowed_addresses. The platform holds the registration and opens its edge firewall to that carrier automatically. Send the digest username exactly as the carrier issues it; some carriers require the bare lowercase connection username (not user@domain), and case matters. Your carrier password is stored encrypted and never returned.

Note

Register-style trunks are common with hosted PBX and softphone providers. Create one yourself with auth_mode set to register; no support ticket needed.

TLS and media encryption

Media can be negotiated as SRTP. Set the trunk's media encryption to allow (the default) or require to enforce SRTP. Encrypted signaling (SIPS over TLS, port 5061) is not yet enabled on the public edge; it is provisioned per deployment during onboarding. Contact Aethex if your carrier requires TLS signaling.

IP allowlisting

If your carrier requires you to allowlist the addresses Aethex sends from and delivers to, use the production edge IPs below. They are stable Elastic IPs and do not change when instances are replaced.

Tip

These are the current production edge IPs and are stable. If Aethex adds edge capacity, new IPs are appended while existing ones stay the same. Where your carrier supports it, point at the sip.aethexai.com hostname so you don't have to track individual IPs.

Aethex production edge IPs

text

13.63.135.167
51.21.123.34

Next steps

Map your inbound numbers to agents in Phone numbers, build the agent that answers in Agents, and review Webhooks to receive call events.