Skip to content
CXGear CXGear Docs

Inbound call floater

When a customer calls in, agents should not hunt through menus. The inbound call floater is a floating bar that appears on top of whatever page they are on so they can Answer or Decline immediately.

It is the agent’s “doorbell” for live voice.

What it is

Section titled “What it is”

A compact bar that shows:

  • That a call is incoming
  • The caller’s phone number
  • A short note that audio connects on the desk phone when they answer
  • Decline and Answer actions

After answer, the same bar becomes the active call controls (timer, hangup, mute, hold, and related actions when enabled).

Screenshot needed
Floating inbound call bar in ringing state with Answer and Decline.
Where: Any page during an inbound ring (agent logged in)
Save as: src/assets/screenshots/25-call-floater.png

Why it exists

Section titled “Why it exists”

Agents live in Records, Jobs, Live Ops, and project pages. Forcing them to open Dialler every time a call arrives would mean missed rings. The floater follows them across the app so presence stays useful wherever they work.

CXGear only shows the bar to users who are set up as agents (role + extension). Admins who are not agents never see it — and that is intentional.

How it works (in plain language)

Section titled “How it works (in plain language)”
  1. An inbound DID hits your PBX.
  2. Routing maps that DID to an agent extension.
  3. CXGear signals the agent’s browser that a call is ringing (via the live event stream).
  4. The floater appears.
  5. The agent clicks Answer or Decline.
  6. Voice audio runs on the desk phone (or SIP softphone), not inside the browser tab today.

The browser is for control and awareness. The phone is for hearing and speaking.

Screenshot needed
Active call floater after answer, showing timer and hangup controls.
Where: Any page during a connected call
Save as: src/assets/screenshots/40-call-floater-active.png

Prerequisites

Section titled “Prerequisites”

Before the floater can appear:

RequirementWhere
Agent or Supervisor role (or custom role with dialler agent permissions)Manage users
Extension savedDialler → Agent desk
Presence not Offline (usually Available)Dialler → Agent desk
Inbound route for the DIDDialler → Call routing
Telephony gateway healthyIntegrations → Telephony

If any of those are missing, the bar stays hidden even when the PBX rings.

What success looks like

Section titled “What success looks like”
  • Agent is Available with a valid extension.
  • Test inbound call shows the floater within a second or two.
  • Answer connects audio on the desk phone; the bar switches to connected state with a timer.
  • Decline clears the offer and the agent can take the next call.
  • After hangup, presence moves toward wrap-up / available as your process expects.

Common problems

Section titled “Common problems”
SymptomLikely causeWhat to try
No floater at allUser is not an agent, or extension unsetAssign Agent role; save extension on Agent desk
Floater never for adminsExpected — admins do not open the agent streamUse an agent account for live tests
Floater shows but no audioDesk phone not registered / wrong extensionFix PBX registration; match extension exactly
Missed calls while on another tabBrowser tab suspended or stream closedKeep CXGear open; check network; refresh and go Available again
Bar stuck after call endsSession status not updated from telephony eventsConfirm gateway posts call lifecycle events with the correct API key
Section titled “Related ideas”

Next

Section titled “Next”