> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Conference failure-attribution analytics

> Break down every failed conference leg into where the failure happened — Orbit, your provider routing, or the destination network — then use the dashboard's failure-insights tab to find the pattern and fix it.

# Conference failure-attribution analytics

Not every failed conference leg means the same thing. One leg drops because the
destination's PBX rejected the codec. Another fails because the trunk was
unregistered at dial time. A third rings out to no answer. A failure count
alone tells you *how many* — the attribution model tells you *whose side* and
*what to do next*.

The conference failure-analytics surface answers those questions in one view,
both in the dashboard's **Voice → Conferences → Failure insights** tab and
through the `GET /voice/conferences/failure-analytics` API.

## 1. Conferences hub map

The Conferences hub (`Voice → Conferences`) has three tabs:

| Tab | What it covers |
| - | - |
| **Active rooms** | Live conferences in progress — participant roster, recording controls, mute/kick/hold per leg. |
| **History** | Past conferences with per-room summaries: start time, duration, participant count, terminal status. |
| **Failure insights** | The analytics tab covered on this page — failure rates, attribution breakdown, top reasons, and affected destinations for every failed leg in your selected window. |

The Failure insights tab is the operator-facing triage surface: it answers
"are my conferences getting worse, and why" without cross-referencing logs.

## 2. Failure-attribution model

Every failed conference leg falls into one of three attribution classes. The
platform classifies each leg automatically; you see the roll-up in the tab
and the API response without having to classify legs yourself.

### Orbit-side failures

A failure that happened before the call ever left Devotel's control plane: an
unowned caller ID, insufficient credit, an unregistered trunk, or a compliance
gate that refused the dial. The leg was never handed off to a provider, so the
upstream routing never saw it.

**Typical codes:** `CONF_CALLER_ID_NOT_OWNED`, `CONF_INSUFFICIENT_CREDIT`,
`CONF_TRUNK_UNREGISTERED`, `VOICE_BLOCKED_DESTINATION`,
`TCPA_DIALING_WINDOW_BLOCKED`, `DNC_CONTACT`.

### Provider-routing failures

A failure that occurred on the carrier or softswitch side AFTER Devotel handed
off the call: a SIP 5xx from the upstream provider, a `CALL_FAILED` rejection
from the gateway, a `VOICE_GATEWAY_ERROR` (unreachable or transient fault), or
a `CONF_PROVIDER_ERROR` from the dial path. The destination network never
answered; the call broke in transit.

**Typical codes:** `CALL_FAILED`, `CONF_PROVIDER_ERROR`,
`VOICE_GATEWAY_ERROR`, `SIP_500` through `SIP_599`.

### Destination-network failures

A failure that happened AT the far end: the destination rang and was busy,
declined, or timed out with no answer — or the destination's own equipment
(PBX, SBC, handset) answered and hung up immediately. The provider routing
succeeded; the destination itself is the reason the leg did not bridge.

**Typical codes:** `SIP_486` (busy), `SIP_480`/`SIP_487` (no answer /
cancelled), `SIP_603` (decline), `NO_ANSWER` (ring timeout with no SIP code).

## 3. Reading the dashboard

The Failure insights tab surfaces five KPIs and two tables, each scoped to
your selected lookback window (7, 14, 30, 60, or 90 days):

* **Conference failure rate** — conferences that ended in `failed` as a
  fraction of all conferences started in the window. A spike here means rooms
  are failing to form at all.
* **Participant failure rate** — dialed legs that ended in a failure-terminal
  status (`failed`, `busy`, `no_answer`, `rejected`) as a fraction of all
  legs dialed. A high rate with a low conference failure rate means rooms are
  forming but individual legs keep failing.
* **Provider-related failed legs** — the count and rate of legs whose failure
  was on the carrier/softswitch side (SIP 5xx or a provider-side structured
  code). A spike here points at your trunk or the upstream carrier; a flat
  line while the participant failure rate climbs points at your destinations.
* **Top failure reasons** — the ten most common failure codes across all
  failed legs, ranked by count. Use the per-code patterns in the table below
  to map each recurring code to an action.
* **Affected destinations** — the ten phone numbers that failed most often.
  Recurring failures on a single destination or prefix tell you the problem
  is at that far end, not in your configuration.

Filter by carrier or destination prefix from the chip row at the top of the
tab. Select a single carrier to isolate provider-routing failures against one
trunk, or type a destination prefix (`+1`, `+44`) to zoom into one country's
legs.

The same data is available through the API for automation or alerting:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/voice/conferences/failure-analytics?window_days=30" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

The response carries `total_conferences`, `failed_conferences`,
`conference_failure_rate`, `total_participant_legs`, `failed_participant_legs`,
`participant_failure_rate`, `provider_related_failed_legs`,
`provider_related_rate`, `top_failure_reasons` (top 10), and
`affected_destinations` (top 10). The `window_days` parameter accepts 1–365;
omit it for the default 30-day window.

## 4. Joining with analytics

The failure-analytics data feeds the same pipeline as the broader
/insights/analytics surface. In the dashboard, go to **Insights → Analytics**
and select the Voice → Conferences card to see the same failure rates and
attribution breakdowns in a wider reliability context — alongside call
completion rates, queue SLA metrics, and provider-health KPIs. The window
selector and filter chips work the same way in both surfaces.

For automation, poll `GET /voice/conferences/failure-analytics` on a cron
schedule and feed the `provider_related_rate` and `participant_failure_rate`
into your monitoring stack. A `provider_related_rate` that crosses a
threshold you set (e.g. > 5%) while the `participant_failure_rate` stays
flat is a carrier-side incident — page your trunk operations, not your
conference participants.

## 5. Patterns table

Six common attribution-and-code combinations and the operator action for each:

| Attribution class | Common codes | What to do |
| - | - | - |
| Orbit-side | `CONF_CALLER_ID_NOT_OWNED` | The dial-from number isn't on your account. Assign a number from your inventory as the conference caller ID. |
| Orbit-side | `CONF_INSUFFICIENT_CREDIT` | Top up your balance or raise the spend cap. Check the [insufficient balance page](/troubleshooting/insufficient-balance) for the top-up path. |
| Provider-routing | `CALL_FAILED`, `CONF_TRUNK_UNREGISTERED` | The trunk registration is sick or the upstream carrier rejected the call. Work the [SIP trunk troubleshooting page](/troubleshooting/sip-trunk) — a single leg is a route problem; every leg failing with the same code points at the trunk itself. |
| Provider-routing | `CALL_FAILED` with codec-mismatch SIP detail | The upstream provider and the destination disagreed on codec negotiation. Check your BYO-PBX SDP offer — a mismatched codec in the SDP can cause the carrier to reject the call before it reaches the far end. Retry with a different codec set. |
| Destination-network | `SIP_486` (busy), `NO_ANSWER` | The far end is genuinely busy or not answering. These are not configuration problems — remove persistently unreachable numbers from your participant lists, or schedule dials when the destination is likely to answer. |
| Destination-network | Recurring failures on one carrier region + `CALL_FAILED` | The carrier's route to that region is degraded. Switch to a different trunk for that destination prefix, or escalate to the carrier. Use the dashboard's carrier filter to confirm the pattern is isolated to one provider before changing routes. |

## 6. Worked example: from alert to routing change

A support team runs daily stand-up conferences with offshore agents across
three carriers. One Monday, the Failure insights tab shows the participant
failure rate jumping from 2% to 14%.

**Step 1 — isolate the class.** The `provider_related_rate` is 11% (up from
1%), while the `conference_failure_rate` is unchanged. The problem is on the
carrier side, not in the conference configuration or the destinations.

**Step 2 — find the carrier.** Filter by carrier in the chip row. Carrier A
and Carrier B show normal rates. Carrier C shows 28% of legs failing, almost
all with the `CALL_FAILED` code.

**Step 3 — find the destination pattern.** Switch to the Affected
destinations table. Every number in the top 10 is a `+91` (India) prefix.
Carrier C's route to India is degraded.

**Step 4 — act.** Route the India-bound conference legs through Carrier A
instead, or remove Carrier C from the trunk pool for that destination prefix
until the carrier resolves the route. Re-check the Failure insights tab
after the next stand-up: the `provider_related_rate` is back at 1%, and the
participant failure rate dropped to 3% — the remaining failures are the
normal `NO_ANSWER` and `SIP_486` legs a conference always collects.

This cycle — isolate the class, find the carrier, confirm the destination
pattern, change one route — is the intended operator workflow for the
failure-analytics surface. It turns a "14% failure rate" alert from a
number you stare at into an action you take in under five minutes.

## Related

* [Voice conferences: create, manage, and end conference bridges](/voice/conferences) — the full conference lifecycle, create/end/manage API, and lifecycle webhooks.
* [Per-queue SLA breach alerting and escalation policies](/voice/queue-sla-escalation-policies) — the parallel observability surface for queue SLA breaches.
* [Troubleshooting: conference lifecycle failures](/troubleshooting/conference-failures) — map a misbehaving room to the lifecycle step that broke, with per-code cause-and-fix tables.
* [Troubleshooting: SIP trunk](/troubleshooting/sip-trunk) — trunk registration and upstream failures behind `CONF_TRUNK_UNREGISTERED` and provider-routing failures.
* [Troubleshooting: insufficient balance](/troubleshooting/insufficient-balance) — the top-up path for `CONF_INSUFFICIENT_CREDIT`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.