Chat agents

Build web-embedded chatbot agents that converse over WebSockets with rich messages, lead capture, and CRM sync.

Chat agents are the web-embedded chatbot experience in Nerva. They run as a widget on your website, connect over WebSocket to a real-time chat backend, and support rich content, lead capture, navigation, and workflow integration.

Create a chat agent

Dashboard → Agents → New agent → Chat

Required fields:

Name: internal label for the agent.
System prompt: the LLM prompt that defines the agent's personality, role, and behavior.
Welcome message: the first message shown when a visitor opens the widget.
LLM provider + model: see Models.

Everything else is optional and grouped into the tabs below.

Behavior

Initial flow: a welcome flow that can present multiple bot messages and steps before the visitor types.
Idle timeout: end the chat after a period of inactivity. Defaults to 30 minutes, which is also when the chat.ended webhook fires.
Message persistence and history length: how much chat state is kept in the visitor's browser. Defaults to on, and the last 50 messages.
Enable human assistant: offer handoff to a human support workflow.
Navigation: let the agent send the visitor to a URL or page section.

Appearance

Position, brand colors, bot name, avatar, branding, placeholder text, timestamps, typing indicator, emoji, and auto-open behavior. See Chatbot widget embedding.

Content and capture

Knowledge base: attach uploaded documents for RAG-powered answers.
Lead capture form: see Lead capture below.
File upload: let visitors attach files, with configurable size limits and allowed extensions.
CSAT: collect a post-chat satisfaction rating.

Tools and workflows

Attach tool calls, integrations, and workflow hooks. See Tools for the full catalog, including the chat-only send_ui tool that renders rich messages, webhook tools, and MCP tools.

Models

Chat agents currently offer three LLM providers in the dashboard:

Google: Gemini 2.5 Flash, Flash Lite, and Pro.
Groq: Llama 3.3 70B, Llama 3.1 8B Instant, and GPT-OSS models.
Azure: Azure-hosted OpenAI deployments.

Gemini 2.5 Flash and Llama 3.1 8B Instant are the cheapest options and suit most support and lead-qualification flows. Move to Gemini 2.5 Pro or a larger Groq model for reasoning-heavy conversations.

Chat does not use STT or TTS, so the LLM is the only per-message model cost.

Agents created before a provider was hidden keep working on their saved provider and model, and the dashboard still shows that model in the picker.

The chat widget is initialized via the agent's public preinit endpoint:

GET /api/widget/[agentId]/preinit

That endpoint returns the widget configuration and a WebSocket URL such as wss://.../ws/chat/{agentId}.

The widget then opens a direct WebSocket connection for real-time chat. This means chat agents do not use a classic HTTP request/response message API; they are live WebSocket sessions with the agent backend.

Use the embed snippet from the agent's Embed tab. The snippet loads the widget launcher and fetches preinit data from your app's public widget API.

For full setup and theming guidance, see Chatbot widget embedding.

Rich messages and interactive content

Chat agents can render rich message types from the chat backend:

Markdown: links, bold text, lists, headings, and formatting.
Quick replies: tappable buttons for visitor choices.
Cards / rich messages: images, headlines, body text, and actions.
Forms: structured input forms embedded in the chat.
CSAT prompt: satisfaction rating at the end of the conversation.

These message types are produced by the agent's response logic and tool calls. The widget renders them using the configured UI components.

Lead capture

You can attach a lead capture form to a chat agent and configure it as:

Required: visitors must complete the form before continuing.
Optional: the form is shown but may be skipped.
Off: no form is shown.

Lead capture supports built-in fields such as name, email, phone, plus custom attributes. When a form is submitted:

a Contact row is created or updated for the organization,
the chat.lead.captured webhook fires immediately,
lead data is included in later chat.ended and chat.analyzed payloads.

See Webhook events for the event shape.

Knowledge base

Attach documents and knowledge bases to a chat agent for retrieval-augmented responses. The agent uses the KB to answer questions with your content, just like voice and other agent types.

Security and embedding controls

Allowed origins: restrict which host domains may open a chat connection. This is enforced when the widget opens its WebSocket, so an embed on an unlisted domain cannot start a conversation. Note that it does not currently gate the public preinit endpoint, which serves widget configuration to any origin, so treat those settings as public.
Status: agents can be active or inactive. Preinit returns 404 for an inactive agent, so the widget never mounts.
Widget secret: a per-agent value shown in the Security tab that you can copy and regenerate. It is reserved for future widget authentication and is not yet checked on any request, so it does not currently restrict access.

Session model

A chat session is a single visitor conversation thread.

The widget establishes identity via:

Visitor ID: a browser fingerprint persisted across visits.
Session ID: per-chat session state stored in localStorage.

Sessions persist through page navigation and expire after the configured idle timeout.

Post-conversation analysis

After the chat ends, Nerva runs a post-chat pipeline that produces:

Transcript: full message log.
Analysis: summary, intent, sentiment, and extracted data.
Cost breakdown: model usage and tokens.
Contact data: latest captured lead information.

Webhooks

Subscribe to chat webhook events for real-time integration:

chat.started
chat.ended
chat.analyzed
chat.failed
chat.lead.captured

For payload details, see Webhook events.