SIP trunks
A SIP trunk is the connection between your phone system and Bird. It gives your PBX (the system that places your calls) an address to send calls to, and gives Bird a way to recognize that they really came from you. Trunks live on the SIP Trunks page, and everything on this page is configured there.
Most workspaces need only one trunk. Create more when you want separate access rules per site or per system, since the IP allow list, the allowed API keys, and the Digest settings are all per trunk.
Create a trunk
Choose Create trunk on the SIP Trunks page and give it a name. The name is a label for you, mutable at any time, and it never travels with your calls.
Bird issues the trunk its own SIP domain. That domain is how Bird recognizes which trunk a call belongs to, so it stays fixed for the life of the trunk: enter it into your phone system once and it keeps working.
A new trunk turns away every call until you tell it who may place them, by adding an IP range, an API key, or both.
Connection details
Open a trunk to see what to enter into your PBX:
| Setting | Value |
|---|---|
| SIP domain | The trunk's own domain. Copy it whole from the trunk page |
| Username | Always bird, on every trunk and every workspace |
| Password | The secret of an API key allowed on this trunk (see API key authentication) |
Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication.
Send your calls to the SIP domain on one of these ports:
| Transport | Port | Notes |
|---|---|---|
| UDP | 5060 | The default most equipment assumes |
| TLS | 5061 | SIP over TLS, for signaling you want encrypted in transit |
| TCP | 5062 | TCP has its own port, so set this explicitly on your PBX |
Controlling who may send calls
A trunk can recognize your equipment by the address it calls from, by an API key, or by both.
Both live on the trunk page, as the IP allow list and Allowed API keys sections. Saving a change there takes effect on the next call, so tightening access can cut off equipment that is mid-configuration.
IP allow list
Add the public addresses your equipment sends SIP from, as single addresses or CIDR ranges, each with an optional description. IP filtering becomes active the moment the list has one entry: from then on, only listed ranges may send calls to this trunk.
The address that matters is the one your traffic arrives from. For equipment behind NAT (a router or firewall that rewrites addresses as traffic passes through), that is the router's public address, not the private one configured on the phone system. A call from an address the list does not cover is turned away at the SIP layer, so it usually never reaches your call log at all. Voice troubleshooting covers a call that is missing from the log.
API key authentication
Bird can instead (or also) ask each call for a password. The exchange is SIP Digest authentication: Bird sends a challenge, your phone system answers with a hash of the password rather than the password itself, and Bird verifies it against a Bird API key.
- Create an API key with the voice scope at write level, which is the level a trunk authenticates against. The key's secret is shown once, at creation, so save it then. See API keys.
- On the trunk page, under Allowed API keys, add that key.
- In your PBX, set the username to bird and the password to the key's secret.
API-key authentication becomes active the moment the list has one key: from then on, only the keys you list may authenticate.
Revoking or deleting an API key removes its ability to authenticate immediately, on every trunk that allowed it. Rotate by adding the new key to the trunk first, moving your equipment over, then revoking the old one.
Digest algorithm
Bird challenges with SHA-256 first and MD5 second by default, and your PBX answers with the first algorithm it supports. The order matters because most equipment picks the first line it recognizes.
Change the offer under Digest algorithm when your equipment needs it. The common case is a PBX that implements only MD5 and mishandles a challenge that leads with SHA-256: set the trunk to MD5 only. A trunk accepts answers only in the algorithms it offers, so narrowing the offer narrows what gets in. Your keys work under either algorithm, so changing the offer never means reissuing them.
Delete a trunk
Deleting a trunk takes effect at once: its SIP domain stops accepting new calls. Calls already in progress continue, and the call records made through the trunk stay in your Call log.
Next steps
| Page | What it covers |
|---|---|
| Place your first call | From an empty workspace to a ringing phone in about ten minutes |
| Placing calls | What Bird expects on the INVITE, and what a call costs |
| Caller IDs | Registering a number and proving you own it with a verification call |
| API keys | Creating a key, choosing its scopes, and rotating it |