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

# AI deflection budget — cap, soft alert, and savings

> Cap how many tickets the AI deflection engine resolves each month, warn your team with a soft alert before the cap trips, and read the cost-savings panel that compares AI resolutions against human-agent cost. Fully per-tenant, tenant-configured.

# AI deflection budget — cap, soft alert, and savings

AI ticket deflection resolves customer questions from your knowledge bases before a ticket enters the human queue, and every self-serve resolution has a per-resolution cost. **Inbox → Settings → AI deflection** (owner or admin) is where you keep that spend predictable: a monthly resolution cap, a soft alert that warns before the cap trips, and a savings panel that compares AI resolution cost against what a human agent would have cost.

Every control on the page is tenant-owned — nothing applies until you set it. With no cap configured (`0` = unlimited), the page is a read-only savings report.

## Everyday cost control

Three numbers working together keep AI resolution spend predictable:

1. **The monthly resolution cap.** A ceiling on how many conversations the AI resolves per calendar month (counted as "resolved by AI"). `0` means unlimited.
2. **The soft alert.** A percentage of the cap — when monthly usage crosses it, the page's warning banner flips to a low-warning state so you see the limit approaching before it becomes a hard stop. Default 80%.
3. **The hard-pause switch.** What happens at the cap: enabled, the deflection engine stops proposing answers and new questions go straight to the human queue; disabled, the engine keeps resolving with the banner showing the cap is reached.

The savings panel does the math on each resolution: human-agent cost per ticket (you set a per-ticket figure in cents; \$7.50 default) minus the AI per-resolution charge.

## Walkthrough

Open **Inbox → Settings → AI deflection**. This console is split across the settings page, and only owners and admins can save changes.

1. **Usage header.** Three cards describe the current calendar month: AI resolutions so far against the cap, the projected month-end count (a straight-line extrapolation — noisy in the first days of a month), and net savings.
2. **Set the cap.** Under **Budget controls**, enter the monthly AI-resolution ceiling. `0` keeps the engine uncapped.
3. **Set the soft alert.** Enter the percentage of the cap at which the warning state activates, between 0 and 100.
4. **Set the human-agent cost.** Enter the per-ticket human cost (cents) you want the savings math to use.
5. **Decide the cap behavior.** Turn **Auto-pause when cap is reached** on or off.
6. **Save.** Changes take effect immediately — the next deflection attempt reads the new config.

The page carries two other sections beside the budget console. **Deflection savings / ROI** is a read-only report over a chosen window; it settles real per-token LLM spend instead of the flat per-resolution estimate, so use it as the authoritative figure. **Deflection controls** (on the same page) is where the engine itself is tuned: enable/disable, the confidence threshold, and the fallback message a customer sees when the AI declines to answer. Set the ceiling here; tune the engine there.

## How the cap interacts with ticket counts

A resolution is a conversation flagged **resolved by AI**: the deflection engine matched the customer's first inbound message to a knowledge-base answer, and either the customer explicitly confirmed the answer helped or an auto-deflect flow closed it. Each confirmed resolution stamps the conversation's metadata, and the budget endpoint counts those stamps month to date.

Deflection signals arrive on the ticket-deflection routes your widget and inbox UI call — principally `POST /inbox/tickets/:id/deflect` (KB match plus suggested answer) and its confirmation siblings (customer accepts or rejects the suggestion). Three boundaries decide what counts:

* **Cap trip.** The current month's total crosses the cap. With hard pause on, every new deflection attempt hands the conversation to the human queue before any AI work runs.
* **No first inbound message.** A conversation with no customer message is never eligible — it returns a no-deflect response and does not move the counter.
* **Declined matches.** When the confidence check fails, the deflection suggests nothing and nothing counts toward the cap, even though the engine spent on the attempt.

## What happens when the cap trips

With **Auto-pause when cap is reached** off, nothing blocks: the banner simply reads that the cap is reached, and deflection continues under your scrutiny.

With **Auto-pause when cap is reached** on:

* New deflection attempts return a `shouldDeflect: false` response with a reason field explaining the pause — the widget and inbox UI see a clean no-answer instead of an error.
* The conversation is left for a human: no AI answer posts, and agents see the thread in the normal queue.
* On the next calendar month roll-over the counter resets to zero and the pause lifts automatically.

The check fails open: if the budget pre-check hits a transient database error at attempt time, the engine proceeds with the deflection rather than denying every tenant's deflections for one blip.

## Reading the savings panel

The header savings card shows three figures:

* **Human cost** — resolutions so far multiplied by the human cost you set.
* **AI cost** — resolutions multiplied by the flat per-resolution AI charge.
* **Net savings** — the difference. Savings go negative if your configured human cost per ticket is below the AI per-resolution charge — the panel shows the signed figure rather than clamping.

Two caveats:

* **The flat estimate is an approximation.** Use the ROI section (same page) for the settled figure: it bills per-token spend over a chosen window and reports a gross-vs-net split.
* **Uncapped months.** A month with no cap still shows savings — the percentage line switches to "no cap configured" instead of a share of the ceiling.

## API parity

The dashboard reads and writes two endpoints — you can automate the same configuration:

| Endpoint                                 | Purpose                                                                      |
| ---------------------------------------- | ---------------------------------------------------------------------------- |
| `GET /api/v1/inbox/ai-deflection/budget` | Current config, month-to-date usage, and savings math                        |
| `PUT /api/v1/inbox/ai-deflection/budget` | Update any subset of cap, soft-alert %, hard-pause, human cost (owner/admin) |
| `GET /api/v1/inbox/deflection/savings`   | Settled savings over a window — real LLM spend, gross and net                |

`PUT` sends only the fields you want to change; the others persist. Full request/response schemas live in the [Inbox API reference](/api-reference/endpoints/inbox).

## Troubleshooting

| Symptom                             | Cause                                                                                                                      | Fix                                                                                                                                                                                                                                                                                                       |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **The soft alert never fires**      | The threshold was never set, or it is `0` — the alert only exists once a threshold exists and a cap exists.                | Set both the cap and a percentage between 1 and 100.                                                                                                                                                                                                                                                      |
| **The cap trips every month**       | Eligible first messages count toward the ceiling on every inbound channel; the cap is a fixed ceiling, not a rate limiter. | Review where the volume is human-served before raising the cap — [Routing rules](/inbox/routing-rules) and [Inbox setup](/guides/inbox-setup) pull some volume off the deflection path by design. If deflected-first-message volume is the bulk of eligible intake, raise the cap or live with the pause. |
| **Resolutions happen past the cap** | Hard pause is off (or a transient read failed open at attempt time).                                                       | Turn on **Auto-pause when cap is reached** if the ceiling should be a hard stop.                                                                                                                                                                                                                          |
| **Net savings reads negative**      | The human-cost figure you set is below the AI per-resolution charge.                                                       | Re-set the human-agent cost to your real blended per-ticket cost, or read the ROI section for settled figures.                                                                                                                                                                                            |

***

Related: [Inbox tickets workflow](/guides/inbox-tickets-workflow) · [Inbox setup](/guides/inbox-setup) · [Routing rules](/inbox/routing-rules) · [Inbox settings map](/inbox/settings-map)