> ## Documentation Index > Fetch the complete documentation index at: https://docs.botbrains.io/llms.txt > Use this file to discover all available pages before exploring further. # Real-time Incident Detection > Catch outages and bugs as customers start reporting them, before your ticket queue explodes Customer support is your product's early-warning system: when something breaks, customers tell you first. Letting AI handle half your volume shouldn't leave you flying blind, and no human team can connect the dots across thousands of conversations. Real-time Incident Detection catches incidents as they start and shows you their scale and customer impact. It watches your incoming conversations for a sudden wave of customers reporting the same problem. When a broken checkout, a login outage, or a bad release makes customers write in, botBrains opens an incident, alerts your team, and collects the affected conversations in one place. You learn about the problem from your customers' first reports, often before the ticket queue fills up. While your team fixes it, you can tell customers what's going on. You find incidents on the [Incidents page](https://platform.botbrains.io/~/incidents). ## What It Catches | Problem | What customers report | | - | - | | **Checkout or payment broken** | They can't finish an order, or the payment step fails with an error | | **Login or app outage** | They can't sign in, or the app or website doesn't load | | **Chat widget failing** | The chat on your website doesn't open, freezes, or loses their messages | | **Shipping partner delays** | Orders with the same carrier or to the same region don't arrive | | **A bad release** | The same bug, right after you updated your app or website | | **Wrong price or promo code** | A product shows the wrong price, or a promo code doesn't apply | A busy hour alone isn't an incident. Spikes with an ordinary explanation, such as a marketing campaign, a price change, a seasonal peak, or many how-to questions at once, don't become incidents. Neither do problems with a single customer's account. ## How It Works Every 5 minutes, botBrains counts how many different customers wrote in over the last 5 to 60 minutes. It does this for each [topic](/concepts/topics) and for your project as a whole. It compares each count with what's normal for that moment and lets AI confirm every unusual spike before it opens an incident. ```mermaid theme={null} flowchart LR S[Unusual spike] -->|AI confirms| A[Active] S -->|AI rejects| N[No incident] A -->|8 hours without reports| C[Closed] C -->|back within 24 hours| A A -->|Not an incident| D[Dismissed] style S fill:#f3e5f5 style A fill:#fff4e6 style C fill:#f5f5f5 style N fill:#f5f5f5 style D fill:#f5f5f5 ``` ### Learning Normal Volume Normal is what botBrains saw at the same weekday and time of day, give or take half an hour, in each of the last 4 weeks. botBrains compares Monday at 10:00 with the last four Mondays around 10:00, not with Sunday night. Conversations of past incidents don't count as normal, so one big outage doesn't hide the next one in that topic. The exception is incidents you [marked as not an incident](#marking-an-incident-as-not-an-incident). ### Spotting a Spike A topic spikes only when these all hold in the same time window: * **Clearly above normal.** At least twice the usual number, at least 4 more than usual, and well beyond the topic's normal ups and downs. * **Not noise from a quiet topic.** Small numbers swing by chance, so a quiet topic needs a minimum number of reports, not just a high ratio. * **Several different customers.** At least 4 different customers wrote in. A customer who writes several times counts once. To give you a sense of scale, this is about how many customers a topic needs within 30 minutes: | Topic at that time of day | Usually | Needed for a spike | | - | - | - | | Quiet | Less than 1 | About 5 | | Medium | About 3 | About 12 | | Busy | About 20 | About 50 | The exact number depends on how much the topic normally varies. Your project's total volume follows the same rules, which catches large problems that spread across many topics. ### Confirming With AI A spike is only a candidate. AI reads what the customers in the spike wrote and compares it with typical conversations of the same topic from previous weeks. It also looks at other topics that spiked at the same time, your open and recent incidents, and the spikes your team recently marked as expected or not a problem. The AI confirms an incident only when several customers independently report the same specific problem, and it must back this with exact quotes from at least 2 different customers. For a confirmed incident it writes: | Part | Meaning | | - | - | | **Title** | A short name for the symptom, in English | | **Summary** | What customers experience | | **How these conversations differ** | What sets them apart from the topic's typical conversations | | **Customer statement** | A short note for affected customers, in their language, used as the suggested wording of the incident's [guidance](/concepts/guidance) | | **Matching rule** | The condition a conversation must meet to belong to the incident | botBrains then tests the matching rule. It must match the quoted conversations and leave nearly all typical conversations alone, otherwise botBrains doesn't open the incident. ### Tracking Affected Conversations Each incident gets its own AI monitor that checks conversations against the matching rule, in every topic. It first checks conversations from the 24 hours before the spike, then every new conversation while the incident is open. The conversations it flags are the incident's affected conversations. Like any [monitor](/concepts/monitors), it checks a conversation once it goes quiet, so affected conversations appear with a short delay. The monitor judges only what the customer wrote. An announcement about the problem from your AI agent or your team doesn't tag every conversation it appears in. If the same problem spreads, for example to another country or platform, botBrains widens the incident instead of opening a new one. Incident monitors don't appear on your monitors page and don't count toward your monitor limit. ### Closing and Reopening An incident closes by itself about 8 hours after its last affected conversation. When the monitor hasn't checked recent conversations yet, botBrains waits for it, so a backlog can't close an incident early. If the same problem comes back within 24 hours of closing, the incident reopens instead of starting a new one. After 7 days, counted from detection, an incident closes even if reports keep coming in. ## What to Expect These are typical values, not guaranteed response times. | Area | What to expect | | - | - | | **Detection delay** | Usually within 30 minutes of the pattern appearing in your conversations, which is typically within the first hour of the incident. | | **Learning period** | Detection starts 4 weeks after your project's first conversation. Each topic needs 4 weeks of history too. Until then, its conversations count toward your total volume only. | | **Topics** | Detection needs [topics](/concepts/topics). When conversations get their topics late, botBrains pauses topic detection and keeps watching your total volume. | | **Minimum reports** | At least 4 different customers within an hour. A problem fewer customers report doesn't become an incident. | | **One incident per problem** | New reports about an open incident join it, without a new incident or a new alert. | | **Re-checks** | After botBrains checks a spike in a topic, it checks that topic again within 24 hours only if the number of extra reports at least doubles. | | **Dismissed incidents** | Stop alerting right away. Matching conversations keep joining them without alerts until they close, and the AI takes your recent dismissals into account for later spikes. | | **Email alerts** | At most 3 incident emails per project and day, counted in Coordinated Universal Time (UTC). Later alerts that day arrive in-app only. | | **Data used** | Only what customers wrote. Replies from your AI agent or your team don't count. | | **Automatic close** | About 8 hours after the last affected conversation | | **Reopen window** | 24 hours after closing | | **Maximum duration** | 7 days from detection. A reopen doesn't extend it, and a recurrence after that becomes a new incident. | | **Imports and hidden conversations** | Bulk imports of conversations don't trigger incidents. [Hidden conversations](/concepts/conversations#hiding-a-conversation) never count. | ## Responding to an Incident Open the incident from the alert. Read the summary and the customer quotes, and check the chart to see whether reports are still coming in. If the spike is expected or harmless, [mark it as not an incident](#marking-an-incident-as-not-an-incident). If it's real, pass it to the team that can fix it, with the link to the incident. Click **Add guidance**. It opens your [guidance](/concepts/guidance) with a new guidance for the incident: when a customer reports the problem, your AI agent tells them it's a known issue, using the customer statement as suggested wording. Review it, then click **Build Version, Set Active** to make it live. Click **Investigate with FDE** or **View conversations** to find out what the affected customers have in common. The incident closes by itself once reports stop. Remove the incident's guidance, or set it to draft, when the problem is fixed. ## The Incidents Page The [Incidents page](https://platform.botbrains.io/~/incidents) lists your project's incidents, active ones first, and refreshes every minute. | Tab | Shows | | - | - | | **Active** | Open incidents. This is the default tab. | | **Dismissed** | Incidents someone marked as not an incident | | **Closed** | Incidents that ended | | **All** | Active and closed incidents, without dismissed ones | Each card shows the incident's title, summary, topics, key times, and how many conversations it affects. The spike at detection, such as **14 in 30 min, usually \~2**, shows how unusual the first wave was. When detection can't run fully yet, a notice at the top explains why: | Notice | Meaning | | - | - | | **Set up topics first** | Your project has no [topics](/concepts/topics) yet. | | **Learning normal volume** | Your project has less than 4 weeks of conversations. The notice shows the date detection starts. | | **Topics are new** | Your topics are younger than 4 weeks, for example because you recreated them. botBrains watches your total volume only until the date shown. | | **Topic detection paused** | Conversations are getting their topics late. botBrains pauses topic detection and keeps watching your total volume until topics catch up. | ## Incident Details Click an incident to open its details. Times show in your local time zone. | Section | Use it to | | - | - | | **What happened** | Understand the problem from the summary, how these conversations differ from typical ones, and up to 3 customer quotes. Each quote links to its conversation. | | **Affected conversations** | See how many conversations match so far. This count grows as botBrains checks more conversations, while the spike at detection stays fixed. | | **Started, Detected, Last report** | See when the first affected conversation came in, when botBrains opened the incident, and when the latest report arrived. | | **Chart** | See whether reports are still coming in. Bars show affected conversations per hour or quarter hour. The line shows all conversations of the topic that spiked, or of your whole project. | | **Topics** | See where affected conversations landed. A **Spike** badge marks the topic that spiked. Click a topic to open its affected conversations. | | **How conversations are matched** | Check the matching rule the AI wrote, to judge which conversations belong to the incident | | **Timeline** | Follow the incident from start to close, including when it closes if no new reports arrive | | **Affected conversations list** | Read the affected conversations, newest first | Right after detection, a banner says that botBrains is tagging affected conversations. The counts, the chart, and the list fill in as the monitor works through them. ### Actions | Action | What it does | | - | - | | **View conversations** | Opens the [conversations page](https://platform.botbrains.io/~/conversations) filtered to the incident, including conversations your AI agent wasn't involved in. You can also pick an incident in the **Incident** filter there yourself. | | **Investigate with FDE** | Opens [botBrains Engineer](/concepts/engineer), the Forward Deployed Engineer (FDE), on the incident, so it can analyze the affected conversations with you | | **Add guidance** | Adds a guidance for the incident to your [guidance](/concepts/guidance), for you to review before you build and set it active. It tells customers who report the problem that it's known, without promising a fix or a time, and doesn't bring it up with anyone else. Not shown for dismissed incidents. | | **Not an incident** | In the **More actions** menu. See [Marking an Incident as Not an Incident](#marking-an-incident-as-not-an-incident). | ## Marking an Incident as Not an Incident When an incident isn't a real problem, open **More actions**, choose **Not an incident**, and pick a reason. botBrains stops sending alerts for it right away. You can do this for active and closed incidents, and you can't undo it. | Reason | When to use it | What happens | | - | - | - | | **Expected or planned** | Something planned or already known caused it, such as a release, a campaign, or an announced outage | Matching conversations keep joining it without alerts until it closes. The AI uses it as an example of what your team doesn't treat as an incident. | | **Not a problem** | Nothing failed. Customers asked about the same thing at once. | Same as **Expected or planned** | | **Duplicate** | Another incident already covers it | It closes right away, and new reports go to the other incident | A dismissed incident never reopens. If the same problem returns within 24 hours of its close, the new reports join it without an alert. ## Alerts Every new or reopened incident alerts your team: | Who | How | | - | - | | Organization Owners, Organization Admins, and Project Owners | In-app and by email | | Other project members who can view conversations | In-app | An alert shows the incident's title, the spike at detection, the summary, and the topics, with a link to the incident. Customer quotes stay in the platform. Each person can turn off incident alerts with the **Incidents** category in their [notification settings](https://platform.botbrains.io/settings/notifications), which the **Notifications** button on the Incidents page also opens. | Rule | Detail | | - | - | | **Email limit** | At most 3 incident emails per project and UTC day, counting new and reopened incidents. After that, people get further alerts that day in-app only. | | **Dismissed incidents** | Send no further alerts | ## Permissions | Action | Who | | - | - | | View incidents and get in-app alerts | Everyone whose role can view the project's conversations. All default project roles can. | | Get alert emails | Organization Owners, Organization Admins, and Project Owners | | Mark an incident as not an incident | Organization Owners and Admins, Project Owners, and Project Contributors | | Add an incident's guidance and make it live | Organization Owners and Admins, Project Owners, and Project Contributors | See [Roles and permissions](/concepts/roles-permissions) for what each role can do. ## FAQ ### How fast will I know about an incident? Usually within 30 minutes of the pattern appearing in your conversations, which is typically within the first hour of the incident. botBrains needs a few minutes of reports to tell a real spike from chance. See [What to Expect](#what-to-expect). ### Why wasn't a problem detected? | Reason | What to check | | - | - | | **Too few customers reported it** | An incident needs at least 4 different customers within an hour, and clearly more than usual for that topic and time of day. See [Spotting a Spike](#spotting-a-spike). | | **The topic is busy anyway** | A topic with many conversations at that time needs a larger jump before it counts as a spike. | | **Detection is still learning** | Your project, or the topic, has less than 4 weeks of history. The [Incidents page](https://platform.botbrains.io/~/incidents) shows a notice. | | **Topic detection paused** | When conversations get their topics late, botBrains watches your total volume only. The Incidents page shows a notice. | | **The AI didn't see one shared problem** | Vague messages that only say something doesn't work, or a mix of unrelated issues, aren't enough evidence. | | **botBrains checked that topic recently** | After a check, botBrains checks the same topic again within 24 hours only if the number of extra reports at least doubles. | | **It joined another incident** | Reports about an open incident join it instead of opening a new one. Check the **Active** tab. | | **Customers reported it elsewhere** | botBrains only sees conversations in your project. Hidden conversations and bulk imports never count. | For a known risk that even one or two customers should flag, set up a [monitor](/concepts/monitors) with an alert. ### Why did I get an alert for something we expected? The AI judges only what customers wrote. It can't know about your campaign, release, or announced maintenance unless the customers' messages make that clear. [Mark the incident as not an incident](#marking-an-incident-as-not-an-incident) with **Expected or planned**. Alerts for it stop right away, and the AI takes your recent dismissals into account when it judges later spikes. ### Does it work for projects with few conversations? Yes, as long as enough customers report the same problem at once. On a quiet topic, about 5 different customers within 30 minutes is enough. A problem that only 2 or 3 customers report doesn't become an incident. For problems you can't afford to miss, use a [monitor](/concepts/monitors) with an alert threshold of 1. Your project also needs 4 weeks of conversation history first. ### Do I need topics? Yes. Detection compares conversations per [topic](/concepts/topics) with the usual level for that time of day, so set up topics first. botBrains also watches your total volume, which catches large problems that span many topics. Each topic needs 4 weeks of history before botBrains watches it on its own. If you delete and recreate your topics, botBrains watches only your total volume for the next 4 weeks. ### What counts as an affected conversation? A conversation that the incident's AI monitor matched against the incident's matching rule, which you see under **How conversations are matched**. It can belong to any topic and any channel, including conversations your AI agent wasn't involved in. The monitor judges only what the customer wrote, so conversations without a customer message and hidden conversations never count. The affected count grows while the incident is open. The spike at detection, such as **14 in 30 min, usually \~2**, stays fixed. See [Tracking Affected Conversations](#tracking-affected-conversations). ### Why does an incident show conversations from before botBrains detected it? Problems often build up over hours, so the monitor also checks conversations from the 24 hours before the spike. **Started** shows the first affected conversation of the wave that led to detection. A similar conversation from more than 8 hours before that wave stays in the list but doesn't move the start time. ### Can I change the thresholds? You don't need to. botBrains learns the thresholds from your own past volume. For each topic, it looks at the same weekday and time of day over the last 4 weeks and at how much the topic normally varies, so the thresholds keep up as your volume changes. See [Learning Normal Volume](#learning-normal-volume). Each person decides whether they get incident alerts. See [Alerts](#alerts). For a specific problem with your own threshold, use a [monitor](/concepts/monitors). ### What happens when I mark an incident as not an incident? Alerts for it stop right away, and you can't undo it. With **Expected or planned** or **Not a problem**, matching conversations keep joining the incident without alerts until it closes. The AI uses it as an example of what your team doesn't treat as an incident. Its conversations also count toward normal volume from then on. With **Duplicate**, the incident closes right away and new reports go to the incident you picked. See [Marking an Incident as Not an Incident](#marking-an-incident-as-not-an-incident). ### Will I get flooded with alerts? botBrains alerts once when an incident opens and once each time it reopens. New reports about an open incident join it without a new alert. Alert emails stop for the day, in Coordinated Universal Time (UTC), after a project's third incident email. Each person can turn off incident alerts in their [notification settings](https://platform.botbrains.io/settings/notifications). See [Alerts](#alerts). ### What if the problem comes back? If it comes back within 24 hours of the incident closing, the incident reopens and botBrains sends a reopened alert. After that, or after an incident reached its 7-day limit, a recurrence becomes a new incident. An incident you marked as not an incident never reopens. See [Closing and Reopening](#closing-and-reopening). ### Can I close an incident myself? No. An incident closes by itself about 8 hours after its last affected conversation, so late reports still join it instead of opening a new incident. If it isn't a real incident, mark it as not an incident to stop its alerts. Marking it as a duplicate closes it right away. ### Which data does incident detection use? Only what your customers wrote in the project's conversations. The AI reads the customer messages in the spike and in typical conversations of the same topic. Replies from your AI agent or your team don't count. botBrains tells the AI to leave names, email addresses, phone numbers, and order or contract numbers out of incident titles and summaries. It rejects any title or summary that contains an email address or a phone number. Customer quotes appear only in the platform, never in alert emails. botBrains processes this data like the rest of your conversations. See [where botBrains runs AI](/trust/faq#where-is-ai-inference-performed) for details. ### Does an incident use one of my monitors? No. The AI monitor that tracks an incident doesn't appear on your monitors page and doesn't count toward your limit of active monitors. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.