# 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](/docs/guides/voice/sip-trunks#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](/docs/guides/voice/sip-trunks#connection-details)             |
| Port and transport                       | One of the trunk's [supported ports](/docs/guides/voice/sip-trunks#connection-details) |
| 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](/docs/guides/voice/sip-trunks#ip-allow-list) needs the first two. The credentials are what [API key authentication](/docs/guides/voice/sip-trunks#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](/docs/guides/voice/call-log). With the [Bird CLI](/docs/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](/docs/guides/voice/caller-ids), 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](/docs/guides/voice/placing-calls#what-bird-expects-on-the-invite).

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

```text
<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:

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

```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](/docs/guides/voice/troubleshooting) | Diagnosing a call that does not go through, from its symptom         |
| [SIP trunks](/docs/guides/voice/sip-trunks)                 | The connection details, the allow lists, and the Digest offer        |
| [Placing calls](/docs/guides/voice/placing-calls)           | What Bird expects on the `INVITE`, and how a call is priced          |
| [Caller IDs](/docs/guides/voice/caller-ids)                 | Registering a number and proving you own it with a verification call |
| [Call log](/docs/guides/voice/call-log)                     | Confirming a call went out, and what it cost                         |