Bring your own SIP trunk

A SIP trunk (any carrier) line lets Athena place outbound calls through the SIP trunk your carrier or PBX gives you. Athena builds the call route for the line, so you only enter the trunk details and the numbers on it. You can add the line in the dashboard or with one API request.

Before you begin

From your carrier, collect:

The SIP trunk address (a public host name or IP address, with a port if your carrier uses one, for example trunk.example.com or 203.0.113.10:5060).
The SIP username and password, unless your carrier authorizes your traffic by IP address.
The transport your carrier expects. Use TCP unless your carrier requires something else.
The phone numbers on the trunk, in E.164 format (for example +15555550123).

Make sure your agents use an Athena Live 1 model configuration. SIP trunk lines run on the Athena voice path; a line in an organization that does not use it reports that it is not ready.

Add the line in the dashboard

Add the configuration

Open Telephony, choose Add configuration, and select SIP trunk (any carrier).

Enter the trunk details

Fill in SIP trunk address, SIP username, SIP password, and Transport. TCP (recommended) is the default. UDP can fail because a call’s setup message can be larger than one UDP packet, so choose it only when your carrier requires it.

Add the numbers

Add the numbers on this trunk under Phone numbers. They are used as caller IDs.

Save and check

Save the configuration. Athena checks the address and login when you save. When the line gets a number, Athena starts building its call route in the background; if that does not finish, the first call builds it. Review any setup step or warning shown on the configuration.

Test with a controlled destination

Place a call to a phone you control and confirm it rings, both sides can hear each other, and the run completes.

Add the line with the API

POST /api/v1/organizations/sip-trunks/provision creates the line, adds its numbers, and builds its call route in one request. It accepts your API key in X-API-Key (see API quickstart).

Field	Required	Notes
`name`	Yes	1 to 64 characters, unique in your organization.
`address`	Yes	The SIP trunk host your carrier gave you.
`username`	No	SIP login. Leave it out if your carrier authorizes by IP address.
`password`	No	SIP password.
`transport`	No	`tcp` (default), `tls`, or `udp`.
`numbers`	Yes	1 to 50 numbers on the trunk. The first one is the default caller ID.
`country_code`	No	Two-letter country hint for numbers written without `+`.
`is_default_outbound`	No	`true` makes this line the organization’s default for outbound calls.

curl --fail-with-body -X POST \
  "$ATHENA_BASE_URL/api/v1/organizations/sip-trunks/provision" \
  -H "X-API-Key: $ATHENA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Sales line",
    "address": "trunk.example.com",
    "username": "<SIP_USERNAME>",
    "password": "<SIP_PASSWORD>",
    "numbers": ["+15555550123"]
  }'

Athena checks every number before it creates anything. If a number is still refused while the numbers are added, Athena removes the new line again and returns the original error. The organization’s default outbound line changes only after everything else succeeds.

Status	Meaning
`200`	The line was created. Read `ready` and `reason` in the body.
`400`	The trunk settings or a number are invalid, or the same number is listed twice. Nothing was created.
`409`	The name is already used, or a number already belongs to another line in your organization.

Keep SIP passwords in your backend’s secret store, never in browser code or logs.

Check readiness

Both the provision response and GET /api/v1/organizations/telephony-configs/{config_id}/readiness return the same object:

{
  "configuration_id": 205,
  "ready": true,
  "route_id": 208,
  "route_state": "unverified",
  "numbers": ["+15555550123"],
  "reason": null
}

ready: true means the line can place calls now.
ready: false comes with a reason written for you to act on, for example “Add at least one active phone number to this line.”
route_state describes the line’s call route, such as unverified, verified, or failed.

The readiness GET only reads. It never creates a route, so a line whose route is not built yet reports that the route is built on the first call or by the provision request. It returns 404 when the configuration is not in your organization.

When the carrier refuses a line

If your carrier refuses calls on a line, for example because SIP trunking is not enabled on the account, Athena stops placing calls on that line. Telephony shows A SIP line was refused by the carrier with the affected line names, and readiness reports the refusal. Nobody is called through a slower fallback path. Fix the carrier account, then check readiness again. Campaigns that use a line that is not ready do not fail their contacts. While the line is still getting ready, the campaign waits and checks again; otherwise it pauses so you can review it. Resume the campaign after the line is ready. See Run campaigns.

Limits

This page covers outbound calling. A SIP trunk line does not take inbound calls or carry call transfers by itself.
A green readiness check is configuration evidence. It does not prove that a particular call rang; confirm with a controlled test call and the run.
Use Connect telephony for the other telephony options in your account and for removing a configuration.

Start here

Build your agent

Tools and knowledge

Launch and operate

Developers

Bring your own SIP trunk

Before you begin

Add the line in the dashboard

Add the line with the API

Check readiness

When the carrier refuses a line

Limits

​Before you begin

​Add the line in the dashboard

​Add the line with the API

​Check readiness

​When the carrier refuses a line

​Limits

Before you begin

Add the line in the dashboard

Add the line with the API

Check readiness

When the carrier refuses a line

Limits