Real-time events vs media

People often assume “live calls in the browser” means the browser is carrying the voice. In CXGear today, those are two different layers:

Signaling — “a call is ringing,” “you are on a call,” “presence changed”
Media — the actual voice audio

Understanding the split explains why the call floater can appear without browser microphone permission, and why admins do not see constant dialler traffic.

The two layers

Layer	Job	Technology today
Signaling	Tell the UI what is happening	Server-Sent Events (SSE) event stream
Media	Carry voice	Desk phone / SIP on your PBX; browser WebRTC softphone later

PBX / carrier  ──media (audio)──►  Desk phone or SIP client
       │
       └──events──►  CXGear API  ──SSE──►  Agent browser (floater, presence)

CXGear is the control plane. Your telephony stack is the media plane.

Screenshot needed

Agent desk showing presence and extension, with a note that audio is on the desk phone.

Where: Dialler → Agent desk

Save as: src/assets/screenshots/42-realtime-vs-media.png

What SSE (the event stream) does

When an agent is configured (role + extension, not offline), the browser opens a long-lived event stream to CXGear. That stream pushes updates such as:

Incoming ring offer
Active call state
Presence-related snapshot fields

It is not polling every second with REST for every admin. Only agents who need live call UI keep the stream open. If you are an admin without agent setup, CXGear closes the stream and you will not see a flood of dialler API calls.

That design keeps the product quiet for operators who only configure projects and billing.

What media does

Voice still needs a path:

Setup	Where you hear the customer
Desk phone / SIP today	Physical phone or softphone registered to your PBX extension
WebRTC later	Microphone and speaker in the browser (softphone mode)

The floater even reminds agents: audio connects on the desk phone when they answer. Clicking Answer in CXGear is a control action; the PBX connects the media legs.

Why this matters

For agents

You do not need to grant browser mic access for desk-phone mode.
Keep your desk phone registered to the same extension you saved in CXGear.
If the floater works but you hear nothing, the problem is almost always media (phone/PBX), not the event stream.

For admins and IT

Firewall and network rules for SIP/RTP are separate from HTTPS to CXGear.
Event stream needs a stable HTTPS connection to the API.
Debugging “no ring in UI” vs “no audio on phone” are different tickets.

For product expectations

CXGear is a communication OS: outreach, dialler, and (roadmap) conversations. The dialler UI is live and real-time for coordination. Full in-browser softphone media is a later step on the same foundation.

What success looks like

Agent goes Available → event stream opens (no noisy polling for non-agents).
Inbound offer appears on the floater quickly.
Answer connects audio on the registered desk phone.
Hangup / end events clear the bar without a full page refresh.
Admin accounts without agent setup stay free of dialler stream traffic.

Common problems

Symptom	Layer	What to try
No floater, phone rings	Signaling	Extension, presence, agent role, inbound route
Floater works, silence	Media	Desk phone registration, extension match, PBX logs
Stream drops on sleep / VPN	Signaling	Wake laptop, reconnect network, refresh and go Available
Constant dialler requests as admin	Unexpected	Confirm you are not also an agent with extension set
Expecting browser mic today	Product stage	Use desk phone; WebRTC softphone is planned, not required now

Mental model cheat sheet

You want…	Look at…
Who is offered the call	Presence, roles, routing
Whether the UI updates live	SSE agent stream
Whether anyone can hear anyone	Trunks, extensions, PBX media
Whether a list can dial out	Outbound routes + trunks