Skip to content
11 min read

AI Agent & Knowledge Base

Wallin's AI agent answers routine customer questions automatically, using only the knowledge you provide. It speaks in your brand voice, respects your guardrails, and hands off to a human the moment a question is outside its scope.

The agent runs as an automation flow on your WhatsApp, Instagram, and Messenger connections — enabled independently for each channel and answering on your schedule (always on, or only outside agent shifts).

Enabling the AI Agent

The AI agent is disabled by default. To turn it on:

  1. Click the Settings menu (top-right corner) and go to AI Assistant, or visit /ai
  2. Scroll to Channels at the bottom
  3. For each connection (e.g., "Support - WhatsApp", "Sales - Instagram"), toggle the AI on/off
  4. Choose Always on (responds 24/7) or Outside shifts only (responds when no agents are working)
  5. Click Save AI settings

The agent is now live. New customer messages matching your flows will trigger the agent to respond.

Building Your Knowledge Base

The agent answers only from the knowledge you give it. It will never invent answers or guess about topics you haven't documented.

Adding Knowledge Sources

Go to /ai and scroll to Knowledge. You'll see tabs for different source types. Add knowledge in any combination:

Text (FAQ or policy snippet)

When to use: Quick wins — add your return policy, shipping info, or business hours as plain text.

  1. Click the Text tab
  2. Enter a title (e.g., "Shipping & Delivery FAQ")
  3. Paste your text (FAQs, policies, product info — line breaks are fine)
  4. Click Add text

The text is indexed immediately and the agent can reference it.

URL (Single page)

When to use: A specific FAQ page or help article you maintain.

  1. Click the URL tab
  2. Paste a full URL (e.g., https://your-site.com/faq)
  3. Click Fetch page

Wallin fetches the page, extracts text, and indexes it. If you update the page later, re-add the URL to refresh.

Website (Full crawl)

When to use: Your entire website's public pages (FAQs, About, Sizing Guide, Policies).

  1. Click the Website tab
  2. Paste your site's base URL (e.g., https://your-site.com)
  3. Click Crawl site

Wallin reads your sitemap (or follows links) and imports up to 30 pages from your site. Pages are re-checked automatically every 24 hours for changes — if you update your site, the agent learns automatically.

Important: The crawler respects robots.txt and will not index pages marked as private or noindex.

Document (PDF, Word, text, Markdown)

When to use: Handbooks, product guides, menus, or materials you maintain offline.

  1. Click the Document tab
  2. Click "Choose File" and select your PDF, .docx, .txt, or .md file (max 10 MB)
  3. Click Add document

Only the text is extracted and indexed — formatting and images are not kept.

Q&A CSV (Question-answer pairs)

When to use: You have pre-written questions and answers (e.g., a support FAQ sheet).

  1. Click the Q&A CSV tab
  2. Prepare a CSV file with two columns: question and answer (max 500 rows) 
    question,answer
"What's your return window?","30 days from purchase. Items must be unworn and original tags attached."
"Do you ship internationally?","We ship to GCC countries only."
  3. Upload the file
  4. Click Import Q&A

Q&A pairs are indexed and the agent will answer similar customer questions.

Google Drive (if enabled)

When to use: You maintain PDFs, Word docs, or Google Docs on Google Drive and want automatic syncing.

  1. Click the Google Drive tab (only visible if your admin enabled this feature)
  2. Click Connect Google Drive and authorize Wallin to access your Drive
  3. Click Browse Drive files and search for files
  4. Click Import next to a file

Imported files are re-synced every 24 hours — if you update a file on Drive, the agent learns automatically.

Note: Once connected, you can enable/disable individual files from the Knowledge table.

Knowledge Base Limits

  • Max sources: 50 (you can add 50 files, URLs, text snippets, Q&A imports, or Drive files combined)
  • Max total tokens: 150,000 tokens (~100,000 words)
  • Document size: 10 MB per file
  • Q&A rows: 500 rows per CSV
  • Website crawl: 30 pages maximum, 2 levels deep
  • Refresh cadence: Every 24 hours for crawls, URLs, and Google Drive files

If you exceed limits, you'll see a warning. Older or least-used sources are a good place to trim.

Managing Sources

In the Knowledge section, you'll see a table of all sources with columns:

  • Source — Title and type (Text, URL, Document, Q&A, Website, Google Drive)
  • Status — Ready (green), Pending (yellow), Failed (red), or Indexing
  • Size — Token count (~1 token ≈ 0.75 words) — shows you how much of your 150,000-token budget is used
  • Actions:
    • Retry (if failed) — Try indexing again
    • Remove — Delete from the knowledge base

Testing the Agent in the Sandbox

Before the agent goes live, test it.

  1. Scroll to Test the assistant in the Knowledge section
  2. Type a test question (e.g., "What's your return policy?" or "Do you ship to Khobar?")
  3. Click Ask

The agent responds with either:

  • An answer (green background) — The agent found knowledge to answer. You'll see:

    • The answer text
    • Confidence level (High = strong match, Needs review = the agent isn't sure)
    • Cost: 1 credit per test

  • Escalation (amber background) — The agent says "I should hand off to your team" and explains why (knowledge gap, guardrail topic, customer's tone signals frustration)

Use the sandbox to:

  • Verify your knowledge base is indexed correctly ("Can the agent answer common questions?")
  • Identify knowledge gaps ("The agent said 'I don't know about X' — add info about X")
  • Tune guardrails ("This question should escalate but the agent answered it — add to 'Never answer about' topics")

Configuring Persona & Tone

Name

The name customers see when the agent replies. You can call it "Support Bot", "Nour", "AI Assistant", or leave blank for a generic "Support" label.

Go to /ai, scroll to Persona, and fill in Name shown to customers.

Tone

How the agent speaks:

  • Friendly — Conversational, warm, encouraging ("Hey! I'd love to help with that.")
  • Formal — Professional, structured, polite ("Thank you for your inquiry. Here is the information you requested.")
  • Brief — Short, direct, to the point ("Yes. Free shipping over 50 SAR.")

Reply Language

  • Match the customer — Reply in the language the customer used (Arabic if they write Arabic, English if English)
  • Arabic — Always reply in Arabic
  • English — Always reply in English

Brand Voice

Add a short description of your brand personality. Examples:

  • "We're a sustainable, youth-focused fashion brand. Be casual, trendy, and fun. Emphasize our eco-friendly practices."
  • "Luxury hotel chain. Be warm, formal, and attentive. Anticipate guest needs. Use their name if known."
  • "Fast-food restaurant. Be friendly and quick. Use food emojis. Keep responses short."

Click Save AI settings when done.

Setting Guardrails

Guardrails tell the agent when not to answer, forcing escalation to a human.

Never Answer About

Add topics the agent should refuse to discuss:

  1. Scroll to Guardrails in /ai
  2. Click the Never answer about section
  3. Type a topic (e.g., "legal issues", "refunds over 500 SAR", "password resets")
  4. Click Add

When a customer asks about a guardrail topic, the agent responds: "That's something I need to hand off to my team. They'll follow up shortly." Then a human takes over.

Hand Off Immediately

Add keywords that trigger instant escalation (customer is frustrated, demanding a human, etc.):

  1. In Guardrails, scroll to Hand off immediately when the customer says
  2. Type a keyword or phrase (e.g., "I want to speak to a human", "this is ridiculous", "manager")
  3. Click Add

Built-in escape keywords (always enabled, can't be removed) include variations of "human", "agent", "manager", "complaint", and "frustrated".

Auto-Reply Behavior

Control how long the agent stays in a conversation and what it says during transitions.

Conversation Limit

How many back-and-forth replies the agent will participate in before handing off:

  1. Go to /ai → Auto-reply behavior
  2. Set Conversation limit (default: 15 turns)
  3. Accepted range: 3 to 30 turns (depending on your plan)

After 15 replies, the agent says: "I've reached the end of what I can help with. A team member will take it from here." Then a human agent takes over.

Session Reset

If a customer goes silent and then returns days later, do they get a fresh agent session (new intro, new conversation charge) or continue the old one?

  1. Set Session resets after (default: 24 hours idle)
  2. Accepted range: 1 to 24 hours

After idle time expires, the next message triggers a fresh agent session with a new introduction.

Custom Messages

Wallin shows customers pre-written messages at key moments. You can customize them:

  1. Introduction — First reply of each session (default: "Hi! I'm [Name], here to help. What can I do for you?")
  2. Handing off — When escalating to a human (default: "I'm passing you to my team. They'll follow up shortly.")
  3. Reached limit — After max conversation turns (default: "I've reached the end of what I can help with. A team member will take it from here.")
  4. While waiting — Reassurance while waiting for human (default: "Thanks for your patience. A team member will reply shortly.")
  5. Unavailable — When AI system is down (default: "We're experiencing technical difficulties. A team member will help shortly.")

Leave fields blank to use Wallin's built-in defaults (bilingual Arabic/English). Edit to match your brand.

Click Save AI settings when done.

Using the AI Agent in Flows

The agent is deployed via an AI Agent automation flow step. You can add it to any flow:

  1. Go to Automation → Flows
  2. Create a new flow or edit an existing one
  3. Add a step: AI Agent
  4. The agent runs according to the settings above
  5. If the agent escalates, the conversation routes to your team

For full flow-building instructions, see Automation Flows.

Monitoring Agent Performance

In the /ai page, near the top, you'll see:

  • AI credits left this month — Your remaining monthly budget
  • CSAT (AI-inferred, this month) — Customer satisfaction score for resolved conversations
  • Assistant · last 7 days:
    • Active now — Conversations currently in progress
    • Conversations — Total bot sessions in the last 7 days
    • Handed off — How many bot conversations escalated to humans
    • Handled alone — Percentage of conversations the bot resolved without escalation
    • Handoff reasons — Why the agent escalated (knowledge gap, guardrail, customer asked for human, reached conversation limit, etc.)

Use this data to:

  • Identify knowledge gaps ("Many handoffs due to 'knowledge gap' — add to KB")
  • Tune guardrails ("Customers asking about X keep escalating — is it a guardrail topic?")
  • Measure agent quality ("80% resolved alone = working well; 40% = need more knowledge or better guardrails")

Billing & Credits

  • Free features:

    • Adding and managing knowledge sources
    • Configuring persona and guardrails
    • Sandbox testing (wait, that's 1 credit per test — but you can test a lot before going live)
    • Lead scoring and tagging
    • Handoff summaries and bot metadata

  • Paid features (deduct from your monthly AI credits):

    • Bot conversation — First reply in a new conversation: 10 credits (subsequent replies in same conversation: free)
    • Copilot draft/rewrite/translate — 1 credit each
    • Custom copy generation — 2 credits
    • Sandbox testing — 1 credit per test

If you run out of credits mid-month, the agent stops answering and hands everything to your team. See Plan & Usage to buy more credits or upgrade your plan.

Troubleshooting

"The agent said something wrong"

  • Check your knowledge base for outdated info. Update or remove the source.
  • Test in the sandbox with the exact customer question. Does the agent give the right answer there?
  • If the knowledge is correct but the agent misunderstood, add the Q&A pair to a Q&A CSV for explicit answers.

"The agent isn't answering some common questions"

  • Verify those questions are in your knowledge base.
  • Test in the sandbox. If the agent says "I don't know", the topic isn't indexed yet.
  • Add more details about those topics — the agent works better with more context.

"The agent is answering things it shouldn't"

  • Check your Guardrails → Never answer about list. Is the topic there?
  • Test in the sandbox — does it escalate correctly?
  • If the sandbox works but live doesn't, it may be a knowledge indexing delay (up to 1 minute after you add a source).

"I see a warning about AI credits or being unavailable"

  • Check /ai at the top — do you have credits left?
  • If out of credits, upgrade your plan or wait until the next billing cycle.
  • If it says "unavailable", Wallin's AI service may be down temporarily. Try again in a few minutes.

Next Steps

  1. Build your knowledge base — Add your FAQs, menu, policies, or website
  2. Configure persona and guardrails — Set your brand voice and safety rules
  3. Test in the sandbox — Verify it answers correctly
  4. Enable on your channels — Turn it on for WhatsApp, Instagram, or Messenger
  5. Monitor performance — Check handoff reasons and refine your knowledge

Ready to automate routine questions? Build your first knowledge base today.

Was this page helpful?
Previous ← Frequently Asked Questions
Next Inbox Copilot →

See Wallin on your own channels.

Book a walkthrough — we'll connect a test account and show you the inbox, broadcasts, and automation live.

Request a demo Sign in