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

# Link a Twilio number

> Connect a number from your Twilio account to Fonoster with one CLI command, and send its calls to an agent or a stream.

If you have a number in Twilio, one command connects it to Fonoster. The command sets up a SIP
trunk between Twilio and Fonoster, moves the number onto it, and adds the number to your workspace
pointing at the application you choose. Calls to the number then reach your Autopilot agent or
stream, and you can place outbound calls from it.

> [!NOTE]
>
> Linking runs from the CLI. The dashboard doesn't have a Twilio flow: once the number is linked,
> you manage it under **Numbers** like any other.

## Before you begin

You need:

* A Twilio account with a voice-capable phone number in it. Note the number in E.164 format, such
  as `+18095550123`.
* Your Twilio **Account SID** and **Auth Token**, from the Twilio console.
* An Autopilot agent or a stream to send calls to. See
  [Build an Autopilot agent](https://docs.fonoster.com/autopilot/build-an-agent.md) or
  [Build a stream with the Voice SDK](https://docs.fonoster.com/streams/voice-sdk.md).
* [Node.js](https://nodejs.org/) 22 or later.

## Link the number

**1. Install the CLI and log in**

In the dashboard, go to **API keys** and create a key. Then install the `fonoster` CLI and log
in to your workspace with the key ID and secret:

```bash theme={"system"}
npm install -g @fonoster/ctl
fonoster workspaces:login
```

**2. Run the link command**

Start the command:

```bash theme={"system"}
fonoster sipnet:numbers:linkTwilioNumber
```

It asks for:

| Prompt | What to enter |
| - | - |
| Friendly Name | A name for the number in Fonoster, such as `Support desk`. Leave it empty to use the number itself. |
| Number to link (E.164 format) | The Twilio number, such as `+18095550123`. |
| Application | The Autopilot agent or stream that answers the number. Pick **None** to choose later. |
| Twilio Account SID | Your Account SID, which starts with `AC`. |
| Twilio Auth Token | Your Auth Token. The CLI uses it only for this command and doesn't save it. |

Confirm with **Ready?**. The command returns when everything is set up.

**3. Check the number**

List your numbers. The linked number is there, on a trunk named **Twilio Trunk**, pointing at
the application you picked:

```bash theme={"system"}
fonoster sipnet:numbers:list
```

Call the number from any phone. Your agent or stream answers.

> [!TIP]
>
> Your Twilio number rings in Fonoster.

## What the command sets up

The command changes both your Twilio account and your Fonoster workspace. It names everything after
your workspace's access key ID in lowercase, shown here as `wo7d2kq9x4m1c8b3n6p0r5t2v9y4z7a1e3`.

![In your Twilio account, the number +1 809 555 0123 moves onto an Elastic SIP trunk with an IP ACL for Fonoster's address and an origination URL sip:wo7d….pstn.fonoster.com. In your Fonoster workspace, a Twilio Trunk with inbound URI wo7d….pstn.fonoster.com carries the same number, which points at the Front desk agent. Incoming calls flow from Twilio to Fonoster; outbound calls flow back to wo7d….pstn.twilio.com.](https://mintcdn.com/fonoster/GsxtawNPYOQvohG4/images/link-twilio/what-it-creates-light.png?fit=max\&auto=format\&n=GsxtawNPYOQvohG4\&q=85\&s=b6148796abc35c88ac88d052406d3906)

**In Twilio:**

* An Elastic SIP trunk named `Trunk-<access key ID>`, with the termination domain
  `<access key ID>.pstn.twilio.com`. Fonoster sends your outbound calls there.
* An IP access control list named `ACL-<access key ID>` on that trunk, holding Fonoster's
  signaling address. Twilio only accepts outbound calls from addresses on this list.
* An origination URL `sip:<access key ID>.pstn.fonoster.com` on the trunk. Twilio sends calls to
  your number there.
* Your number moves onto the trunk. Twilio then sends its calls over SIP, not to the number's voice
  webhook.

**In Fonoster:**

* A trunk named **Twilio Trunk**, with the inbound URI `<access key ID>.pstn.fonoster.com` and an
  outbound URI pointing at the Twilio termination domain.
* The number, on that trunk, pointing at the application you picked.

To link more Twilio numbers, run the command again. It reuses the trunks it already created on
both sides and only adds the number. If the number is already in your workspace, the command
replaces it.

## Change where calls go

The linked number is a normal number in your workspace. To send its calls somewhere else, go to
**Numbers**, open it, and pick a new destination under **When this number is called, send it to**.
See [Numbers and routing](https://docs.fonoster.com/telephony/numbers.md).

## On your own install

On a self-hosted Fonoster, Twilio has to reach your servers, not Fonoster Cloud. Pass two flags:

```bash theme={"system"}
fonoster sipnet:numbers:linkTwilioNumber \
  --outbound-uri-base sip.example.com \
  --access-control-list 203.0.113.10/32
```

| Flag | Short | What it sets |
| - | - | - |
| `--outbound-uri-base` | `-b` | The host Twilio sends calls to. The command prefixes it with your access key ID, so `<access key ID>.pstn.example.com` must resolve to your SIP address. Default `pstn.<domain>`, from the server you're signed in to. |
| `--access-control-list` | `-a` | The addresses your install sends calls from, comma-separated, as IPs or CIDR ranges. Twilio accepts outbound calls only from these. |

## Troubleshooting

* **"The number … was not found in your account."** The number isn't in the Twilio account whose
  SID you entered. Check the account and the E.164 format.
* **The number rings but nothing answers.** Check that the number points at an application under
  **Numbers**.
* **Outbound calls fail.** Twilio rejects calls from addresses outside the trunk's access control
  list. On your own install, check the `--access-control-list` you passed.

## Next steps

> **[Numbers and routing](https://docs.fonoster.com/telephony/numbers.md)**
>
> Send each number to the right agent, stream or SIP agent.

> **[Make outbound calls](https://docs.fonoster.com/telephony/outbound-calls.md)**
>
> Call people from your Twilio number.

> **[Connect a SIP trunk](https://docs.fonoster.com/telephony/trunks.md)**
>
> Use another carrier.

> **[Bring your Twilio or Pipecat app](https://docs.fonoster.com/streams/bring-your-app.md)**
>
> Run a bot built for Twilio Media Streams on Fonoster.


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