Set up a SIP trunk to receive and place calls

This page walks through a complete trunk setup in the order the dashboard needs it. Where skipping a step leaves a visible symptom, the step names it, so you can also use the page as a checklist when a test call fails. For what each setting means, follow the links to SIP trunks, Receiving calls, and Placing calls.

Before you start

• A Bird workspace. Calls, numbers, and trunks belong to one workspace, so do every step in the same one.
• The public addresses of your equipment: the hosts Bird should deliver calls to, and the addresses your equipment sends SIP from.
• For incoming calls, a Bird number in that workspace. For outgoing calls, a caller ID: a Bird number in the workspace or a number you verified.
• A Bird number whose status is active. A number still waiting for its ownership paperwork or its registration carries no incoming or outgoing calls: see File a number's ownership paperwork.

1. Create the trunk

Open Voice > SIP Trunks, select Add new SIP trunk, enter a name, and select Create trunk.

A new trunk carries no calls in either direction until you turn each one on.

2. Turn on inbound calling

Under Inbound calling, select Enable inbound. The Inbound routing section appears below it.

If you skip this step, numbers cannot be pointed at the trunk: the trunk is missing from the number's trunk list.

3. Add your gateways

In Inbound routing, open the Gateways tab and select Add gateway for each address Bird should deliver calls to:

If your equipment expects numbers without the leading +, open the format's list and choose Without the plus, or a 00 or 011 international prefix. What a gateway needs explains the number formats.

Bird passes the To header through as the caller's carrier sent it. If your equipment reads the dialed number from To, select Rewrite To user part and build the same format as the R-URI user part. Bird then replaces the user part of To on calls to that gateway.

Your gateway must accept calls from Bird without a SIP Digest challenge, because Bird does not answer one.

4. Choose the group calls hunt

Bird delivers a call to a group of gateways. Every gateway is in All gateways (automatic), which tries them in the order of their Priority on the Gateways tab, lowest first. For failover through it, give the backup gateway a higher Priority number than the primary. If the Groups tab shows no All gateways (automatic), the trunk's saved routing holds a group of its own in its place, and Priority does not order that group; see Use the automatic group.

When the first gateway is added to a trunk whose routing was never saved, the dashboard points the default route at All gateways (automatic).

For other ring times, weights, or only some of the gateways, build your own group: in the Groups tab, select Add group, name it, and use Add gateway to group for each gateway. Fail over and share incoming calls explains each order, the ring time and when the hunt stops.

5. Point the default route at the group

In the Rules tab, find Default route (No rule above matched). Set Then to Route to group and choose your group. Select Review and save, then confirm.

The default route answers every call no rule matches, so with no rules it answers every call. If it is set to Reject, those calls are refused before they reach your equipment, even with gateways in a group.

In the review, the dashboard warns Calls never reach some gateways when a gateway sits in no group that a rule or the default route sends calls to. Fix that warning before you test.

This default route belongs to the trunk. It is separate from the workspace setting Calls to numbers without their own route on the Numbers page, which decides what happens to numbers that have no route of their own.

6. Point your numbers at the trunk

Open Voice > Numbers, open the number, and under Inbound routing choose Deliver to a SIP trunk. Pick the trunk and save.

A number without a route of its own follows the workspace default route, which starts as reject. To send every such number to this trunk at once, set Calls to numbers without their own route to the trunk. See Set a default route.

If you skip this step while the workspace default route is still reject, incoming calls are rejected and the call record's Inbound route shows Reject the leg.

7. Turn on outbound calling and say who may send

Under Outbound calling, select Enable outbound. The Connection section appears with the trunk's SIP domain. Bird identifies your trunk by this domain, so copy it whole.

Then add at least one way to recognize your equipment:

• Allowed IP addresses: the public addresses your equipment sends SIP from. Behind NAT, use the router's public address.
• Allowed API keys: for equipment that answers a Digest challenge, with username bird and an API key secret as the password.

Until outbound is on, the trunk refuses every outgoing call. Until the trunk can recognize your equipment, calls are refused before a call record exists. See Controlling who may send calls.

8. Configure your PBX or SBC

On your PBX or SBC:

• Send outgoing calls to the trunk's SIP domain. Put the SIP domain in the Request-URI host. Use port 5060 (UDP or TCP) or 5061 (TLS). A call whose Request-URI host is any other name is refused.
• Dial in international format. Put the called number in the Request-URI user part as + and the country code, for example +442071234567. Do not add a technical prefix. See What Bird expects on the INVITE.
• Present an eligible caller ID in the From header.
• Offer G.711 (A-law or µ-law) and send DTMF as RFC 4733 telephone events. The same section of that page covers media.
• Allow Bird's addresses. If your firewall or SBC accepts only listed addresses, allow the signalling and media addresses of your trunk's region, listed in SIP trunk network requirements.

9. Turn on the countries you call

Open Voice > Destinations, tick each country you call, and select Save changes. A new workspace starts with none enabled, and a call to a disabled country is rejected with destination_not_enabled. See Voice destinations.

10. Test both directions

1. Incoming: call your Bird number from an ordinary phone, then open Voice > Legs in the same workspace.
2. Outgoing: place a call from your equipment to any reachable number in an enabled country, presenting your Bird number or a verified number as caller ID. You do not need a second Bird number for this.
3. Open each leg. Inbound route says what the number was set to do. A rejected call shows its reason and, when the fix is a setting of yours, a link to that setting. A call that worked shows Answered. Keep the Leg ID if you contact support.

If a call is missing, rejected, or never reaches your equipment, follow Voice troubleshooting, which starts from the symptom.

Next steps