Trunk Monitor: sub-second SIP trunk health for Genesys Cloud, with the evidence

It is 14:10 on a Tuesday and the service desk has a cluster of tickets: inbound callers hearing silence, outbound campaigns stalling. The IT Systems, Telecoms & SIP Engineer joins the bridge and everyone looks at them. Is the carrier trunk down? Did calls fail over to the backup trunk? What was our concurrent-call peak this afternoon, and at exactly what second did things change? Those answers decide whether you call the carrier, the network team or nobody at all.

Answering them usually means flicking between screens and copying timestamps by hand. Trunk Monitor exists to make that one view. For every monitored trunk it shows health – connected or disconnected per Edge instance, Edge state and OPTIONS-ping status – and live utilisation, with active inbound and outbound call counts charted on a rolling five-minute window and a zoomable session history of up to three hours.

Genesys Cloud has good native trunk visibility, and our engineers use it every day. On the Trunks page, the External Trunks and Phone Trunks tabs show a colour-coded status icon with a tooltip, and the Status dialog lists the Edges a trunk connects to and the network interface it uses. The Edge page shows trunk status in its Information panel. The documented indicators range from “Up and running” through “Working partially” to “Error/Down”, with messages such as failing availability checks or failing registration requests.

For volumes, the Telephony Metrics page lets you build a dashboard of widgets – trunk call counts and QoS mismatches across BYOC Premises, BYOC Cloud and Genesys Cloud Voice – shown as gauges or bar charts for the current value, or as line graphs for a chosen time period. More broadly, the Operational Console lists actionable operational events from across the platform, keeps them for 10 days, and can feed triggers, alert rules and an Amazon EventBridge integration. Trunk Monitor does not replace any of this. It focuses on a single incident-time job: trunk health and call volume, together, live, with a timestamped record.

The core engineering idea is fusion. Every five seconds the server polls GET /api/v2/telephony/providers/edges/trunks/metrics for the monitored trunks, passing trunkIds as a single comma-separated value and chunking requests at 50 IDs. That poll is the authoritative time series: each one appends exactly one history point per trunk, and the server keeps a 60-point rolling window that it re-sends with every update, so short gaps on the client heal themselves.

In parallel, one Genesys notification channel per session subscribes two topics per trunk: v2.telephony.providers.edges.trunks.{id} for health – connected state, Edge state and OPTIONS status – and v2.telephony.providers.edges.trunks.{id}.metrics for call counts. Pushed events update the counters, KPI tiles and sidebar between polls, so a trunk going down shows up in sub-second time rather than at the next tick.

The fusion rule keeps the charts honest. Points are added to the charts only from poll results, at uniform five-second spacing, so a burst of pushed events never jitters the time axis. WebSocket metric events update the live numbers instantly but wait for the next poll to become history. A small source chip in the event log flips between poll and ws to show which feed spoke last, so an engineer always knows where a number came from.

At sign-in the server pages through every trunk in the organisation, 100 at a time, and keeps the ones that matter on an incident bridge: every trunk of type EXTERNAL, plus, optionally, PHONE trunks whose names match a carrier-facing naming convention set for the deployment. EDGE trunks, the inter-Edge ties, are always excluded. If nothing matches, the app falls back to every non-EDGE trunk and says so in the event log, so nobody wonders why a trunk is missing.

Genesys creates one trunk object per Edge instance, named with the base name followed by a UUID suffix. The sidebar strips that suffix and groups instances by base name, so a carrier trunk running on two Edges is one card with a “2 edges” badge and a health dot: green when every instance is up, amber when partial, red when all are down. Each card carries a sparkline of recent inbound readings and live in/out counters, and cards sort busiest first, which is exactly where your eye should go.

Above the charts, a six-tile KPI strip gives the bridge its headline numbers: how many trunk groups are monitored, how many are fully connected – with a “partial” subtitle when a group is half-up – how many are disconnected or partial, active inbound and outbound calls summed across visible trunks, and the wall-clock time of the newest data. These tiles update the instant a WebSocket event lands; they never wait for the next poll. Clicking a sidebar card hides that trunk group from both charts and from the history totals, which is how an engineer isolates the primary and backup carrier trunks and watches traffic move between them.

Every UP or DOWN transition is written to a newest-first health event log, with the group’s “x/N edges up” context, alongside notification-channel status changes, poll errors and the sign-in filter note. The same moment drops a vertical annotation line on both charts at the exact timestamp. On the live chart, inbound is drawn above the zero line and outbound mirrored below it, so a drain from one trunk to another is visible as two lines crossing at the annotation.

When the bridge moves on to the write-up, the engineer zooms the session-history chart into the incident window – mouse wheel or pinch, drag to pan – and exports it as a PNG with the annotations included. Long series are decimated with an algorithm that preserves peaks, so the concurrent-call high point survives the zoom. The result is a picture of what happened, when, and on which trunk, produced in seconds rather than reconstructed afterwards.

A monitor that silently stops streaming is worse than no monitor, so most of the engineering effort went into the failure paths. The server sends the JSON heartbeat Genesys expects every 30 seconds and terminates the socket if the channel.metadata reply does not arrive within 10 seconds. After any close it waits 10 seconds and rebuilds a fresh channel and subscriptions, with a guard against duplicate reconnects. Polling continues throughout, so the charts never stop. The OAuth token is refreshed 60 seconds before expiry with a single-flight guard.

We also documented a data characteristic we met during testing: the trunk metrics endpoint returns rows only for Edge-registered, reachable trunks, so BYOC Cloud trunks and fully offline trunks yield no metric rows, although health can still arrive through notifications. The app logs that explicitly rather than drawing a misleading flat line. And every teardown path clears the channel’s subscriptions, so the organisation’s notification quota is always released.

We made one deliberate trade-off visible to users. Each session has exactly one live browser feed, and when that feed closes – a reload, a closed tab, a machine going to sleep – the server treats it as a sign-out and runs a single shared cleanup path: stop the poller and heartbeat, close the Genesys socket and clear the channel subscriptions. Region and client ID are remembered, so signing back in takes only the secret, and the rolling window refills within a few polls. The guarantee in return is that no forgotten tab can leave a channel consuming the organisation’s quota.

Trunk Monitor signs in with an OAuth client-credentials grant whose role carries the Telephony read permission, telephony:plugin:all. Against Genesys it issues reads plus the notification-channel calls that manage its own feed; it never modifies telephony configuration. There is no database: sessions, trunk snapshots and chart history live in memory for the lifetime of a session, and the dashboard never sees your client secret.

The squad that built it is the same one we muster for telephony projects. An IT Systems, Telecoms & SIP Engineer defined the operational questions; a Solution Architect designed the fusion rule and recorded the decision; Senior Developers built to the Senior Platform Practice Lead’s standards with four-eyes review; and a Systems Integration Tester proved the negative paths – a dropped Genesys socket, a missed pong, an empty metrics poll, a laptop that went to sleep mid-incident.