How to Set Your AI Cap Behavior — Pause, Downgrade, Throttle

When you hit a daily or monthly AI credit cap, Botline doesn't just keep silently overspending. The AI pauses, your customers see a friendly fallback message (or nothing for media), and you see exactly which conversations were affected — all without any error from the customer's perspective.

This is Phase 2 of the AI Credits feature. Phase 1 (already shipped) gave you visibility into spend; Phase 2 makes the caps actually do something when they're reached.

The behavior differs by category, because different categories have different UX needs:

• Text AI cap-hit — AI sends one tenant-configurable canned fallback message to the customer, e.g. “Thanks! 👋 We're a quick break — back tomorrow!”. Sent only ONCE per conversation per cap-period — your customer doesn't get the same message 20 times.
• Vision/Audio/Documents cap-hit — silently skipped. The customer gets no special message; the AI just doesn't process their image/voice-note. Other categories on the same message keep working — text replies still send if text isn't capped.

You see a clean amber row in your conversation feed with the attempt count, so you know exactly what happened.

The text-AI fallback is tenant-configurable. Edit it from Settings → AI Configuration → Cap behavior. The textarea accepts a special token:

• {{TIMEFRAME}} — auto-fills as “tomorrow” when the daily cap hits, or “next week” when the monthly cap hits.

If you leave it blank, Botline uses a localized built-in default in seven languages (English, Urdu, Bahasa Malaysia, Arabic, Bengali, Bahasa Indonesia, Mandarin). The language is picked from your tenant's primary language setting.

If you're on the Pro or Enterprise plan, you can enable a feature that's very useful for high-volume tenants: instead of pausing when 80% of your daily Text AI cap is reached, the AI automatically swaps from Sonnet 4.6 (your premium model) to Claude Haiku (a cheaper, faster, slightly-less-capable model) for the rest of the day.

This means your customers keep getting answers — they just might be a bit shorter or less nuanced. The AI auto-resumes the premium model at midnight when your daily counter resets.

Toggle this on at Settings → AI Configuration → Cap behavior → Auto-downgrade to Haiku.

Even with auto-downgrade, a runaway customer (or a bot loop) can still rack up Haiku costs. The adaptive throttle is your second line of defense:

• Off — always reply fast (3-second batching). No throttle ever.
• Smart — throttle to 60-second batching only when budget is at risk or a loop is suspected. Recommended for most tenants.
• Strict — always 60-second batching, even on normal traffic. Use only for very high-volume tenants where every reply needs cost protection.

When throttle kicks in, multiple customer messages in the same minute get batched into a single AI reply — at most 1 reply per conversation per minute.

When a cap-hit affects a conversation, you'll see a single amber inline row in the conversation feed:

⚠ AI reply paused — daily AI replies credit exhausted (3 attempts). Followed by either “Top up →” (paid plans) or “Upgrade to Starter →” (free plan).

The attempt count rolls up throughout the day, so you don't see 20 amber rows for one chatty customer — just one row that updates as more messages come in. The next day, if the cap is still hit, a fresh amber row appears for that new day.

The cap-hit experience differs by plan tier:

• Free plan — when capped, the dashboard shows an “Upgrade to Starter” CTA in place of the top-up link. The auto-downgrade and the throttle modes are still available, but the upgrade path is the primary signal.
• Starter / Pro / Enterprise — when capped, the “Request top-up” flow is shown. Admin gets emailed and decides. Pro+ also gets the auto-downgrade toggle to keep AI running on Haiku instead of pausing.

You set both a daily cap and a monthly cap (independently per category). When checking, Botline gates on whichever cap is hit first. The message you see differs:

• Daily cap hit — softer message: AI auto-resumes at midnight in your timezone. No top-up CTA on the dashboard panel since it auto-restores in hours.
• Monthly cap hit — harder message: AI is paused until the first of next month, with prominent “Top up →” CTA.

If you exceed both at the exact same moment (rare), monthly wins as the message because it's the more “real” cap.

That's everything. Open Settings → AI Configuration → Cap behavior to configure all three switches.