SIP client setup

Any SIP client that can place a call through a proxy works with a Bird trunk: a full PBX (the system that places your calls), a softphone on your laptop, a CLI tool in a test script. This page maps the trunk's connection details onto the fields each one asks for, and covers the two settings that catch people out whatever they are running.

What a client needs

Four values, all from the trunk page:

Client field	What to enter
SIP server, domain, host, or proxy	The trunk's SIP domain
Port and transport	One of the trunk's supported ports
Authentication user, auth user, or login	bird, on every trunk and every workspace
Password or secret	The secret of an API key allowed on the trunk

A trunk that uses only its IP allow list needs the first two. The credentials are what API key authentication adds.

The configurations on this page write those values as YOUR_TRUNK_DOMAIN, YOUR_CALLER_ID and YOUR_API_KEY_SECRET. Copy the domain whole from the trunk page rather than assembling it: Bird recognizes a call by the exact domain it was addressed to, and a call to any other is turned away before it reaches your call log. With the Bird CLI signed in, bird voice tools test-call --dry-run prints those values as a working baresip account line, a starting point for any client on this page.

Leave any realm or authentication domain field empty so your client answers with the realm Bird sends in the challenge. A client that insists on a value wants your workspace ID with its wsp_ prefix removed, followed by .sip.bird.com. That is the workspace's realm, and it is not the trunk's SIP domain.

Place calls without registering

Bird authenticates every call on its own, so a trunk has nothing to register against: your client sends its INVITE and Bird checks that call, either against the trunk's IP allow list or with a password challenge.

This is the setting to find first, because most softphones register by default and a PBX only does so when you tell it to:

In a PBX, configure Bird as a trunk and leave registration off. Asterisk means no type=registration section; FreeSWITCH means register=false on the gateway; FreePBX and 3CX have a registration mode to set to none.
In a softphone, turn registration off in the account's advanced settings if it offers the choice. Where it does not, the failed registration attempt is cosmetic and dialing still works, because Bird decides on the INVITE.

Two identities, two fields

Your client presents two different names, and clients that share one field for both are the usual reason a first call is refused:

The caller ID goes in the From header, and it has to be a number you have verified, in E.164 format: a leading + followed by the country code and national number. In most clients this is the account's user or caller-ID field.
The digest username is always bird. In most clients this is the authentication user or login field.

Dial in E.164 too, since that is what Bird routes and prices on.

Softphones

A softphone is the quickest way to prove a new trunk works before you point production traffic at it.

baresip

Add one line to ~/.baresip/accounts, with your caller ID as the account user and bird as the auth user:

代码示例

<sip:YOUR_CALLER_ID@YOUR_TRUNK_DOMAIN>;auth_user=bird;auth_pass=YOUR_API_KEY_SECRET;regint=0;outbound="sip:YOUR_TRUNK_DOMAIN;transport=udp"

regint=0 is what stops baresip registering. Start it and dial with /dial +31612345678.

Zoiper

Add a SIP account by hand rather than letting the wizard probe for a provider. Set Domain to the trunk's SIP domain, Username to your verified caller ID, Password to the API key secret, and under the account's advanced settings set Auth username to bird and turn off registering on startup. Pick the transport there too.

Linphone

Add an account with bird as the SIP identity's auth user and your caller ID as its username, then disable registration on the account. In linphonerc the same account is a [proxy_N] section with reg_sendregister=0.

MicroSIP

Under Account: SIP server is the trunk's SIP domain, Username your verified caller ID, Login bird, Password the API key secret. Leave Domain the same as the SIP server.

PBXs

Asterisk

In pjsip.conf, an endpoint with outbound auth and no registration section:

代码示例

[bird-auth]
type=auth
auth_type=userpass
username=bird
password=YOUR_API_KEY_SECRET

[bird-aor]
type=aor
contact=sip:YOUR_TRUNK_DOMAIN:5060

[bird]
type=endpoint
context=from-internal
outbound_auth=bird-auth
aors=bird-aor
from_user=YOUR_CALLER_ID
from_domain=YOUR_TRUNK_DOMAIN

from_user is the caller ID Bird checks, so it has to be a verified number. Dial with Dial(PJSIP/+31612345678@bird).

FreePBX

Under Connectivity > Trunks, add a SIP (chan_pjsip) trunk. In its pjsip Settings, set Username to bird, Secret to the API key secret, SIP Server to the trunk's SIP domain, Authentication to outbound, and Registration to none. Set the trunk's outbound caller ID to a verified number.

FreeSWITCH

A gateway in conf/sip_profiles/external/bird.xml:

代码示例

<include>
  <gateway name="bird">
    <param name="proxy" value="YOUR_TRUNK_DOMAIN"/>
    <param name="register" value="false"/>
    <param name="username" value="bird"/>
    <param name="password" value="YOUR_API_KEY_SECRET"/>
    <param name="from-domain" value="YOUR_TRUNK_DOMAIN"/>
    <param name="caller-id-in-from" value="true"/>
  </gateway>
</include>

With caller-id-in-from set, the caller ID on the leg becomes the From number, so set it to a verified one when you originate.

3CX

Add a generic SIP trunk, choose the registration mode that does not register, and set the trunk's host to the trunk's SIP domain. Put bird in the authentication ID and the API key secret in the password. The trunk's outbound caller ID has to be a verified number.

Next steps

Page	What it covers
Voice troubleshooting	Diagnosing a call that does not go through, from its symptom
SIP trunks	The connection details, the allow lists, and the Digest offer
Placing calls	What Bird expects on the INVITE, and how a call is priced
Caller IDs	Registering a number and proving you own it with a verification call
Call log	Confirming a call went out, and what it cost