SIP.js browser calling: package, media and lifecycle boundaries

Pin the package and migration path

The project's release archive still marks 0.21.2 as Latest at the October 8, 2026 review. Pin the exact package and application build instead of treating the main branch, CDN alias or old example as the deployed contract. Release 0.21.0 moved the project to ECMAScript modules, introduced SessionManager, changed the SimpleUser register signature and removed UserAgent auto-start and auto-stop options; 0.21.2 added an optional SessionManager SIP OPTIONS ping and fixed a registration-expiry option.

The migration guide says normal package installations should remain compatible, but custom builds, forks and development processes may be affected by NodeNext module resolution and fully specified imports. Treat that as a rebuild-and-test boundary rather than proof that an existing bundle will continue to load. Review every intervening release, test the application against a contained account and retain a rollback artifact.

Keep the release label and security-policy table separate

The same first-party repository currently exposes two different statements: its release archive labels 0.21.2 Latest, while its published security-policy table lists 0.19.x as supported and versions below 0.19.x as unsupported. The table does not state whether 0.20.x or 0.21.x receives security fixes, and the absence of a published advisory is not a support commitment.

Record both statements with the retrieval date and obtain maintainer or supplier clarification before making a support claim. Do not relabel 0.21.2 as security-supported merely because it is the newest release, and do not infer that 0.21.2 is vulnerable merely because it is omitted from the table. Package currency, maintenance policy, vulnerability status and application acceptance remain separate decisions.

Use SimpleUser only within its documented limits

The current Simple User guide demonstrates explicit connect and register calls, hold and unhold, and DTMF sent through SIP INFO. The repository describes broader SIP.js support for hold, transfers and DTMF through RFC 2833 or SIP INFO, while SessionManager is the documented multi-session layer. Those surfaces are not interchangeable contracts.

Choose SimpleUser, SessionManager or the full API from the workflow the application must own, then pin the imports and acceptance cases to that choice. A method appearing in a guide or repository overview does not prove the selected abstraction, PBX, gateway or far end supports the same signaling and media behavior.

Keep the library separate from the phone product

The full SIP.js API supplies registration, session and subscription infrastructure but no application interface. The product owner still controls sign-in and credential lifecycle, accessible call controls, device selection, error states, logs, privacy notices and support ownership. Do not expose long-lived PBX credentials in client code or describe a successful library import as a deployable phone.

Prove signaling and media as separate paths

Use a secure web origin and a trusted WSS endpoint, then match the PBX WebSocket transport to the installed server release. Treat browser permission, microphone selection, SIP registration, INVITE handling, ICE connectivity and negotiated audio as distinct checkpoints. A lock icon, connected WebSocket or successful REGISTER does not prove two-way media.

The published Asterisk configuration guide is a starting example, not a current-version acceptance result. Verify ICE, STUN or TURN behavior and the actual SDP, DTLS and SRTP path in the target network without silently downgrading transport security.

Design browser lifecycle and recovery

Define what the application does after a laptop sleeps, the network changes, a tab is suspended or the browser exits. Reconnect the transport deliberately, restore or renew registration as appropriate, expire abandoned sessions and show the user a truthful state. The optional OPTIONS ping introduced in 0.21.2 can add an observation point; it does not prove registration, inbound reachability or call media.

Document alternative routing for an unavailable browser, along with credential revocation and emergency-calling boundaries. A foreground demonstration should not be presented as evidence of background reachability.

Do not turn mobile browser compatibility into background reachability

The SIP.js mobile guide says Chrome and Firefox on Android are WebRTC-capable and compatible with SIP.js web applications. That is a foreground browser-compatibility statement. It does not define iOS behavior, a native wrapper, push notification delivery, service-worker calling, locked-screen wake-up or survival after the browser suspends or closes the page.

Name the exact browser or wrapper, operating system, page state, notification path and fallback route. Prove incoming-call behavior after the intended idle, sleep and network-change cases before describing a mobile webphone as reachable.

Build an evidence-based acceptance matrix

Record the exact SIP.js build, browser versions, operating systems, PBX branch and network path. Check inbound and outbound calls, rejection and cancellation, hold and transfer only where the selected API supports them, DTMF, audio-device changes, permission denial, tab closure, sleep and network recovery. Capture signaling and media evidence from systems you are authorized to inspect.

This guide reports documentation review only. It does not claim that SIP.js 0.21.2, a named browser or a particular PBX combination was lab validated.

Instrument the incoming Invitation before debugging ringtone audio

SIP.js routes a received INVITE to the UserAgent delegate's onInvite handler. The browser no-ring diagnostic records that event and Invitation before testing application state, autoplay policy or media elements.