Endpoints
Holler::routes() registers nine JSON routes and the pop-out page. The widget and @packstub/holler talk to them; this page is for writing another browser client, or another backend for @packstub/holler. Paths are relative to the prefix (calls by default) and names to as (holler.).
Routes
| Method | Route | Name | Does |
|---|---|---|---|
POST |
/ with {callee, tab} or {callees: [...], tab} |
store |
ring one person, or up to 16 ids at once (the call still stops at max_participants) |
POST |
{id}/answer with {tab} |
answer |
someone rung joins; the call becomes active the first time |
POST |
{id}/decline |
decline |
someone rung says no; someone already on the call leaves it |
POST |
{id}/hangup |
hangup |
leave the call; it goes on for the others and ends once fewer than two are left |
POST |
{id}/invite with {callee} |
invite |
add someone to the call I have joined |
POST |
{id}/hold |
hold |
step out of a running call without leaving it; I stay on it as on_hold |
POST |
{id}/resume with {tab} |
resume |
back into the call I put on hold; a call I am in meanwhile goes on hold instead |
GET |
people?q={words}&call={id} |
people |
{people: [{id, name, avatar}]}: who I can ring, or add to that call; up to 8 |
POST |
{id}/signals with {type, payload, to?} |
signal |
queue an offer, answer, ice, reset or state (mute, camera off, screen share) for one participant (to) or for everyone else on the call |
POST |
{id}/leave with {tab} |
leave |
a beacon as the window unloads: the side is free for the next page |
GET |
poll?after={cursor}&call={id}&tab={tab}&hold=1&kind=call |
poll |
{call, incoming, on_hold, signals, cursor}, see below |
GET |
ice-servers |
ice |
{iceServers, iceTransportPolicy}, asked when a call starts and never cached |
GET |
window?call={id}&callee={user} |
window |
the widget's pop-out page; left out with window: false |
Every route answers 401 to someone who is not signed in, and the routes with a call id answer 403 to anyone who is not on that call (or is on it from another scope).
The browser files are served outside Holler::routes(), without auth: GET holler/assets/{index.js|widget.js|widget.css}, named holler.asset. Holler::asset('widget.js') gives a URL with a version in it, cached for a year.
Polling
One request, repeated by every window: every 5 seconds without a call, every second while one rings or runs.
call: the call this window names withcall=, or else any call I have joined and not left, for a page that just loaded. A call named withcall=is returned after it ended too, so the window learns theend_reason.incoming: a call ringing me, if any.on_hold: the call I put on hold, if any. It is no window'scallmeanwhile, and every poll of mine keeps it: someone on hold who stops polling forhold_timeoutseconds is dropped from the call.signals: my new signals afterafter, as{id, call, type, payload, from}, at most 100 per poll. Only the window that claimed my side gets them.cursor: the last signal id, for the nextafter.
claim=1 asks for this window to claim my side of the call named by call=, and doubles as the heartbeat the other side watches. kind limits call and incoming to calls of that kind; the widget sends kind=call. Each poll also marks people who did not answer in time as missed and people who went quiet as dropped.
Windows and reconnecting
Every window picks a random tab id. Each participant's side of a call belongs to one window at a time: the window that claimed it gets the signals and keeps the side by polling. A window that stops polling for 5 seconds loses it, and a leave beacon frees it at once.
A fresh page (a reload, or the pop-out taking over) claims the side on its first poll, sends reset and a new offer to each peer, and they build new connections to it. Signals meant for the old connection are skipped. If nobody claims the side within HOLLER_RECONNECT_TIMEOUT (15 seconds), that person is dropped from the call.
Signals are deleted once the window that claimed the side has read them, and all of a call's signals when it ends.
The call
present() returns a call as one person sees it, and every route that returns a call uses it:
{
"id": 12,
"kind": "call",
"status": "active",
"end_reason": null,
"role": "caller",
"seat": 0,
"joined": true,
"peers": [
{"id": "5", "name": "Ana", "avatar": null, "seat": 1, "status": "joined", "claimed": true, "seen_ago": 0}
],
"peer": {"id": "5", "name": "Ana", "avatar": null},
"peer_claimed": true,
"peer_seen_ago": 0,
"on_hold": false,
"claimed_elsewhere": false,
"answered_at": "2026-11-10T09:30:00+00:00"
}
roleiscallerorcallee;statusisringing,activeorended; a participant'sstatusisringing,joined,left,declined,missedordropped.end_reasonisdeclined,cancelled,missed,hung_upordropped, or whatever your code passed toHoller::end().- Between two participants, the lower
seatmakes the WebRTC offer. claimed_elsewhereis true when another window of mine (a pop-out) has claimed my side;claimedon a peer says whether a window has claimed theirs, andseen_agois the seconds since it last polled.on_holdis true when I put the call on hold.peer,peer_claimedandpeer_seen_agodescribe the first live peer, which is all a 1-on-1 client reads.
User ids are strings everywhere, so integer and UUID keys both work.
Errors
Errors are {message, reason}. message is for people (from the holler::messages translations); reason is for code, so a client can tell the two 409s apart:
| Status | reason |
When |
|---|---|---|
| 422 | not_allowed |
yourself, nobody, someone the context refuses, someone already on the call, inviting before you joined, or a signal from or to someone not on the call |
| 422 | full |
more people than max_participants |
| 409 | busy |
the person is on another call |
| 409 | not_ringing |
answering a call that no longer rings you |
| 410 | ended |
a signal or an invite for an ended call |
| 413 | too_large |
a signal above HOLLER_MAX_SIGNAL_KB |
| 429 | too_many |
more than HOLLER_MAX_PENDING_SIGNALS of your signals still unread on the call |
A request that fails validation gets Laravel's usual 422 with errors.