> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryopencomputer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring your own SIP trunk

> Connect a SIP trunk from any carrier, add its numbers, and check whether the line can place calls.

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

**1. Add the configuration**

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

**2. 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.

**3. Add the numbers**

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

**4. 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.

**5. 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](https://docs.tryopencomputer.com/guides/api.md)).

| 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. |

```bash theme={null}
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:

```json theme={null}
{
  "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](https://docs.tryopencomputer.com/guides/campaigns.md).

## 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](https://docs.tryopencomputer.com/guides/telephony.md) for the other telephony options in your account and for removing a configuration.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.