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:

The monthly resolution cap. A ceiling on how many conversations the AI resolves per calendar month (counted as “resolved by AI”). 0 means unlimited.
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%.
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.

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.
Set the cap. Under Budget controls, enter the monthly AI-resolution ceiling. 0 keeps the engine uncapped.
Set the soft alert. Enter the percentage of the cap at which the warning state activates, between 0 and 100.
Set the human-agent cost. Enter the per-ticket human cost (cents) you want the savings math to use.
Decide the cap behavior. Turn Auto-pause when cap is reached on or off.
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.

Worked round-trip samples

Script the whole loop outside the console: attempt a deflection, read and set the budget, check the settled savings, and confirm the cap-trip shape. Samples run against the sandbox — use a Test key (dv_test_sk_…) as they are, and tag each call with a request id so you can correlate it in your API request logs. The conventions below match the worked-sample guide.

1. Attempt a deflection

The widget and the inbox UI both call the same route — a programmatic check uses it verbatim. The body can carry the KB to scope the match against; an empty body searches every active KB.

curl -X POST https://api.orbit.devotel.io/api/v1/inbox/tickets/conv_4f0b21/deflect \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req_sample_deflect_001" \
  -d '{ "knowledgeBaseId": "kb_9a2c" }'

When confidence clears the threshold, the response carries the suggested answer plus its citation, and the answer posts into the thread as the first reply:

{
  "data": {
    "shouldDeflect": true,
    "confidence": 0.91,
    "threshold": 0.75,
    "reasoning": "Top KB chunk matches the refund-policy question.",
    "answerText": "Refunds process back to the original payment method within 5 business days.",
    "citation": {
      "knowledgeBaseId": "kb_9a2c",
      "documentId": "doc_77abd0",
      "chunkIndex": 4
    }
  },
  "requestId": "req_sample_deflect_001"
}

When nothing clears the threshold — or the conversation has no customer message — the route returns a clean no-answer envelope instead of an error, and nothing counts toward the cap:

{
  "data": {
    "shouldDeflect": false,
    "confidence": 0.30,
    "threshold": 0.75,
    "reasoning": "Best KB candidate fell below the confidence threshold."
  },
  "requestId": "req_sample_deflect_001"
}

2. Read and set the budget

GET returns the persisted config, the live month-to-date usage, and the savings math in one payload:

curl -X GET https://api.orbit.devotel.io/api/v1/inbox/ai-deflection/budget \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "X-Request-Id: req_sample_budget_001"

{
  "data": {
    "config": {
      "monthly_resolution_cap": 500,
      "soft_alert_threshold_pct": 80,
      "hard_pause_on_cap": true,
      "human_agent_cost_cents": 750
    },
    "usage": {
      "period_start": "2026-09-01",
      "monthly_resolutions": 421,
      "projected_monthly_resolutions": 505,
      "projected_to_exceed_cap": true,
      "cap_reached": false,
      "soft_alert_active": true
    },
    "cost_savings": {
      "human_cost_cents": 315750,
      "ai_cost_cents": 842,
      "savings_cents": 314908
    }
  },
  "requestId": "req_sample_budget_001"
}

PUT updates any subset of the four settings — only owners and admins. Send only what changes; the rest persist.

curl -X PUT https://api.orbit.devotel.io/api/v1/inbox/ai-deflection/budget \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: req_sample_budget_set_001" \
  -d '{ "monthly_resolution_cap": 600, "soft_alert_threshold_pct": 85, "hard_pause_on_cap": true, "human_agent_cost_cents": 750 }'

The response echoes the full updated config-plus-usage payload — the same shape as GET. A non-owner/admin PUT returns a 403 with INSUFFICIENT_PERMISSIONS.

3. Read the settled savings

The month-to-date panel above uses a flat per-resolution estimate. For the number you put in a cost review, call the savings endpoint — it settles real per-token LLM spend over a window (7d, 30d, 90d, or 365d):

curl -X GET "https://api.orbit.devotel.io/api/v1/inbox/deflection/savings?window=30d" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY" \
  -H "X-Request-Id: req_sample_savings_001"

{
  "data": {
    "window": { "from": "2026-08-18", "to": "2026-09-17", "days": 30 },
    "resolved_deflections": 421,
    "llm_spend_cents": 1290,
    "gross_human_cost_avoided_cents": 315750,
    "net_savings_cents": 314460,
    "roi_ratio": 244.77
  },
  "requestId": "req_sample_savings_001"
}

net_savings_cents is the gross human cost minus the actual LLM spend — the same human-cost figure, minus the real bill rather than the flat estimate.

4. When the cap trips

With hard pause on and the month’s count at or past the cap, a deflection attempt short-circuits before any AI work and returns a clean no-answer with the reason — the widget renders it without an error:

{
  "data": {
    "shouldDeflect": false,
    "confidence": 0,
    "threshold": 0.75,
    "reasoning": "AI deflection paused: monthly resolution cap reached for this tenant."
  },
  "requestId": "req_sample_deflect_002"
}

The conversation is left for the human queue, and the counter resets to zero on the next calendar month roll-over — the pause lifts automatically.

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

WhatsApp

Developer console

Contact center

Guides

Messaging Controls

Audience & Support Tools

AI deflection budget — cap, soft alert, and savings

AI deflection budget — cap, soft alert, and savings

Everyday cost control

Walkthrough

How the cap interacts with ticket counts

What happens when the cap trips

Reading the savings panel

API parity

Worked round-trip samples

1. Attempt a deflection

2. Read and set the budget

3. Read the settled savings

4. When the cap trips

Troubleshooting

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

​Everyday cost control

​Walkthrough

​How the cap interacts with ticket counts

​What happens when the cap trips

​Reading the savings panel

​API parity

​Worked round-trip samples

​1. Attempt a deflection

​2. Read and set the budget

​3. Read the settled savings

​4. When the cap trips

​Troubleshooting

AI deflection budget — cap, soft alert, and savings

Everyday cost control

Walkthrough

How the cap interacts with ticket counts

What happens when the cap trips

Reading the savings panel

API parity

Worked round-trip samples

1. Attempt a deflection

2. Read and set the budget

3. Read the settled savings

4. When the cap trips

Troubleshooting