SIP client setup

Any SIP client that can place a call through a proxy can use a Bird trunk. This includes PBXs, desktop softphones, and command-line tools. This page maps the trunk's connection details to common client fields and authentication settings.

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 examples use YOUR_TRUNK_DOMAIN, YOUR_CALLER_ID, and YOUR_API_KEY_SECRET. Copy the complete domain from the trunk page. Bird refuses calls to another domain before they reach your call log. When signed in with the Bird CLI, run bird voice tools test-call --dry-run to print these values as a baresip account line.

Leave realm or authentication domain empty so the client uses the realm in Bird's challenge. If a client requires a value, use the workspace ID without its wsp_ prefix, followed by .sip.bird.com. The workspace realm differs from the trunk's SIP domain.

Place calls without registering

Bird authenticates each INVITE against the trunk's IP allow list or through a password challenge. Clients do not register with the trunk.

Check registration before placing a call:

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 we act on the INVITE rather than on the registration.

Two identities, two fields

Your client must send two different identities:

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:

Ejemplo de código

<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 manually. Set Domain to the trunk's SIP domain, Username to your verified caller ID, and Password to the API key secret. In advanced settings, set Auth username to bird, disable registration on startup, and choose the transport.

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:

Ejemplo de código

[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:

Ejemplo de código

<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 and disable registration. Set its host to the trunk's SIP domain, its authentication ID to bird, and its password to the API key secret. Set the outbound caller ID to 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