Connect your carrier to Bolna with a SIP trunk

This guide takes you from nothing to a working trunk: you create the trunk in Bolna, set Bolna’s values in your carrier’s console, and place a test call in each direction.

Before you begin

Have these from your carrier:

A SIP trunk with at least one number on it. Some carriers, Plivo among them, use one trunk for inbound and another for outbound. Create both.
The gateway host Bolna dials for outbound calls, for example acme.pstn.twilio.com, and its port if it is not 5060.
The IP addresses the carrier sends calls from. Carriers publish these as their signalling IPs.
A SIP username and password, only if your carrier issued them for the calls you place.

Create the trunk

Open SIP Trunks

In the sidebar, under Deploy, open SIP Trunks and click Create trunk. If your account still has legacy SIP trunks, that page lists them: click Open new SIP trunks first.

SIP Trunks page in the Bolna dashboard with an empty trunk table and the Create trunk button in the top right — The SIP Trunks page

Pick your carrier

The Provider step asks Which carrier is this trunk for? Pick Plivo, Telnyx, Twilio, Exotel, Vobiz, Vonage, or Custom for any other carrier. Then fill in:

Trunk name, a label only you see.
Channels, the number of simultaneous calls the trunk allows. The default is 10.
Gateway we dial, the host Bolna sends outbound calls to. The Telnyx and Exotel presets fill this in. For the others, enter the host your carrier gave your account; the field shows the expected shape.

Click Continue.

Create trunk dialog on the Provider step, with the Plivo carrier tile selected, a trunk name, 10 channels and a Zentrunk domain in the Gateway we dial field — Provider step with the Plivo preset

Add your carrier's IPs

The Carrier IPs step asks Which addresses does your carrier call from? Add every signalling IP or CIDR range your carrier publishes, one at a time. Bolna accepts an inbound call only from these addresses. The Plivo and Exotel presets prefill the addresses those carriers publish, and every preset links to its carrier’s IP page.Under Carrier credentials (optional), enter the Username and Password only if your carrier issued them for the calls Bolna places. Enter both or neither. Click Continue.

Create trunk dialog on the Carrier IPs step, showing Plivo's prefilled signalling CIDR ranges as removable chips, an address input with an Add button, and empty Username and Password fields under Carrier credentials (optional) — Carrier IPs step

Add your numbers

The Numbers step asks Which numbers arrive on this trunk? Enter each number in E.164 format, starting with +, and click Add. This step is optional; you can add numbers later. Click Continue.

Create trunk dialog on the Numbers step, with one E.164 number added and its destination key shown underneath — Numbers step

Review and create

The Review step summarizes the trunk and shows the first thing to do in your carrier’s console for each direction. Click Create trunk. The trunk page opens, and its health reads Waiting for carrier until the first call crosses it.

Create trunk dialog on the Review step, summarizing provider, carrier IPs, carrier credentials, gateways and numbers, with Inbound and Outbound next-step cards and a Create trunk button — Review step

Set Bolna’s values at your carrier

Open the trunk’s Overview tab. Under Carrier setup, the Inbound, carrier to Bolna and Outbound, Bolna to carrier cards list every value your carrier needs, each with a copy button. Expand the steps under each card, for example Plivo inbound trunk steps, for a checklist written for your carrier’s console.

Inbound: carrier to Bolna

Set these on your carrier’s origination (inbound) trunk:

Setting	Value
Origination URI	`sip:trunk.bolna.ai:5060` for UDP, or `sip:trunk.bolna.ai:5060;transport=tcp` for TCP
If the carrier accepts only an IP	`15.252.21.46`, port `5060`
Number format	E.164, with or without the `+`
Codecs	`PCMU` and `PCMA`. Turn off any others, such as G.729.
DTMF	RFC 2833

Your carrier must send each INVITE with an SDP offer, from an address on the trunk’s carrier IPs. Assign your numbers to this origination trunk in the carrier’s console.

Outbound: Bolna to carrier

Set these on your carrier’s termination (outbound) trunk:

Setting	Value
IP allowlist (signalling)	`15.252.21.46` and `13.206.230.198`
Media (RTP), both directions	UDP `30000`-`40000`, to and from `15.252.21.46`
Credentials	Optional. If you use a credential list instead of, or as well as, the IP allowlist, enter the same username and password on the trunk in Bolna.
Caller ID	One of your trunk numbers, in E.164 with the `+`
Codecs	`PCMU` and `PCMA`

Allowlist both Bolna IPs. 13.206.230.198 is reserved for a second edge, so listing it now means no carrier change later.

Manage carrier IPs, gateways and credentials

The trunk’s Connection tab holds both directions. Changes take effect on live traffic.

Trunk Connection tab with the Inbound: carrier IPs list on the left, the Outbound: gateways list with a Dial with leading plus switch and Carrier credentials row on the right, and the Advanced row below showing UDP, PCMU, PCMA and RFC 2833 DTMF — The Connection tab

Inbound: carrier IPs. Click Add IP to add an address or CIDR range. Changes apply within 5 seconds. Each entry must be a public IPv4 address or range, no broader than /16, and a trunk holds up to 32. With no carrier IPs, every inbound call is refused. Outbound: gateways. Click Add gateway and enter the Host, Port and Priority. A trunk holds up to 8 gateways, tried in priority order, lowest first. The host must be a public IPv4 address or a DNS name. If a gateway times out, answers 408 or 478, or answers with a 5xx, Bolna tries the next gateway. Any other answer, such as busy, a decline or no answer within 60 seconds, ends the call.

Dial with leading plus sends the number you call as +<digits>. Off, the default, sends the digits alone. Pick whichever your carrier expects.
Carrier credentials holds the username and password Bolna sends when your carrier challenges an outbound call with 401 or 407. The password is stored encrypted and never shown again.

Advanced. Click Edit to change the Transport (UDP or TCP) Bolna uses to reach your gateways, the Channels, and the Codecs (PCMU, PCMA, or both). DTMF is always RFC 2833.

If another trunk on Bolna dials the same gateway host or address, both trunks must have carrier credentials. Without them, the carrier cannot tell the trunks apart by Bolna’s shared IPs, so Bolna refuses the gateway with 409 gateway_conflict.

Add numbers

Open the Numbers tab and click Add number.

Number is the number in E.164 format, starting with +.
Destination key is the called number exactly as your carrier puts it in the Request-URI. Leave it blank to use the number’s digits without the +. Set it when your carrier sends something else, such as a national format.

An inbound call matches a number when the called number equals the E.164 number, with or without the +, or equals the destination key. A number can be on only one trunk at a time; adding one that is already on a trunk fails with 409 number_taken.

Add number dialog with a Number field holding an E.164 number and a Destination key field showing the digits as a placeholder — Add number

Next, assign an agent to each number so inbound calls are answered.

Verify with a test call

The trunk tests itself without an agent. Open the Activity tab, or click Test trunk at the top of the trunk page.

Test inbound

Under Test inbound, click Start listening, then dial the number shown from any phone within five minutes. Bolna answers and plays your voice back to you about a second later. While the trunk is listening, the next call to any of its numbers reaches the test instead of your agent. Stop listening cancels the test before a call arrives.

Test outbound

Under Test outbound, enter a phone number you can answer and click Place echo call. Bolna calls it from the trunk’s first number, through its gateways in priority order. Answer, speak, and you hear yourself about a second later. The call ends after a minute.

Read the result

Each test shows its state, ending in Completed or Failed. A failed test shows the SIP code and cause the carrier returned. See Troubleshooting for what each one means.

Trunk Activity tab with the Test inbound card waiting for a call, showing Dial the number now, Listening for a countdown and a Stop listening button, and the Test outbound card with a number in the Number to call field next to the Place echo call button — Self-tests on the Activity tab

A trunk runs one test at a time and allows five tests every ten minutes. A test uses one of the trunk’s channels while it runs. Tests do not appear in Call History or under Recent calls, and they do not change the trunk’s health, which stays Waiting for carrier until a real call crosses the trunk.

Using the API

Every step above has an API equivalent. Send your API key as a Bearer token; see Authentication. These requests use the create trunk, add carrier IP, add gateway, update trunk, add number and connection details endpoints.

curl -X POST https://api.bolna.ai/trunk/trunks \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme India",
    "preset": "plivo",
    "channels": 10,
    "transport": "udp",
    "codecs": "PCMU,PCMA",
    "outbound_leading_plus_enabled": false,
    "gateways": [
      { "host": "21784177241578.zt.plivo.com", "port": 5060, "priority": 1 }
    ],
    "ip_acls": ["15.207.90.192/31", "204.89.151.128/27"],
    "auth_username": "<carrier_username>",
    "auth_password": "<carrier_password>"
  }'

curl -X POST https://api.bolna.ai/trunk/trunks/<trunk_id>/ip-acls \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "cidr": "13.52.9.0/25" }'

curl -X POST https://api.bolna.ai/trunk/trunks/<trunk_id>/gateways \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "host": "sip-backup.example.com", "port": 5060, "priority": 2 }'

curl -X PATCH https://api.bolna.ai/trunk/trunks/<trunk_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_username": "<carrier_username>",
    "auth_password": "<carrier_password>",
    "transport": "tcp"
  }'

curl -X POST https://api.bolna.ai/trunk/trunks/<trunk_id>/numbers \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+918045678901", "destination_key": "918045678901" }'

curl https://api.bolna.ai/trunk/pop \
  -H "Authorization: Bearer <api_key>"

GET /trunk/pop returns the values to give your carrier:

{
  "sip_domain": "trunk.bolna.ai",
  "ips": ["15.252.21.46", "13.206.230.198"],
  "port": 5060,
  "transports": ["udp", "tcp"],
  "rtp_ports": "30000-40000"
}

A few rules the API enforces:

preset records which carrier template the trunk came from. The API does not fill any values from it; send the gateways, transport and carrier IPs yourself.
transport is udp (the default) or tcp.
codecs is PCMU, PCMA, or both, comma-separated.
auth_username and auth_password are set together and cleared together. To clear them, send both as null.
destination_key is required when adding a number through the API. Send the number’s digits without the + unless your carrier sends something else.
gateway.priority is 0 to 100, lowest tried first.

The trunk’s health field reads waiting_for_carrier until the first call, ready after it, degraded after three outbound calls in a row fail at the carrier (an answered call resets this), and disabled while is_active is false.

Build

Deploy

Monitor

Go live

Connect your carrier to Bolna with a SIP trunk

Before you begin

Create the trunk

Set Bolna’s values at your carrier

Inbound: carrier to Bolna

Outbound: Bolna to carrier

Manage carrier IPs, gateways and credentials

Add numbers

Verify with a test call

Using the API

Next steps

Receive inbound calls

Make outbound calls

​Before you begin

​Create the trunk

​Set Bolna’s values at your carrier

​Inbound: carrier to Bolna

​Outbound: Bolna to carrier

​Manage carrier IPs, gateways and credentials

​Add numbers

​Verify with a test call

​Using the API

​Next steps

Receive inbound calls

Make outbound calls

Before you begin

Create the trunk

Set Bolna’s values at your carrier

Inbound: carrier to Bolna

Outbound: Bolna to carrier

Manage carrier IPs, gateways and credentials

Add numbers

Verify with a test call

Using the API

Next steps