Skip to main content

Knowledge-base chat agent

Embed a web chat agent on your site that answers from crawled docs and uploaded PDFs. When a question stumps it, the conversation routes to a Freshdesk ticket so nothing falls through. Cuts your support ticket volume on the FAQs and gives your team better-prepared tickets for the genuine edge cases.

What you'll build​

  • A data source built from your help center, docs site, and product PDFs.
  • An assistant with a citation-friendly system prompt.
  • A chat widget embedded on your site as a one-line script.
  • An intent that detects when the agent has hit its limit.
  • A Freshdesk integration that opens a ticket on escalation.

Step 1 — Ingest your knowledge​

A good support agent is only as good as its sources. Combine these in one assistant:

  1. Build → Data Sources → Add data source.
  2. Add a website crawl of your docs/help center (Crawl website). The crawler chunks pages by headings and embeds them.
  3. Add PDF uploads for anything not on the public web — pricing PDFs, internal runbooks marked safe-for-customers, manuals (Upload files).
  4. Wait for indexing. Re-crawl on a schedule (weekly is usually enough) to keep up with doc changes.

Step 2 — Build the assistant​

  1. Build → Assistants → Add assistant. Pick gpt-4o-mini for cost-effective Q&A.

  2. System prompt — bias toward citing sources and admitting uncertainty:

    You are Acme's support assistant. Answer customer questions using only the linked knowledge sources. When you cite a fact, include a link to the source page.

    If you can't find the answer in the knowledge base — or you're not confident the answer is current — say so plainly: "I'm not sure about that one. Want me to open a ticket so a human can help?" Then wait for confirmation before escalating.

    Never invent product features, prices, or policies. If a question is about billing or account access, escalate immediately — those require account-specific data you don't have.

  3. Link data sources — attach everything from Step 1.

  4. Optionally tighten retrieval in Playground by inspecting which chunks come back for representative questions.

Step 3 — Add the escalation intent​

  1. Build → Library → Intents → Add intent.
  2. Create support_escalation:

    Set when the user explicitly asks for human help, agrees to "open a ticket", or when the assistant has stated twice that it cannot find an answer.

  3. Attach the intent set to the assistant.

The intent fires at conversation close. We'll wire it to Freshdesk in the next step.

Step 4 — Connect Freshdesk​

  1. Open the Freshdesk integration and authorize.
  2. On the assistant, enable the Freshdesk tool. Configure the default ticket properties (group, priority, type).
  3. Open Automation → Workflows → Add workflow. Trigger: conversation closed with intent support_escalation.
  4. Add a call_webhook (or use the Freshdesk tool action directly) that creates a ticket with:
    • Subject: first user message of the conversation.
    • Description: full transcript + which knowledge sources were consulted.
    • Requester email: from the captured contact.

Now any conversation the agent escalates becomes a ticket automatically, with the full chat history attached.

Step 5 — Embed the widget​

  1. Build → Widgets → Add widget. Pick Web chat, link to your assistant.
  2. Customize bubble color, position, greeting, placeholder. The greeting matters — set expectations:

    "Hi! I can answer questions from our docs and pricing pages. If I can't help, I'll set you up with a human."

  3. Copy the embed snippet (one-line <script>) and paste it into your site's HTML before </body>. See Web chat widget for advanced customization.

Step 6 — Watch and tune​

  • Engagements → Conversations — filter by intent. The support_escalation bucket is your gap list: every one represents a question your KB doesn't answer well. Add the missing content, re-crawl, and the agent will resolve those automatically next time.
  • Sample conversations marked "resolved" (no escalation) and check the cited sources matched the question — bad citations are usually fixed by tightening the system prompt or splitting an over-broad doc page into focused sections.

What to do next​

  • Capture feedback in the chat — drop in a Form at the end of resolved conversations to ask "did this help?" Track satisfaction over time in Engagements.
  • Notify on hot tickets — add a second workflow that call_webhooks your Slack channel when the captured Freshdesk ticket subject contains keywords like "outage" or "billing".
  • Same KB on more channels — clone the assistant onto WhatsApp or SMS so customers get the same answers on whichever channel they use.