> ## 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.

# Voice Settings Consoles

> The eight org-level voice settings — dialing-class restrictions, skill-proficiency decay, max call duration, ACD auto-answer, shared speed dial, affinity routing, attribute routing, and the SIP registration cap — with their GET/PUT admin endpoints and the exact settings key each one writes.

# Voice Settings Consoles

Voice runs on a set of organization-level policy knobs that decide how calls are placed, answered, routed, and capped. Eight of these policies ship as paired GET/PUT endpoints under `/api/v1/voice/*`, so you can inspect and change them from the dashboard or from your own tooling with an API key.

This guide covers each setting: what it changes, which endpoints read and write it, the organization settings key it persists, and where it appears in **Settings → Voice** in the dashboard.

## Access controls

The same two rules guard every endpoint on this page:

* **Admin only.** Read and write both require an owner/admin role (or an API key scoped for voice administration). Members without the admin role cannot read or change these policies.
* **Rate limited.** Reads run under the standard voice read limit; writes run under a tighter voice write limit, so a misbehaving integration cannot thrash the policy.

Every write replaces the whole policy object for that setting and is recorded in the audit log (**Settings → Audit log**), so changes are attributable and reviewable. GET responses and PUT bodies use the same shape — what you read is exactly what you PUT back.

## Dialing-class restrictions

Control which call classes each user or extension may place: toll-free, domestic, international, or premium. Set a default for the organization and tighten specific users where needed — for example, block international dialing for everyone except the collections team.

* **Read:** `GET /api/v1/voice/dialing-restrictions`
* **Write:** `PUT /api/v1/voice/dialing-restrictions`
* **Settings key:** `settings.voice.user_dialing_restrictions`
* **Dashboard:** Settings → Voice (API-only today — no console section yet; manage through the endpoints).

```json theme={null}
{
  "enabled": true,
  "home_country": "US",
  "default_allowed_classes": ["tollfree", "domestic"],
  "users": {
    "user_2svc": { "allowed_classes": ["tollfree", "domestic", "international"] }
  },
  "premium_prefixes": ["+1900"]
}
```

`users` overrides the default per user ID; `premium_prefixes` lets you list E.164 prefixes that always count as premium. Enforcement happens when an outbound call is initiated — a denied class returns an error before any ring-out.

## Skill-proficiency decay

Agents' skill ratings fade automatically when a skill goes unused, so routing weights recent handling history instead of an agent's stale, all-time score. A scheduled sweep applies the decay bands you define.

* **Read:** `GET /api/v1/voice/skill-proficiency-decay`
* **Write:** `PUT /api/v1/voice/skill-proficiency-decay`
* **Settings key:** `settings.acd_skill_proficiency_decay`
* **Dashboard:** Settings → Voice (API-only — manage through the endpoints).

```json theme={null}
{
  "enabled": true,
  "bands": [
    { "remainingFractionAtMost": 0.5, "cap": 4 },
    { "remainingFractionAtMost": 0.25, "cap": 3 },
    { "remainingFractionAtMost": 0.1, "cap": 2 }
  ],
  "exemptSkills": ["compliance", "escalations"]
}
```

Each band caps the proficiency level (1–5) once the agent's remaining evaluation window drops to that fraction. List regulated or rarely-used skills in `exemptSkills` so the sweep never decays them. The policy supports up to 10 bands and 200 exempted skills.

## Max call duration

Set a hard ceiling on live ACD call length. Queues govern waiting, wrap-up, and idle time; this setting governs the call itself. Use it when you bill per minute, run collections scripts with a fixed cadence, or want a backstop against runaway calls.

* **Read:** `GET /api/v1/voice/max-call-duration`
* **Write:** `PUT /api/v1/voice/max-call-duration`
* **Settings key:** `settings.acd_max_call_duration`
* **Dashboard:** Settings → Voice (API-only — manage through the endpoints).

```json theme={null}
{ "enabled": true, "maxSeconds": 1800 }
```

`maxSeconds` accepts 60 to 14,400 (one minute to four hours). When enabled, the inbound call leg auto-disconnects at the limit. The default is disabled with the platform ceiling of four hours — the legacy behaviour for every existing tenant.

## ACD auto-answer

Deliver ACD calls straight to the agent's endpoint without it ringing — the desk phone answers the call leg automatically, optionally preceded by a short zip tone so the agent knows a call was dropped onto the line. Standard headset-operations behaviour in a contact center.

* **Read:** `GET /api/v1/voice/acd-auto-answer`
* **Write:** `PUT /api/v1/voice/acd-auto-answer`
* **Settings key:** `settings.acd_auto_answer`
* **Dashboard:** Settings → Voice (API-only — manage through the endpoints).

```json theme={null}
{ "enabled": true, "zipToneEnabled": true }
```

The zip tone only applies when auto-answer itself is enabled. Default disabled preserves ring-until-answered behaviour; enable it per organization when your agents run dedicated headsets.

## Shared speed dial

Publish an organization-curated speed-dial and busy-lamp-field (BLF) list — front desk, sales hotline, on-call — to every desk phone, ahead of the automatic teammate roster. Entry values are validated as internal extensions only; external numbers are rejected, so one-touch dialing always stays on-net.

* **Read:** `GET /api/v1/voice/shared-speed-dial`
* **Write:** `PUT /api/v1/voice/shared-speed-dial`
* **Settings key:** `settings.voice_shared_speed_dial`
* **Dashboard:** Settings → Voice (API-only — manage through the endpoints).

```json theme={null}
{
  "entries": [
    { "type": "blf", "label": "Front desk", "value": "1000" },
    { "type": "speed_dial", "label": "On-call", "value": "2001" }
  ]
}
```

`type` is `blf` (monitored lamp field) or `speed_dial` (one-touch dial). Desk phones pick up the list through their provisioning fetch; a preview of the resolved key layout appears on the device detail page.

## Affinity routing

Route each inbound contact to the best-matched agent rather than the globally best-scoring one. Affinity tags on agent profiles (segment, language style, topic fit) are weighed against the resolved caller's attributes — a behavioral-affinity pairing objective, opt-in per organization.

* **Read:** `GET /api/v1/voice/affinity-routing`
* **Write:** `PUT /api/v1/voice/affinity-routing`
* **Settings key:** `settings.acd_affinity_routing`
* **Dashboard:** Settings → Voice (API-only — manage through the endpoints).

```json theme={null}
{
  "enabled": true,
  "treatment_percent": 100,
  "affinity_weight": 0.75,
  "headroom_weight": 0.25,
  "agent_profiles": {
    "user_9k3v2": ["segment:enterprise", "style:analytical"]
  }
}
```

`treatment_percent` (0–100) is the share of calls scored on the affinity arm; the weights balance contact-to-agent fit against load headroom. `agent_profiles` maps a user ID to up to a bounded set of affinity tags. Default off — matching stays purely score-based until you enable it.

## Attribute routing

Match the resolved caller's contact tags and attributes against an ordered rule list before the call enters a queue, adding skills and a priority boost on the first matching rule. Use it for VIP routing, language detection, or tier-based escalation.

* **Read:** `GET /api/v1/voice/attribute-routing`
* **Write:** `PUT /api/v1/voice/attribute-routing`
* **Settings key:** `settings.acd_attribute_routing`
* **Dashboard:** Settings → Voice — this one has a full console section (edit the rule list inline, no API calls needed).

```json theme={null}
{
  "enabled": true,
  "rules": [
    {
      "kind": "tag",
      "value": "vip",
      "skills": ["priority"],
      "priorityBoost": 10,
      "label": "VIP tag"
    },
    {
      "kind": "attribute_gte",
      "key": "lifetime_value",
      "threshold": 10000,
      "skills": ["premium-support"],
      "label": "High-value customer"
    }
  ]
}
```

Rule kinds are `tag` (matches a contact tag value), `attribute_equals` (string field equals a value), and `attribute_gte` (numeric field at or above a threshold). Each rule can add skills and an optional integer `priorityBoost` (0–99). Up to 50 rules; only the first match applies.

## SIP max registrations per extension

Cap how many distinct SIP endpoints may hold a live registration for one extension. Without a cap, nothing prevents a registration flood on a shared credential or an unbounded number of hot-desking devices binding the same extension.

* **Read:** `GET /api/v1/voice/sip-max-registrations`
* **Write:** `PUT /api/v1/voice/sip-max-registrations`
* **Settings key:** `settings.sip_max_registrations_per_extension`
* **Dashboard:** Settings → Voice (API-only — manage through the endpoints).

```json theme={null}
{ "enabled": true, "maxRegistrations": 3 }
```

`maxRegistrations` accepts 1 to 50. The registration itself is checked at login: a device binding past the cap is rejected until another endpoint unregisters. Disabled (the default) restores unlimited registrations — the legacy behaviour.

## Troubleshooting

* **403 on GET or PUT** — your role or API key lacks voice admin access. Have an owner grant it.
* **422 / 400 on PUT** — the body failed validation; the error lists each invalid field. Fetch the current policy with GET, correct it, and re-submit.
* **429** — you hit the read or write rate limit. Back off and retry; the limits reset on a short window.
* **A setting behaves like it is off after a PUT** — `enabled: false` (or a malformed earlier blob) resolves to the safe default. Confirm the saved object with a GET.