> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/inbox-credit-quota.md).

# Conversation Platform Credit Quota Management

Set a Credits spending limit for each inbox to control AI usage costs across channels such as your website and LINE

In addition to [member quotas](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md), administrators can set a Credits spending limit and validity period for **each inbox**. For example, you can assign separate quotas when your website Web Chat has a fixed monthly campaign budget or your LINE inbox needs its own cost controls.

{% hint style="info" %}
**Available only to organizations using Credits billing.** Like member quotas, inbox quotas are **spending caps, not separate wallets**. Charges still come from the organization wallet; the quota only limits how much an inbox can spend.

Member, role, and inbox quotas **operate independently and apply simultaneously**. If any applicable quota is exhausted, the next AI request is blocked. The last permitted transaction may still exceed the cap; see the Fail-Open explanation below. For the purpose of each layer, see [How the Three Quota Layers Work Together](#quota-layers).
{% endhint %}

## How the Three Quota Layers Work Together <a href="#quota-layers" id="quota-layers"></a>

Credits quotas have three layers, corresponding to the three subtabs under Quota Allocation. These layers are easy to confuse because **each controls a different scope**. Use them separately or together as needed:

| Layer            | Scope                                                              | Who is blocked when the quota is exhausted | Subtab        |
| ---------------- | ------------------------------------------------------------------ | ------------------------------------------ | ------------- |
| **Member quota** | Individual members (admin console operations, API Key calls, etc.) | The individual member                      | Member Quotas |
| **Role quota**   | All members assigned to a MaiAgent role                            | Members with that role                     | Role Quotas   |
| **Inbox quota**  | Visitor conversations in a single inbox (Web Chat, LINE, etc.)     | All visitor conversations in that inbox    | Inbox Quotas  |

The three layers apply as follows:

* **Any exhausted layer blocks the request**: Each transaction checks all applicable quotas along with the organization wallet balance. If any layer has no remaining quota at the time of the check, the AI request is blocked
* **Charges are deducted only once**: Quotas measure spending limits; they are not separate wallets. Regardless of how many quota layers apply, Credits are **deducted from the organization wallet only once**, with no duplicate charges
* **Member quotas do not apply to inbox visitors**: Visitors on external channels such as LINE are not organization members. Their conversations check only the organization wallet and the inbox quota

For instructions on role and member quotas, see [Member Credits Quota Management](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md). For how a single transaction counts toward multiple layers and what the displayed numbers mean, see [How the Three Quotas Are Calculated: Scenarios and FAQ](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/credit-quota-scenarios.md).

## Use Cases <a href="#use-cases" id="use-cases"></a>

* **Finance and banking—separate budgets for each inbox**: The website Web Chat answers public questions about credit cards and loans, while the official LINE account focuses on wealth management customers. The two channels have marketing budgets owned by different departments. Set a separate quarterly cap for each inbox to see each channel's spending clearly and prevent overruns in one from affecting the other.
* **Services, retail, and hotels—website limits during campaigns**: Embed a dedicated Web Chat on a campaign page to answer questions about anniversary sale offers and reservations. When assigning the quota, set its effective time to the campaign start and its expiration to the campaign end, and add the campaign name in the notes. The quota expires automatically when the campaign ends, without manual deactivation.
* **Educational institutions—admissions inbox and departmental budgets**: Set up a LINE inbox for application inquiries during admissions season and assign a quarterly quota to control external inquiry costs. For internal use, combine this with [role quotas](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md#role-quota) to allocate budgets by each department's MaiAgent role, controlling inbox and departmental spending separately.
* **Technology and electronics manufacturing—separate external support from internal use**: Set a monthly quota for the external technical support Web Chat to prevent large volumes of specification and pricing inquiries from driving up costs. Control internal engineers' usage with member quotas, keeping the two scopes separate.

## Administrator Operations <a href="#admin-operations" id="admin-operations"></a>

### Open the Inbox Quotas Page <a href="#enter-inbox-quota-tab" id="enter-inbox-quota-tab"></a>

1. In the left menu, click <mark style="color:blue;">**Organization Settings**</mark> → <mark style="color:blue;">**Credits**</mark>
2. Switch to the <mark style="color:blue;">**Quota Allocation**</mark> tab. Three subtabs appear at the top: <mark style="color:blue;">**Member Quotas**</mark>, <mark style="color:blue;">**Role Quotas**</mark>, and <mark style="color:blue;">**Inbox Quotas**</mark>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b5776797d962c17a76fd1d2ff896a5e3f4367973%2Fquota-01-credits-quota-entry.png?alt=media" alt="Entry to the Credits Quota Allocation tab"><figcaption><p>Organization Settings → Credits → Quota Allocation: three subtabs (Member Quotas / Role Quotas / Inbox Quotas)</p></figcaption></figure>

3. Select the <mark style="color:blue;">**Inbox Quotas**</mark> subtab

The page displays summary cards (All Inboxes, Allocated Quotas, Expired / Disabled, and Unallocated) and a quota list for each inbox. Search by inbox name, ID, or Agent name. Quotas disabled before their scheduled expiration show <mark style="color:blue;">**Disabled**</mark>; those that became invalid upon expiration show <mark style="color:blue;">**Expired**</mark>. The <mark style="color:blue;">**Expired / Disabled**</mark> card counts both. The Role Quotas subtab uses the same display rules.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-8eb99994b153f9fa752ad96a48e0ff7d8a7da740%2Fcredit-quota-inbox-tab.png?alt=media" alt="Inbox Quotas subtab: summary cards include Expired / Disabled; clicking the card filters the list to one inbox with a Disabled quota"><figcaption><p>Quota Allocation → Inbox Quotas: summary cards, search, and the Assign Quota button; click Expired / Disabled to filter for disabled inboxes</p></figcaption></figure>

### Assign a Quota <a href="#assign-inbox-quota" id="assign-inbox-quota"></a>

1. Click <mark style="color:blue;">**Assign Quota**</mark> and select an inbox in the Assign Inbox Quota dialog
2. Enter the **quota limit**, **effective time**, and **expiration time** (leave blank for no expiration), select a **reset period**, and optionally add notes (for example, a campaign quota)
3. Confirm and submit

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-1b697c398ff794f23c020bfa77b9511092343aed%2Fquota-02-inbox-assign-modal.png?alt=media" alt="Assign Inbox Quota dialog"><figcaption><p>Assign Inbox Quota: select an inbox, then enter the quota limit, effective time, and expiration time</p></figcaption></figure>

{% hint style="info" %}
Each inbox can have only one active quota at a time. If an inbox already has an active quota, use Edit to adjust it. Increases take effect immediately; decreases cannot bring the limit below the amount already spent.
{% endhint %}

For Reset Period, choose Never, Daily, Weekly, or Monthly. At the start of the next period, the system resets usage to zero and restores the full quota at 00:00 Taipei time. The quota limit and expiration time remain unchanged. For details, see [Set the Reset Period](https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/member-credit-quota.md#quota-reset-period).

### Require Quota Toggle <a href="#inbox-quota-required" id="inbox-quota-required"></a>

Each inbox row has a <mark style="color:blue;">**Require Quota**</mark> toggle:

| Toggle State | Description                                                                                                                                                 |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **On**       | This inbox must have an active quota to use AI replies. If no active quota exists, AI replies are paused                                                    |
| **Off**      | Removes the inbox quota restriction and disables any existing active quota. Spending remains subject to the organization wallet and other applicable limits |

When you change the toggle, a confirmation dialog (Require Quota / Remove Quota Restriction) explains the impact. The change takes effect only after confirmation.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-61de335a8c31548af20bfb7468aaa1a815b23ae3%2Fquota-03-inbox-require-confirm.png?alt=media" alt="Require Quota confirmation dialog"><figcaption><p>Confirmation dialog when changing the Require Quota toggle</p></figcaption></figure>

{% hint style="warning" %}
When disabling a quota, if Require Quota remains on, AI replies for this inbox pause until a new quota is assigned or the restriction is removed.
{% endhint %}

### Organization-wide Usage Cap for MaiGPT <a href="#maigpt-org-quota" id="maigpt-org-quota"></a>

A **MaiGPT** row appears at the top of the inbox quota list. Its <mark style="color:blue;">**Channel**</mark> column displays a <mark style="color:blue;">**MaiGPT**</mark> label (or the deployment's assistant name for custom-branded deployments), rather than the usual inbox channel labels such as Web, Internal, or API. This quota is not for visitors to a single inbox; it is a **shared cap on MaiGPT usage by all organization members**.

> **Use case**: An IT department manager wants a monthly cap on company-wide MaiGPT usage to avoid discovering Credits overruns at the end of the month. The manager opens <mark style="color:blue;">**Inbox Quotas**</mark> and clicks <mark style="color:blue;">**Assign Quota**</mark> on the top row labeled MaiGPT. The dialog explains that all organization members share this quota. The manager enters a quota limit, sets the reset period to Monthly, and saves. All employees' MaiGPT usage then counts toward this quota, which resets to zero each month.

After saving, the MaiGPT row's <mark style="color:blue;">**Require Quota**</mark> toggle turns on, and the quota status shows <mark style="color:blue;">**Active**</mark>. The usage column shows the amount used and remaining quota, while the next reset column shows the next reset time and period.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e56fea2c9ecde87641e88a6bf32e6374fc5aeb17%2Fcredit-quota-inbox-maigpt-row.png?alt=media" alt="Inbox quota list: the top MaiGPT row shows a MaiGPT channel label and an Active quota with a monthly reset; other inboxes show channel labels such as Voice, API, and Internal"><figcaption><p>The MaiGPT row shows a MaiGPT channel label, and its status becomes Active after a quota is assigned</p></figcaption></figure>

Assigning, disabling, and removing restrictions work the same way as for regular inboxes. The difference is the explanatory text displayed:

| Operation                                                                                                                                     | On-screen Explanation                                                                                                                                                                                                                                    |
| --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Assign a quota (click <mark style="color:blue;">**Assign Quota**</mark> on the MaiGPT row, or select MaiGPT in the assignment dialog)         | “This quota is shared by all organization members' MaiGPT usage (including both Classic and Work). When it is exhausted, MaiGPT pauses for the entire organization. Other features are not affected.”                                                    |
| Disable a quota (click <mark style="color:blue;">**Disable**</mark> on the MaiGPT row; the confirmation dialog is titled Disable Inbox Quota) | “Disabling this quota immediately invalidates the organization cap for MaiGPT. If Require Quota remains on, MaiGPT pauses for the entire organization until a new quota is assigned or the restriction is removed. Are you sure you want to disable it?” |
| Turn off Require Quota (the confirmation dialog is titled Remove Quota Restriction)                                                           | “After this restriction is removed, MaiGPT usage is no longer subject to this organization cap and draws directly from the organization wallet. Any active quota will also be disabled.”                                                                 |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-19f3034121a7a89fcba7ba83b5a768df155844c9%2Fcredit-quota-inbox-maigpt-assign-hint.png?alt=media" alt="Assign Inbox Quota dialog: MaiGPT is selected, the text below explains that all organization members share this quota, and the reset period is Monthly"><figcaption><p>When MaiGPT is selected, the assignment dialog explains that the quota is shared across the organization</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9c79d9ea24ea4a2ffe5c175fe4cb585c50d90c6c%2Fcredit-quota-inbox-maigpt-disable-confirm.png?alt=media" alt="Disable Inbox Quota confirmation dialog: explains that disabling immediately invalidates MaiGPT&#x27;s organization cap and pauses MaiGPT for the entire organization if Require Quota remains on"><figcaption><p>Confirmation dialog when disabling the quota on the MaiGPT row</p></figcaption></figure>

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b0d4ce1cc2022490f1cbdb398a704a1b59d9373f%2Fcredit-quota-inbox-maigpt-lift-confirm.png?alt=media" alt="Remove Quota Restriction confirmation dialog: explains that MaiGPT usage draws directly from the organization wallet after the restriction is removed"><figcaption><p>Confirmation dialog when turning off Require Quota on the MaiGPT row</p></figcaption></figure>

{% hint style="warning" %}
When this MaiGPT quota is exhausted, or Require Quota is on without an active quota, **no one in the organization** can use MaiGPT's AI replies. Other features are not affected. Members receive fixed messages when they ask a question: “Insufficient quota. Please contact your organization administrator.” when the quota is exhausted, or “No active quota. Please contact your organization administrator.” when no active quota exists. These two messages do not use the custom Default Message described below.
{% endhint %}

## What Visitors See When the Quota Is Exhausted <a href="#quota-exceeded-behavior" id="quota-exceeded-behavior"></a>

When an inbox quota is exhausted (or Require Quota is on without an active quota):

* **The Agent pauses replies**, and visitors receive a notification. The default system message is: “Sorry, this inbox has reached its Credit quota limit, and the AI assistant has paused replies. We have received your message, and a support representative will reply as soon as possible.”
* **Visitor messages still arrive in the inbox normally**, so human support agents can take over without interruption

You can customize the notification: open the inbox's <mark style="color:blue;">**Inbox Settings**</mark> → <mark style="color:blue;">**Interaction Settings**</mark>, then enter the reply to send when the quota is exhausted in the <mark style="color:blue;">**Default Message**</mark> field. You can also override it by language (and save it in advance even if no quota has been configured).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-14675fad5509485a7811a39c0a569904b5c9623a%2Fquota-05-interaction-default-message.png?alt=media" alt="Default Message field"><figcaption><p>Inbox Settings → Interaction Settings: customize the reply sent when the quota is exhausted in Default Message</p></figcaption></figure>

{% hint style="info" %}
As with member quotas, quota checks use a **Fail-Open** strategy: if the remaining quota is insufficient for a transaction, that transaction is still allowed (usage may temporarily exceed the cap). Only the next transaction is blocked, preventing an interruption at the quota boundary.
{% endhint %}

## View Quotas in Inbox Settings <a href="#view-in-inbox-settings" id="view-in-inbox-settings"></a>

Open an individual inbox's settings and select the <mark style="color:blue;">**Quota**</mark> tab in the left menu to view its used quota, remaining quota, status, and expiration time (read-only). Members with Credit management permission can click <mark style="color:blue;">**Go to Management**</mark> to open the Credits management page, then switch to Quota Allocation.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0221c452e29414a76fb53fb207d682e51f6ae4d2%2Fquota-04-inbox-settings-quota-tab.png?alt=media" alt="Quota tab in Inbox Settings"><figcaption><p>Inbox Settings → Quota: a read-only view of the inbox's quota status</p></figcaption></figure>

## FAQ <a href="#faq" id="faq"></a>

#### Q: What do clients see when the quota is exhausted? <a href="#faq-exceeded-message" id="faq-exceeded-message"></a>

The Agent pauses replies, and visitors receive a notification. If no custom message is set, the system defaults to: “Sorry, this inbox has reached its Credit quota limit, and the AI assistant has paused replies. We have received your message, and a support representative will reply as soon as possible.” Customize it in the Default Message field in Interaction Settings and override it by language. See the [explanation above](#quota-exceeded-behavior).

#### Q: Are human support agents affected? <a href="#faq-human-agent" id="faq-human-agent"></a>

**No.** Quotas limit spending on AI replies only. Once the quota is exhausted, visitor messages still arrive in the inbox normally, and human support agents can take over as usual.

#### Q: Why does used quota sometimes slightly exceed the cap? <a href="#faq-fail-open" id="faq-fail-open"></a>

This is expected behavior under **Fail-Open**: the system allows a request as long as the remaining quota is greater than 0 at the time of the check. Usage is recorded only after the AI finishes responding. The last permitted transaction may therefore push usage slightly above the cap, and only the **next** request is blocked. This ensures users do not encounter a failure after already receiving an AI response.

#### Q: How does an inbox quota differ from the organization wallet? <a href="#faq-quota-vs-wallet" id="faq-quota-vs-wallet"></a>

The organization wallet is the **only pool of funds**, while a quota is a **spending cap**. Assigning a quota does not move any Credits out of the wallet, and quota expiration does not involve a refund. Conversely, if the organization wallet balance is insufficient, AI replies are unavailable even if the inbox still has quota remaining. Both the wallet and all applicable quota layers must have capacity for spending to be permitted.

## Permissions <a href="#inbox-quota-permission" id="inbox-quota-permission"></a>

* Assigning, editing, and disabling inbox quotas requires **Credit management permission** (the same as member quotas), rather than inbox management permission. Quotas are financial controls, so their permissions are deliberately separate from inbox settings
* Inbox management permission is sufficient to view the read-only Quota tab in Inbox Settings


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/others/credits/inbox-credit-quota.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
