# Configuration

The plugin's options (`canCall()`, `video()`, `maxParticipants()`, `popOut()`, `iceServers()`, `deviceSettings()`, `notifications()`) are set per panel and covered in [Calling](https://packstub.dev/docs/filament-holler/calling) and [The call](https://packstub.dev/docs/filament-holler/the-call). Everything else lives in `config/holler.php`, which belongs to `packstub/holler`. Each key reads an env variable, so most apps never publish the file; when you want to edit it:

```bash
php artisan vendor:publish --tag=holler-config
```

## ICE servers (STUN / TURN)

What a call needs depends on where the two people are:

| The two people are | What the call needs | Set |
| --- | --- | --- |
| on the same network (an office, a VPN) | nothing | `HOLLER_STUN_URL=` (empty) if you want no outside server at all |
| on different networks, behind ordinary routers | a STUN server | nothing: this is the default |
| behind a strict NAT, a VPN or a corporate firewall | a TURN server | `HOLLER_TURN_URL` and a secret or a login |

So an intranet app runs with no outside service, the default covers most calls between homes and offices, and reaching everyone takes a TURN server, your own or a hosted one.

Two browsers need help to find a path to each other. A **STUN** server tells each one its public address, and for most calls that is enough: the media then goes straight from browser to browser. The package uses Google's public STUN server out of the box, free and without an account, so calls work right after the install:

```dotenv
HOLLER_STUN_URL=stun:stun.l.google.com:19302
```

Any other STUN server works the same way (`stun:stun.cloudflare.com:3478`, or your own), several can be listed with commas, and an empty value uses none. Public STUN servers come without a guarantee, so a production app that depends on calls usually runs its own beside the TURN server below (coturn does both).

Behind a strict NAT, a VPN or a corporate firewall no direct path exists, and the call needs a **TURN** relay that forwards the media. This is a minority of calls, but for the people on those networks it is every call. Point the package at a relay, your own [coturn](https://github.com/coturn/coturn) or a hosted service:

```dotenv
HOLLER_TURN_URL=turn:turn.example.com:3478,turns:turn.example.com:443?transport=tcp
HOLLER_TURN_SECRET=the-secret-coturn-shares-with-the-app
```

`HOLLER_TURN_URL` takes several addresses separated by commas. Listing a `turns:` address on port 443 over TCP beside the plain one is what gets a call through networks that only let web traffic out.

With `HOLLER_TURN_SECRET` every call gets a username and a credential that expire (after `HOLLER_TURN_TTL` seconds, 3600 by default), signed with the secret the TURN server shares with the app, so no long-lived password ever reaches a browser. It is coturn's `use-auth-secret` scheme:

```ini
# /etc/turnserver.conf
listening-port=3478
tls-listening-port=5349
realm=turn.example.com
use-auth-secret
static-auth-secret=the-secret-coturn-shares-with-the-app
cert=/etc/letsencrypt/live/turn.example.com/fullchain.pem
pkey=/etc/letsencrypt/live/turn.example.com/privkey.pem
```

A server with one fixed login takes `HOLLER_TURN_USERNAME` and `HOLLER_TURN_CREDENTIAL` instead of the secret.

A hosted TURN service (Cloudflare Realtime, Twilio, Metered and others) hands out short-lived credentials through its API. Ask for them in a closure and return what the browser should use:

```php
FilamentHollerPlugin::make()->iceServers(fn (): array => [
    ['urls' => 'stun:stun.example.com:3478'],
    ...Http::withToken(config('services.turn.token'))
        ->post(config('services.turn.url'), ['ttl' => 3600])
        ->throw()
        ->json('iceServers'),
])
```

The browsers ask for the servers each time a call starts (`GET /{panel}/filament-holler/calls/ice-servers`), never when the page loads: the closure runs per call, the credentials never sit in the page's HTML, and a tab left open all day still gets fresh ones. Any server in that list may carry `secret` (and `ttl`) instead of a username and credential, and is signed the same way; `Holler::turnCredentials($secret, $ttl)` returns the pair on its own.

ICE candidates show each side's network addresses to the other. To keep them private, send everything through your TURN server:

```dotenv
HOLLER_ICE_TRANSPORT_POLICY=relay
```

A TURN relay forwards packets it cannot decrypt (WebRTC media is encrypted end to end with DTLS-SRTP).

### Why Laravel cannot be the relay

The signaling (who calls whom, the offers and answers) goes through your Laravel routes. The audio and video cannot: a browser sends them over UDP or a long-lived socket, to the other browser or to a TURN server, and offers no way to send them through HTTP requests. A relay is therefore always a TURN server. [coturn](https://github.com/coturn/coturn) is one small daemon on any server with a public address, it answers STUN too, and with `HOLLER_TURN_SECRET` it is all the app needs.

### When a call does not connect

A call that rings and is answered but never shows the other person ends after `HOLLER_RECONNECT_TIMEOUT` with "Could not connect" on both sides: the browsers found no path to each other. The usual reasons:

- **No TURN server, and one side is on a strict network.** The browser console says so. Add a TURN server, with a `turns:` address on port 443 for the strictest networks.
- **A TURN server that refuses.** Wrong, expired or removed credentials look the same as no server at all. Open `chrome://webrtc-internals` (`about:webrtc` in Firefox) during a call and look for `icecandidateerror`: a code in the 400s means the server turned the login down, 701 means it could not be reached.
- **`HOLLER_ICE_TRANSPORT_POLICY=relay` without a working TURN server.** Every call then has to go through the relay, so none connects, also on one network. Remove the line or fix the server.

To check a TURN server on its own, set `HOLLER_ICE_TRANSPORT_POLICY=relay` for a moment and call between two tabs on your own machine: the call connects only when the relay works.

A call that connected and then ends with "Connection lost" had a path and lost it (a laptop that went to sleep, a network that dropped) for longer than the timeout. During a call a "Weak connection" badge on someone's picture means many packets to or from them are being lost or arrive late.

## Polling and timeouts

Every open panel tab asks the server for incoming calls every 5 seconds and, during a call, for signals every second; that poll is also the heartbeat that tells the other side you are still there. Hidden tabs poll less often.

| Variable | Default | |
| --- | --- | --- |
| `HOLLER_POLL_IDLE` | 5000 | milliseconds between polls without a call |
| `HOLLER_POLL_ACTIVE` | 1000 | milliseconds between polls during a call |
| `HOLLER_RING_TIMEOUT` | 45 | seconds before a call nobody answers is marked missed |
| `HOLLER_RECONNECT_TIMEOUT` | 15 | seconds a side may be away before the call ends as lost |
| `HOLLER_MAX_PARTICIPANTS` | 4 | people on one call, the caller included; `maxParticipants()` overrides it |
| `HOLLER_VIDEO` | true | `false` makes every call a voice call |
| `HOLLER_POP_OUT` | true | the pop-out on panels without SPA mode; `popOut()` overrides it |
| `HOLLER_PRUNE_AFTER_DAYS` | 90 | ended calls older than this go at `holler:prune` |
| `HOLLER_DB_CONNECTION` | default | the central connection, under a database per tenant |

The limits on signals (`HOLLER_MAX_SIGNAL_KB`, `HOLLER_MAX_PENDING_SIGNALS`) and the rest of the file are documented in [Holler for Laravel](https://packstub.dev/docs/holler/configuration). Its `guard` key does not apply here: inside a panel the panel's guard is used.

## Events and the call log

```php
use Packstub\Holler\Events\CallEnded;

Event::listen(CallEnded::class, function (CallEnded $event) {
    $event->call->caller_id;     // user ids as strings
    $event->call->callee_id;     // the first person called
    $event->call->participants;  // everyone, with seat, status and times
    $event->call->end_reason;    // declined | cancelled | missed | hung_up | dropped
    $event->call->duration();    // seconds, null if never answered
});
```

The other events are `CallStarted`, `CallAnswered`, `ParticipantJoined` and `ParticipantLeft`. `Packstub\Holler\Models\Call` is a plain Eloquent model over the `holler_calls` table, ready for a resource of your own.
