Connect a SIP trunk

A trunk is your connection to a carrier. Inbound, the carrier sends calls for your numbers to Fonoster. Outbound, Fonoster sends your calls to the carrier. Use a trunk to bring numbers from any carrier that speaks SIP. For a Twilio number, Link a Twilio number does all of this for you.

One trunk between your carrier and Fonoster. Inbound, the carrier sends calls for your numbers to sip:acme.pstn.fonoster.com, checked by an ACL or inbound credentials. Outbound, Fonoster sends your calls to sip.acme.com:5060 over UDP with outbound credentials, trying outbound URIs by priority, then weight.

Before you begin

Ask your carrier for:

How they authenticate you: by IP address, by username and password, or both.
Where to send outbound calls: a host name or IP, a port and a transport (UDP, TCP or TLS).
The addresses they send calls from, if you want to accept calls from those addresses only.
The format of your numbers in the calls they send, so you can add them exactly as sent.

Find your connection details

Your carrier needs to know where to send calls and which addresses to allow. The trunk form in the dashboard shows both, under Inbound URI:

Point your carrier at <host>:<port> (<transport>); allowlist <addresses>.

Give your carrier the SIP address, and ask them to allowlist the listed addresses if they filter by IP. If your workspace runs in a private region, the region’s own addresses are under Settings → Region, in Connection details.

Create the trunk

Add credentials (if your carrier uses them)

If your carrier gave you a username and password, save them as credentials first. Fonoster uses them to sign in when it sends calls to the carrier.

Dashboard
CLI

Go to Credentials, choose Add credentials, and enter a Name, the Username and the Password. Passwords are never shown again.

fonoster sipnet:credentials:create

Usernames take lowercase letters, numbers, dots, underscores and hyphens.

Add an access control list (optional)

An access control list (ACL) is an allowlist of IP addresses. Attach one to the trunk so only your carrier’s addresses can send calls in. Anything not listed is rejected.

Dashboard
CLI

Go to ACLs, choose Add ACL, name it (for example Acme signaling IPs), and add each address or range, such as 200.88.12.0/24.

The command asks for a name and a comma-separated list of IPv4 addresses or CIDR ranges:

fonoster sipnet:acls:create

Create the trunk

Dashboard
SDK
CLI

Go to Trunks and choose Add trunk. The form has three parts.Inbound · carrier → Fonoster

Name: the carrier’s name, such as Acme.
Inbound URI: a short label that identifies this trunk, such as acme. The form adds your install’s .pstn.<domain>, so the URI reads acme.pstn.fonoster.com. Give it to your carrier: they send calls for your numbers to this host. It must be unique, so if it’s taken, pick another.

Outbound · Fonoster → carrierAdd a row for each address your carrier gave you, with its Host, Port and Transport. Fill in User only if your carrier asks for one. Fonoster tries enabled URIs by Priority, then spreads calls by Weight. A trunk without outbound URIs takes calls in but can’t send them out.Security

Access control list: the ACL from the previous step.
Inbound credentials: credentials your carrier must sign in with when it sends you calls. Use them if your carrier authenticates by password instead of IP.
Outbound credentials: the credentials from the first step.
Send REGISTER: turn on only if your carrier requires registration.

Choose Create trunk.

This script creates a trunk with one outbound URI and the carrier’s credentials:

create-trunk.js

const SDK = require("@fonoster/sdk");

async function main() {
  const client = new SDK.Client({
    accessKeyId: "WO7d2kq9x4m1c8b3n6p0r5t2v9y4z7a1e3"
  });
  await client.loginWithApiKey(
    process.env.FONOSTER_API_KEY,
    process.env.FONOSTER_API_SECRET
  );

  const trunks = new SDK.Trunks(client);
  const { ref } = await trunks.createTrunk({
    name: "Acme",
    inboundUri: "acme.pstn.fonoster.com", // one label under pstn.<domain>
    accessControlListRef: "8e1d4b7a-3c9f-4e2a-b6d0-7a5c1f3e9b28",
    outboundCredentialsRef: "2c6a9e4f-1b7d-4f3a-8e5c-0d9b3a7f1e64",
    sendRegister: false,
    uris: [
      {
        host: "sip.acme.com",
        port: 5060,
        transport: "UDP",
        priority: 1,
        weight: 10,
        enabled: true
      }
    ]
  });

  console.log(`Trunk created: ${ref}`);
}

main().catch(console.error);

transport is one of UDP, TCP, TLS, SCTP, WS or WSS. Hosts are an IPv4 address or a domain name.

The command asks for the name, the inbound URI (one label under pstn.<domain>, such as acme.pstn.fonoster.com) and the ACL, then whether you need an outbound URI. If you do, it asks for the outbound credentials, host, port, transport (TCP or UDP) and user:

fonoster sipnet:trunks:create

Trunks created with the CLI have Send REGISTER on. If your carrier doesn’t expect registration, turn it off on the trunk in the dashboard.

Add your numbers

Add each of your carrier’s numbers to the trunk, in E.164 format, exactly as the carrier sends them. Point each one at an agent, a stream or a SIP agent. See Numbers and routing.

Configure your carrier

In your carrier’s portal, set up:

Inbound (their origination): send calls for your numbers to sip:<your inbound URI>, such as sip:acme.pstn.fonoster.com, at the SIP address from the trunk form.
Authentication: allowlist the addresses the trunk form lists, or give them the inbound credentials you attached to the trunk.
Outbound (their termination): accept calls from the addresses the trunk form lists, signed in with the outbound credentials if you set them.

Use the transport your carrier prefers, and the same one on both sides.

Check it

Call one of the trunk’s numbers from any phone. The agent, stream or SIP agent it points at answers.
Place an outbound call from the number. See Make outbound calls.

The trunk page lists the trunk’s numbers under Numbers on this trunk. If calls don’t arrive:

Check that the number in Fonoster matches what the carrier sends, + included.
If the trunk has an ACL, check that it lists every address the carrier sends from.
Check that the carrier sends to your inbound URI, not to a different host.

Delete a trunk

Go to Trunks, open the trunk and choose Delete, or run fonoster sipnet:trunks:delete <ref>. Calls to and from the carrier stop. For every command and method, see Trunks in the CLI reference and the Node SDK reference.

Next steps

Numbers and routing

Add the carrier’s numbers and send their calls somewhere.

Make outbound calls

Call out through the trunk.

SIP agents

Connect softphones and desk phones.

Transfer calls

Send callers to an operator through the same trunk.

Get started

Autopilot

Streams

Telephony

Observe

Workspace

Reference

Self-hosting

Private regions

Hacking Fonoster

Connect a SIP trunk

Before you begin

Find your connection details

Create the trunk

Configure your carrier

Check it

Delete a trunk

Next steps

Numbers and routing

Make outbound calls

SIP agents

Transfer calls

​Before you begin

​Find your connection details

​Create the trunk

​Configure your carrier

​Check it

​Delete a trunk

​Next steps

Numbers and routing

Make outbound calls

SIP agents

Transfer calls

Before you begin

Find your connection details

Create the trunk

Configure your carrier

Check it

Delete a trunk

Next steps