Chat agents

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

Chat agents power the embeddable chatbot widget on your website. They handle text conversations over a WebSocket, support rich messages (carousels, cards, quick replies, forms), and capture leads.

Create a chat agent

Dashboard → Agents → New agent → Chat.

Required fields:

Name — internal label.
System prompt — the agent's personality and behavior.
Greeting — first message shown when a visitor opens the widget.
LLM provider + model — see Models.

Optional:

Idle timeout — close the session after N minutes of inactivity. Default 30 minutes (matches the chat.ended webhook timing).
Knowledge base — RAG over your documents.
Lead capture form — see Lead capture below.
Quick replies — predefined buttons the agent can offer.
Navigation — give the agent the ability to navigate the visitor on the host page (open a URL, scroll to a section, fill a form).

Models

LLM providers: OpenAI, Anthropic, Google, Groq, Azure, DeepSeek, Mistral, Together, Fireworks, Cerebras, Perplexity, Grok, OpenRouter.

For chat we recommend:

GPT-4o-mini or Claude Haiku — best cost/quality for most flows.
GPT-4o or Claude Sonnet — reasoning-heavy use cases.

Chat doesn't need STT or TTS — only the LLM provider matters for cost.

Get the embed snippet from your agent's Embed tab and paste it into your website's <head>. See Chatbot widget embedding for the full guide, including positioning, themes, and programmatic control.

Rich messages

Chat agents can render messages beyond plain text:

Type	Use case
Markdown	Default — links, bold, lists, headings.
Carousel	Horizontal scrollable cards (products, services).
Rich card	A single card with title, image, body, and buttons.
Quick replies	Tappable buttons that send a predefined message.
Form	Multi-field form for capturing structured data.
CSAT prompt	1–5 star rating at end-of-conversation.

The agent decides when to render these via tool calls. You configure the catalog of rich messages in the agent editor's Messages tab.

Lead capture

Chat agents can present a form before letting visitors converse — useful for generating leads on your site.

Dashboard → Agents → your chat agent → Lead capture form:

Required — block conversation until form is submitted.
Optional — show form but allow skip.
Off — don't show.

Configurable fields: name, email, phone, custom attributes. Each form submission:

Creates or updates a Contact record in your org's contact database.
Fires the chat.lead.captured webhook immediately (not at chat-end).
Bundles the contact data into the eventual chat.ended and chat.analyzed webhook payloads.

See Webhook events for the lead capture event shape.

Tools

Chat agents share most tools with voice agents:

Knowledge base lookup — RAG against documents you upload.
Custom webhook — POST any URL with extracted parameters and use the response in the chat.
Navigation — navigate_to(url) opens a URL on the host page.
CRM tools — when a CRM integration is attached. See CRM integrations.

Knowledge base

Same as voice — upload PDFs, web pages, or paste text and attach the knowledge base to your chat agent. The agent retrieves relevant chunks when answering questions.

Session model

A chat session is a single conversation thread for a given visitor. It opens when the visitor first sends a message and closes after 30 minutes of inactivity (configurable per agent).

Visitor identity is established via:

Visitor ID — a stable browser fingerprint (FingerprintJS) that persists across sessions on the same browser.
Session ID — per-conversation, stored in localStorage keyed by agent ID. Survives page navigation but resets on long inactivity.

Post-conversation analysis

After a chat session closes, Nerva runs the same post-call pipeline as voice (cost calc + LLM analysis), producing:

Transcript — full message log.
Analysis — summary, outcome, sentiment, custom-extracted data.
Cost breakdown — LLM tokens consumed.
Contact data — merged from the latest captured lead.

Webhooks

Subscribe to real-time events:

chat.started, chat.ended, chat.analyzed, chat.failed
chat.lead.captured — fires the moment the lead form is submitted.

See Webhook events for payload shapes.