Skip to main content

Chat Agent

Audience: Sales · Management · QA · Support · Engineering · Where in app: Settings → AI Agents → Chat Agent (tabs: Behavior, Routing, Chat Interface, Pre-Chat Form, + Tags when GHL is connected, + Bot Flow when bot_flow_enabled) · Plan availability: All plans (model/usage limited by AI Credits — see AI Credits)

The Chat Agent is the AI that responds to visitor chat messages in the widget. When a visitor opens the chat and types, the Chat Agent answers in real time, grounded in the content you trained it with (your Knowledge Base) and, for verified visitors, what the platform already knows about that person. It works around the clock, even outside your working hours, and can hand off to a human when a conversation needs a personal touch.

What it does​

  • Answers visitor questions about your business, products, services, pricing, and policies.
  • Pulls answers from your Knowledge Base (scraped website content, PDFs, manual FAQ Q&A) via RAG.
  • Personalises responses for verified visitors using identity-graph context (name, CRM stage, past conversations, bookings, extracted facts).
  • Greets visitors with a custom welcome message and guides them toward a next step (book a call, fill a form, talk to a human).
  • Hands off to a human in ai_to_human mode when it can't resolve the conversation.
  • Extracts contact details (name/email/phone) and semantic facts from the conversation for the identity graph.
  • Emits quality signals (sentiment, outcome, topics, "failed to answer" count) that Nox and analytics surface.

How it works​

Routing modes — set on companies.ai_config.chat_routing:

ValueBehaviour
aiThe Chat Agent handles the conversation end-to-end.
ai_to_humanThe AI handles it until a takeover condition fires, then hands off to a human agent.
humanNo AI; goes straight to the human queue.

The schema default is ai since 2026-10-08 (backend 772445905, ms-comm mirror d52002f; was ai_to_human) — existing companies keep their stored value. The Routing tab only offers ai (AI Only) and ai_to_human (AI to Human); human is legacy-only. ai_to_human reveals chat_queue + chat_queue_max_per_agent (FIFO human-chat queue, 0 = unlimited).

Model routing (multi-provider). ms-ai resolves the model from companies.ai_config.chat_model + chat_model_provider. The platform is multi-provider: Anthropic (claude-*), OpenAI (gpt-*), plus other providers configured in the catalog (e.g. Groq/Mistral). The service-wide default is the CHAT_MODEL env var (currently gpt-5.1; verify the live value per environment). The same CHAT_MODEL dial also powers the safety/guardrail filter and the Nox admin assistant — they share one model unless split in constants.ts (see cost-tracking/agent-model-bindings.ts).

RAG grounding. Before answering, ms-ai embeds the visitor's question (OpenAI text-embedding-3-small), runs a vector similarity search (cosine distance) over the company's embeddings pgvector table, fetches the top ~20 candidate chunks, then Cohere-reranks down to the top KB_TOP_RESULTS (default 4), and injects those as a "Knowledge" section in the system prompt. If nothing relevant is found the agent falls back to its persona prompt only (more generic, higher hallucination risk — keep the KB tight). See Knowledge Base and Knowledge-Base RAG.

Identity-graph context (verified visitors only). When the visitor has a verified PersonProfile, the prompt also includes: identity (name/email/phone/company/location), engagement (lead score, visit count, first/last seen), recent pages this session, past conversations (last 5 chat/call summaries), CRM state (HubSpot/GHL lifecycle stage, deals, tags), deduped bookings, and extracted facts (e.g. "budget under $5k"). Sections are toggleable globally by super-admin via IdentityGraphDefaultsModel.enabled_sections[]. For unverified ("claimed") sessions, only the current session is in context — no cross-session memory. See Identity Graph.

Streaming. POST /agents/v2/ask-question streams the answer token-by-token over SSE; POST /agents/ask-question is the non-streaming variant. Both are secret-auth (service-to-service, called by the backend, not the browser directly).

Configuration & options​

Configured in Settings → AI Agents → Chat Agent. Stored on companies.ai_chat and companies.ai_config.

AI Engine tab (hidden)​

The tab is commented out of ChatAgent/index.vue; the fields below are still read but not edited here.

SettingFieldWhat it does
Model selectionai_config.chat_model + chat_model_providerWhich LLM powers the agent (speed/accuracy/cost trade-off).
Response styleai_chat.response_sizeconcise / detailed — biases answer length. Plus creativity/precision controls.

Behavior tab​

SettingFieldWhat it does
Modeai_chat.settingquick (template prompts driven by tone) or advanced (full prompt control).
Instructionsai_chat.agent_instructionsThe system prompt (advanced mode). The more specific, the better the responses.
Personality / Toneai_chat.toneprofessional / friendly / casual / etc. — used in quick mode.
Agent nameai_chat.agent_nameName shown to the visitor.

Chat Interface tab​

SettingWhat it does
Widget appearanceColors/layout of the chat window.
Greeting messageFirst message shown before the visitor types — sets the tone.

Routing tab​

SettingFieldWhat it does
Chat routingai_config.chat_routingAI Only (ai, default) / AI to Human (ai_to_human).
Takeover triggersai_chatPhrases / turn-count thresholds that trigger handoff to a human.

Bot Flow tab​

Shown only when company.bot_flow_enabled === true (super admin, per company or agency-wide). Hosts the Bot Flow Builder canvas full-width; ?tab=botflow opens it and the old /settings/ai/bot-flow route redirects here. See Bot Flow Builder.

Tags tab (PostChatTags.vue → ai_chat.post_chat_tags)​

Shown whenever GHL is connected (go_high_level.access_token) — the super-admin widget_chat_tags_enabled gate was removed 2026-09-25 (f1d39fb38 / 021eae6b). One built-in outcome, Chatted with the visitor (engaged, editable tag name, blank → engaged), plus custom {description, tag} rules the AI matches against the transcript. ChatTranscriptEmailJob._applyChatTags applies them after the chat, replacing the feature's managed tag set on the contact (GhlPostCallTagsService.managedTags). Note this means every GHL-connected tenant's contacts now get the engaged tag after a real chat, with no opt-in.

QA/support tip: to confirm which model and prompt a tenant is running, ask Nox ("what model does the chat agent use?") or read companies.ai_config.chat_model and companies.ai_chat.agent_instructions.

Behaviors & edge cases​

  • Takeover (ai_to_human). The AI hands off when: it explicitly flags the conversation as needing human help; the visitor types a configured trigger phrase; N turns pass without resolution; or the visitor asks for a human. On handoff the AI emits connect-to-agent and available agents are notified.
  • Hallucination guard. Answers are grounded in retrieved KB chunks; when retrieval returns nothing the agent leans on its persona prompt and is more likely to be generic/wrong. Keep the KB current; use focused FAQs for high-frequency questions.
  • Fact extraction. After a chat ends, FactExtractionService extracts semantic facts from the transcript → persisted on PersonProfile.extracted_facts[] and agent_memories. State tracked on chats.fact_extraction_state (pending / queued / complete / skipped).
  • Credit exhaustion. Each LLM turn deducts AI credits (logged with source = chat_agent). When credits run out the chat falls back to a human queue (or shows an offline "we'll get back to you" message). Fact extraction is skipped (fact_extraction_state: skipped). See AI Credits.
  • No reply, no charge. If a visitor messages but the AI doesn't reply (e.g. instant handoff to a human), no credits are consumed for that interaction.
  • Multi-persona. There is one Chat Agent per company. "Multiple personas" are achieved with per-page prompt overrides via page rules (same agent, different prompt) — an advanced feature.

Plan & limits​

  • Available on all plans; usage is bounded by AI Credits (each turn is priced per token, weighted by model). See AI Credits.
  • Knowledge-base size (documents / total tokens / page caps) is plan-dependent — verify under billing/plans.
  • Sales/management: heavier/more capable models consume more credits per turn; concise response style and a tight KB reduce burn.

Quality / KPIs​

Tracked on chats.knox.* and surfaced to Nox/analytics:

FieldMeaning
sentimentpositive / neutral / negative
outcomebooked / contact_captured / no_action / escalated
topics_covered[]fixed taxonomy of topics
agent_failed_to_answer_counttimes the AI gave up on a question (find KB gaps)
questions_asked_by_visitor[]surfaced in Nox queries

Nox queries: "show me chats where the AI struggled this week" (agent_failed_to_answer_count > 0); AI-vs-human conversion comparison; whether an extracted fact appears across visitors (cohort signal). Tools: knox-call-transcripts, knox-extracted-facts, knox-aggregate(metric=conversation_quality_breakdown).

Technical implementation​

  • Service: ms-ai, module agents/ (KnockAgentsModule — agents.controller.ts, knock-agents.service.ts).
  • Endpoints: POST /agents/ask-question (non-streaming), POST /agents/v2/ask-question (SSE streaming), POST /agents/auto-trigger-message, POST /agents/chat-summary-notification, POST /agents/extract-contact-details. See ms-ai/API_ENDPOINTS.md.
  • RAG: company/company.service.ts — questionEmbeddings() (embed) → getUserContext() (top-20 by embeddings <=> $vector, then CohereService.rerankItems(... , KB_TOP_RESULTS)). Embeddings stored in the embeddings pgvector table keyed by company.
  • Model wiring: constants.ts (CHAT_MODEL, EMBEDDINGS_MODEL) and cost-tracking/agent-model-bindings.ts (agent label chat).
  • Facts: fact-extraction/ (FactExtractionService), factExtractionQueue (BullMQ).
  • Cost: cost-tracking/ writes a usage_event / usage_charge per call (input/output tokens). See AI Credits.
  • Identity: ms-ai pulls verified-visitor context via the identity-graph gRPC client. See Identity Graph and Nox Assistant.