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

# Inbox AI co-pilot: org kill switch, auto-approve confidence bar, send-only gate

> Tune how the Inbox AI co-pilot behaves per workspace — turn AI-drafted replies off entirely, set the confidence bar a draft must meet to qualify for one-click approve-and-send, and understand why escalate/end suggestions are never auto-approvable.

# Inbox AI co-pilot settings

When the AI co-pilot is enabled, Devotel Orbit drafts a suggested reply whenever a new inbound customer message lands in an open conversation. The draft appears as a card above the composer with Accept, Edit, and Discard buttons — your operator stays in control of every reply: nothing ships to the customer until a person approves or edits the draft and sends it.

Every draft also carries a confidence score from 0 to 1, and each workspace sets the confidence bar a draft must clear to qualify for one-click approve-and-send. Drafts below the bar are still shown — they simply require an explicit review rather than a one-click acceptance.

## Which settings exist

The per-workspace co-pilot config has two fields:

| Field                               | Type        | Default | What it controls                                                                                                                                                                                                                                                         |
| ----------------------------------- | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`                           | boolean     | `true`  | Org-level kill switch. Set to `false` to stop the co-pilot from drafting across the whole workspace — the AI suggest surface returns its empty state instantly and no model calls are made.                                                                              |
| `auto_approve_confidence_threshold` | number, 0–1 | `0.9`   | The minimum self-reported confidence a draft needs to qualify for one-click approve-and-send. Lower it toward `0` when you trust your knowledge base and want most send-shaped drafts to qualify; raise it toward `1` when every reply should get explicit human review. |

Both fields are workspace-wide owner/admin settings. Operators read the effective values; only owners and admins can change them, and every change is written to the audit log and takes effect immediately.

## Read the current settings

Read the effective config with `GET /inbox/copilot/config`:

```bash theme={null}
curl -X GET https://api.orbit.devotel.io/api/v1/inbox/copilot/config \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

The response is the normalized, effective config — the exact values the drafting path uses:

```json theme={null}
{
  "data": {
    "enabled": true,
    "auto_approve_confidence_threshold": 0.9
  }
}
```

## Change the settings

Change the config with `PATCH /inbox/copilot/config`. Send a partial update with only the fields you want to change:

```bash theme={null}
curl -X PATCH https://api.orbit.devotel.io/api/v1/inbox/copilot/config \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_approve_confidence_threshold": 0.75
  }'
```

Both fields are optional on each request, and the threshold must sit between 0 and 1 inclusive — anything else returns `422 VALIDATION_ERROR`. Non-owner/admin callers get `403 INSUFFICIENT_PERMISSIONS`. The response is the effective config after the update, so follow with a GET or read the response body to confirm the new values. Changes are applied to live drafts immediately.

## How the threshold applies to each draft

Each draft response includes two routing fields, derived from your config:

* `require_human_review` — always `true`. A person reviews every draft before anything is sent; confidence is displayed as guidance, never as permission to skip review.
* `auto_approve_eligible` — `true` only when all three hold: the co-pilot is enabled, the draft's confidence meets your threshold, and the suggested action is `send`. This is the signal composer automations can use to offer one-click approve-and-send.

Only send-shaped suggestions can ever qualify. When the model suggests `escalate` or `end` — closing or handing off the conversation — the draft is never eligible, at any confidence level, because those actions change the conversation's trajectory rather than just replying to it. Confidence values above 1 or below 0 are clamped to the 0–1 range before comparison, and a workspace whose threshold is 0 effectively qualifies every send-shaped draft. A threshold of 1 requires a perfect score.

## Common failures

* **`403 INSUFFICIENT_PERMISSIONS` on PATCH** — the API key or session belongs to a non-admin operator. Use an owner or admin identity.
* **`422 VALIDATION_ERROR` on PATCH** — the threshold is outside 0–1, or the body includes a field that does not exist. Send only `enabled` and `auto_approve_confidence_threshold`.
* **The AI suggest card is empty for every conversation** — check `enabled` on the config; the kill switch returns a gentle empty state rather than an error.