Documentation
How conversations work, AI processing gates, and lifecycle management.
A conversation is a message thread between a contact and a bot. Conversations are created automatically when a new contact messages a bot — Neuron uses a find-or-create pattern, so the same contact always returns to the same conversation thread. Every message is saved to the conversation history regardless of whether the AI processes it.
Conversations are created from four sources: WhatsApp messages (when a contact messages a number with an assigned bot), the web widget (when a visitor starts a chat), the Bot API (when your backend calls /chat or /compose with a new contact), and the dashboard (when an agent starts a conversation manually). If a WhatsApp message arrives on a session with no bot assigned, no new conversation is created — the message is routed to any existing conversation for that contact, or dropped if none exists.
The same contact always maps to the same conversation per bot. If a conversation is closed and the contact messages again, a new conversation is created.
This is the most important distinction in Neuron. Saving and processing are two separate steps. Saving always happens — every incoming message is stored in the database and visible in the dashboard, regardless of any configuration. Processing is conditional — the AI only generates a response when all processing gates pass. This means pausing a bot, disabling processDms, or taking over a conversation will stop AI replies, but messages are never lost.
A common misconception is that disabling processDms or processGroups prevents messages from being saved. It does not — messages are always saved. Only AI processing is skipped.
When a message arrives, it passes through an ordered series of gates before the AI processes it. If any gate fails, the message is saved but the AI does not respond. The gates run in this order: (1) Bot exists — the session must have an assigned bot, (2) Bot is active — the bot must not be paused (bot.isActive), (3) Conversation bot is active — a human must not have taken over (conversation.isBotActive), (4) Human agent delay — if the last message was from a human agent, wait 15 seconds before processing to avoid the bot stepping on an ongoing human reply, (5) Message processing toggle — processDms must be true for DMs, processGroups must be true for groups (widget and playground conversations bypass this gate), (6) Learning source — if the message is from an admin or owner, it is routed to the learning queue for reflection analysis instead of AI processing, (7) Group filter — for group messages, an algorithmic filter decides whether the message needs a bot response based on mentions, context, and conversation patterns.
Conversations have a status field and an isBotActive flag. The status can be: Active (bot is handling it normally), Escalated (bot has flagged it for human review or a human has taken over), or Closed (conversation is resolved). The isBotActive flag controls whether the AI processes new messages — when false, messages are saved but the AI does not respond. Both takeover and escalation set isBotActive to false.
Takeover can happen in three ways. Explicit takeover: click "Take Over" in the dashboard — this assigns the conversation to you and pauses the AI. Implicit takeover via dashboard: when any agent sends a message from the dashboard, the conversation is automatically taken over. Implicit takeover via WhatsApp: if someone replies directly from the WhatsApp device connected to Neuron, the conversation is automatically taken over — useful for quick replies without opening the dashboard. In all cases, isBotActive is set to false and the conversation status becomes "escalated".
During takeover, if the AI was mid-processing when you took over, its response is saved but marked as suppressed — it won't be sent to WhatsApp, but you can see it in the dashboard.
When a conversation is escalated or taken over, Neuron can automatically return it to the bot after a period of inactivity. Configure humanIdleTimeoutMinutes on the bot — if no human agent message is sent within that window, the conversation is automatically released back to the bot. The evaluation checks three things: (1) the conversation is still escalated, (2) no agent has replied since the timer started, and (3) the message type is allowed by the bot's processing toggles (processDms for DMs, processGroups for groups). If humanIdleTimeoutMinutes is not set, recovery never happens automatically.
Release a conversation to hand it back to the bot. This sets isBotActive to true, clears the assigned agent, and changes the status back to "active". The bot resumes responding to new messages immediately. Closing a conversation marks it as resolved — the status changes to "closed" and it moves to the Closed tab. If the same contact sends a new message, a new conversation is created.
Group messages have additional controls beyond processDms. The processGroups toggle must be true for the bot to respond in any group. Beyond that, you can configure a processGroupWhitelist — an array of specific group chat IDs the bot should respond in. For groups that pass the whitelist, an algorithmic group filter decides whether each individual message warrants a response (based on mentions, direct questions, conversation context). If the AI decides no response is needed, it returns a [NO_RESPONSE] signal — the message is saved but nothing is sent to the group.
Silent mode is a per-session setting for multi-session bots. When a session is in silent mode, the bot still processes the message through the full AI pipeline (runs the LLM, executes tools), but does not send a visible WhatsApp reply. The assistant message is still saved to the database and visible in the dashboard. This is useful for group moderation — the bot can sit in a group, run moderation tools (e.g., spam detection, content filtering), but never post a chat reply.
The confidence gate applies to DMs only (not groups). After the AI generates a response, Neuron scans it for signs of business uncertainty — phrases like "I'm not sure", "I don't have that information", "you'd need to contact", or multiple hedging phrases like "I think", "approximately", "usually". If uncertainty is detected, the response is not sent to the customer. Instead, the conversation is automatically escalated, a fallback message is sent (if configured), and the team is notified. This prevents the bot from giving customers inaccurate information about your business.
Configure a good fallback message on your bot — something like "Let me connect you with someone who can help." This is what the customer sees when the confidence gate triggers.
The Conversations page shows all conversations for a selected bot. Filter by status (active, escalated, closed) to focus on what needs attention. Each conversation shows the contact name, phone number, last message, and current status. Conversations update in real-time via WebSocket — new messages, status changes, and escalations appear instantly without refreshing.