> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardrails: protect your AI agent from spam and abuse

> Protect your AI agent from abuse with rate limits, automatic spam detection, and country blocking.

Guardrails are the Chatbase settings that protect your AI agent from abuse: a **Rate limit** that caps how fast visitors can send messages, **Spam detection** that pauses spammy or abusive conversations, and **Country blocking** that hides your AI agent from visitors in chosen countries. They're set per AI agent and apply mainly to your website channels (Chat Bubble, Center Stage, and Help Page), with some coverage of the API and messaging channels, as listed in each section below.

Go to **Build > Guardrails**. The page has two tabs:

* **Auto protection** holds two cards: **Rate limit** and **Spam detection**. Each card has its own **Save** button, so save after editing one before moving to the other.
* **Blocklists** holds **Country blocking**, which hides your AI agent from visitors in the countries you choose.

> [!NOTE]
>
> Guardrails here are about protecting your AI agent from abuse. To set behavioral rules the AI agent must follow in its replies, such as topics to avoid, use the **Guardrails** section of the instructions editor instead. See [Instructions](https://chatbase.co/docs/user-guides/chatbot/build.md#guardrails-instructions).

> [!TIP]
>
> You can also ask [Backstage](https://chatbase.co/docs/user-guides/chatbot/backstage.md) to change spam detection or country blocking. It asks for your approval before saving. Backstage can't change the rate limit.

## Rate limit

Use **Rate limit** to cap how many messages can be sent to your AI agent from one IP address over a chosen time period.

Set **Limit to** *N* **messages every** *N* **seconds**, then write the **Message to show when limit is hit**. Visitors who exceed the limit see this message instead of a reply until the window resets.

![Rate limit](https://mintcdn.com/chatbase/_7J6eyqGPyLZWnmQ/images/guardrails-rate-limit.png?fit=max\&auto=format\&n=_7J6eyqGPyLZWnmQ\&q=85\&s=526b59134132942728e718568e36f06d)

### Defaults and allowed values

| Setting | Default | Allowed values |
| - | - | - |
| **Limit to** (messages) | 20 | 1 to 200 |
| **every** (seconds) | 240 | 1 to 3,600 |
| **Message to show when limit is hit** | "Too many messages in a row" | Any text |

If a value is out of range, the card shows an error such as "Message limit cannot exceed 200 messages" or "Time limit cannot exceed 3600 seconds".

### How visitors are counted

The rate limit doesn't identify individual devices. It counts messages per IP address, per AI agent. Visitors who share one IP address, such as people on the same office network, share the same limit. If your AI agent serves many people behind one network, raise the limit.

### Where the rate limit applies

* **Applies to:** the Chat Bubble and iframe, Center Stage, Help Page, and voice on the web
* **Doesn't apply to:** API calls, the Playground and Compare, Tests, Helpdesk AI draft replies, email, and Phone

## Spam detection

Use **Spam detection** to have Chatbase automatically check conversations for spam. When spam is detected, the conversation is paused and the AI agent stops replying to it. You can also [pause conversations manually](https://chatbase.co/docs/user-guides/chatbot/activity.md#pausing-a-conversation) from **Activity > Conversations**.

Turn the toggle on to enable it. The check runs after the 2nd, 4th, 8th, and 16th user message in a conversation, so it catches abuse early. Spam checks don't use your message credits.

![Image](https://mintcdn.com/chatbase/3pXUdlAnPude4UYE/images/image-18.png?fit=max\&auto=format\&n=3pXUdlAnPude4UYE\&q=85\&s=effca2dfe4193b52617ffd9499f78132)

Here is how a paused conversation from spam detection looks:

![Image](https://mintcdn.com/chatbase/3pXUdlAnPude4UYE/images/image-23.png?fit=max\&auto=format\&n=3pXUdlAnPude4UYE\&q=85\&s=3c2f4c71637e806ce5c29f2a2ac13345)

### Defining what counts as spam

The **What counts as spam for this AI agent** field holds the instructions the spam checker follows, up to 2,000 characters. Chatbase provides a default that flags:

* **Profanity**, such as vulgar, obscene, insulting, or sexually explicit words or slang, in any language.
* **Spam**, such as unsolicited commercial promotions, scams, repetitive gibberish, random keyboard mashing, or emoji-only messages.

Edit the text to fit your use case. For example, you might loosen the profanity rule for a casual brand, or add patterns you see often, such as competitor promotions or repeated links. Be specific about what should and should not be flagged, since anything the checker considers spam pauses the conversation for that user.

If the toggle is on but this field is empty, no check runs.

> [!TIP]
>
> Start with the default definition and adjust it after reviewing paused conversations in [Activity](https://chatbase.co/docs/user-guides/chatbot/activity.md). Too broad a definition can pause legitimate users who are simply frustrated.

### What happens when a conversation is paused

* **The visitor** can keep sending messages. They're saved, but the AI agent doesn't reply, and the visitor sees no error.
* **Your team** sees "Paused by spam detection" on the conversation, with how long ago it was paused and the reason the spam checker gave.

### Resume a paused conversation

1. Go to **Activity > Conversations** and open the conversation.
2. Open the conversation's menu and click **Resume conversation**.

**Resume conversation** is disabled for conversations that have ended or that a human has taken over. You can also ask [Backstage](https://chatbase.co/docs/user-guides/chatbot/backstage.md) to resume a conversation, with your approval. A resumed conversation can be checked and paused again at a later checkpoint.

### Supported Channels

Spam detection works across the following channels and experiences:

* **Chat widget**, including the Chat Bubble, and iFrame
* **Center Stage**
* **Help Page**
* **API v1 and v2**
* **WhatsApp, Messenger, and Instagram**
* **Playground, Q\&A preview, and Action preview**: these are internal testing experiences, not customer-facing channels. Spam detection still runs there, so testing with rude or nonsense messages can pause your test conversation.

Spam detection is **not supported** on:

* **Slack**
* **Email**: email uses its own spam detection system
* **Zendesk Messaging**
* **Phone**
* **Facebook and Instagram comments**: these become Helpdesk tickets, not AI agent conversations

## Country blocking

Use **Country blocking** on the **Blocklists** tab to hide your AI agent from visitors in specific countries. Chatbase detects a visitor's country from their IP address and blocks anyone from a listed country from reaching the AI agent.

### Blocking a country

1. Go to **Build > Guardrails** and open the **Blocklists** tab.
2. Under **Blocked countries**, open the **Select countries...** dropdown and search for a country by name.
3. Select each country you want to block. Selected countries appear as chips below the dropdown.
4. Click **Save**.

![Country blocking](https://mintcdn.com/chatbase/IvktngihE88rUfYA/images/guardrails-country-blocking.png?fit=max\&auto=format\&n=IvktngihE88rUfYA\&q=85\&s=20989e035661ac74d2e6833048af51cc)

To unblock a country, click the **X** on its chip and save again.

### Allowing only a few countries

To make your AI agent available in only a few countries:

1. Click **Select all** in the country picker.
2. Unselect the countries you want to allow.

When most countries are blocked, the card lists the countries that can still reach your AI agent instead, for example: "Only these 3 countries can reach this AI agent."

### Supported Channels

* Website **Chat Bubble** and **Center Stage**: these will not be displayed to blocked visitors.
* **Help Page**: blocked visitors will receive a `404` error.
* **API**: chat requests (API v1 and v2) originating from blocked countries will be rejected with "This chatbot cannot be found".
* **Voice on the web**: blocked visitors can't start a voice session.

> [!NOTE]
>
> Country blocking does not apply to **WhatsApp, Messenger, Instagram, Slack, Zendesk, email, Phone, or the Playground**. Conversations through these channels will continue as usual, regardless of the user's location.

## Frequently asked questions

> [accordion] Why are several visitors hitting the rate limit at once?
>
> The rate limit counts messages per IP address, not per device. Visitors behind one IP address, such as a shared office or school network, share the same limit. Raise **Limit to** so more messages fit in each window.

> [accordion] Does spam detection use message credits?
>
> No. Spam checks are free and don't count toward your message credits.

> [accordion] Can I unpause a conversation that spam detection paused?
>
> Yes. In **Activity > Conversations**, open the conversation's menu and click **Resume conversation**. The AI agent then replies to new messages again.

> [accordion] How do I see which conversations spam detection paused?
>
> In **Activity > Conversations**, set the **Conversation state** filter to **Paused**. Conversations paused by spam detection show "Paused by spam detection" with the reason the spam checker gave, so you can check that your spam definition flags the right conversations.

> [accordion] What does a paused visitor see?
>
> Nothing changes for them on screen. Their messages are saved, but the AI agent doesn't reply and no error is shown.

> [accordion] Can I allow only certain countries?
>
> There's no allowlist mode, but you can get the same result: click **Select all** in the country picker, then remove the countries you want to allow, and save.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.