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

# Connect a phone number

> How a carrier's phone numbers reach an agent, and which connection to create first.

An agent reaches the phone network through a **connection**: a SIP link between
your carrier and SLNG. You bring your own phone numbers. They come from a
carrier such as Twilio, not from SLNG.

Create an inbound connection, an outbound connection, or both. An agent can use
one connection in each direction.

**Inbound**: a caller dials a number you own. Your carrier hands the call across
the inbound connection to the agent, and audio flows both ways from there.

```mermaid theme={null}
graph LR
  caller["<span style='display:block;width:30px;height:30px;margin:0 auto 6px;background:url(/images/icons/phone-incoming.svg) center/contain no-repeat'></span>Caller"]
  sip["<span style='display:block;width:30px;height:30px;margin:0 auto 6px;background:url(/images/icons/server.svg) center/contain no-repeat'></span>SIP provider"]
  agent["<span style='display:block;width:34px;height:34px;margin:0 auto 6px;background:url(/images/icon.svg) center/contain no-repeat'></span>SLNG agent"]
  caller -- "dials your number" --> sip
  sip <== "inbound connection" ==> agent
  classDef slng stroke:#fbe566,stroke-width:2.5px;
  class agent slng
```

**Outbound**: the agent opens the outbound connection to your carrier, which
rings the number. Audio flows both ways once the person answers.

```mermaid theme={null}
graph LR
  agent["<span style='display:block;width:34px;height:34px;margin:0 auto 6px;background:url(/images/icon.svg) center/contain no-repeat'></span>SLNG agent"]
  sip["<span style='display:block;width:30px;height:30px;margin:0 auto 6px;background:url(/images/icons/server.svg) center/contain no-repeat'></span>SIP provider"]
  callee["<span style='display:block;width:30px;height:30px;margin:0 auto 6px;background:url(/images/icons/phone-outgoing.svg) center/contain no-repeat'></span>Person you call"]
  agent <== "outbound connection" ==> sip
  sip -- "rings the number" --> callee
  classDef slng stroke:#fbe566,stroke-width:2.5px;
  class agent slng
```

## Pick a direction

Choose whether the agent needs to receive calls, place calls, or both:

|                       | Inbound connection                     | Outbound connection                                               |
| --------------------- | -------------------------------------- | ----------------------------------------------------------------- |
| Use it when           | Callers dial a number you own          | The agent places the call                                         |
| Agents per connection | One. Inbound connections are exclusive | Many. One connection can serve multiple agents in the same region |
| Numbers you add       | The numbers callers dial               | The caller IDs the agent calls from                               |
| Also required for     | An `inbound_greeting`                  | An `outbound_greeting`, the Transfer Call tool, and call dispatch |

If callers dial you and the agent also calls people back, create both.

## Pick a setup mode

Within each direction, choose a setup mode:

* **Twilio**: provider-specific guidance and a checklist for the Twilio console.
* **Manual**: SIP settings that you enter yourself. Use this mode with another
  carrier, or with Twilio when you want to configure the trunk without the
  guided flow.

An outbound Twilio connection uses Elastic SIP Trunking termination. An inbound
Twilio connection gives you a webhook URL to paste into the number's voice
settings in Twilio.

## Where connections live

Connections are org-wide, like [BYOK keys](/guides/models/bring-your-own-key).
You create them once and attach them to as many agents as the direction allows:

| Step                            | Where                                              | Who                           |
| ------------------------------- | -------------------------------------------------- | ----------------------------- |
| Create and edit a connection    | The **Telephony** section in the dashboard sidebar | Org admins                    |
| Attach a connection to an agent | The project's **Telephony** section                | Anyone who can edit the agent |

Create and edit connections in the dashboard. The public API does not support
connection management. You can attach an existing connection from either the
dashboard or the API through `sip_inbound_trunk_id` and
`sip_outbound_trunk_id` on the agent.

## When a connection cannot be attached

The dashboard marks an unavailable connection with the reason. The
`sip-trunk-options` API endpoint returns the same reason in
`unavailable_reason`.

| Reason                      | What to do                                                                                  |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `inactive`                  | Open the connection and check the provisioning error.                                       |
| `not_synced`                | Provisioning has not finished. Wait, then reload.                                           |
| `different_livekit_project` | The connection and agent are in different regions. Use an agent in the connection's region. |
| `assigned_to_another_agent` | Detach the inbound connection from the other agent first.                                   |

<CardGroup cols={2}>
  <Card title="Receive calls on a number" icon="phone-incoming" href="/guides/agents/telephony/inbound">
    Route calls that arrive on your number to an agent.
  </Card>

  <Card title="Place calls from an agent" icon="phone-outgoing" href="/guides/agents/telephony/outbound">
    Give an agent a caller ID so it can dial out and transfer calls.
  </Card>

  <Card title="Dispatch outbound calls" icon="phone-call" href="/guides/agents/telephony/dispatch-calls">
    Start one call from the dashboard or API, or process a contact list.
  </Card>
</CardGroup>