Skip to content

FAQs Workflow - Complete Implementation

Overview

A fully self-service FAQ knowledge base integrated into the AI agent, allowing customers to get instant answers to common questions without human support. The AI agent can intelligently search and present FAQs based on customer inquiries.

System Architecture

1. FAQ Model (models/faq.py)

- id: int (primary key)
- question: str (searchable)
- answer: text (detailed response)
- category: enum (general, accounts, transactions, security, disputes, fees, transfers, wallets, loans, technical)
- keywords: str (comma-separated for search optimization)
- order: int (display priority)
- is_active: bool (soft delete)
- helpful_count: int (user feedback)
- unhelpful_count: int (user feedback)
- created_on: timestamp
- updated_on: timestamp

2. FAQ Database Schema

  • Stored in support.faq_schema
  • Indexed on: category, is_active, keywords, created_on
  • Supports full-text search on question, answer, keywords

3. FAQ Seed Data (seed/faq_seed.json)

20 comprehensive FAQ articles covering: - General: How to contact support - Accounts: Password reset, verification, KYC, account closure, spending limits, 2FA, biometric login - Transactions: Transaction decline reasons, pending status, cancellation - Security: Account security, lost card, fraud detection, security questions - Disputes: Filing disputes, chargeback process - Fees: Fee structure and explanations - Transfers: Transfer speed, beneficiaries, domestic vs international - Wallets: What are wallets, how to use them - Loans: Loan application process, eligibility - Technical: Technical issues, app problems

AI Agent Tools

1. search_faqs

Purpose: Intelligent FAQ search by keywords and optional category

Parameters: - query (required): Search keywords (e.g., "password reset", "why was I charged", "dispute") - category (optional): Filter by category - limit (optional): Max results (default 10, max 50)

Response: 

{
  "query": "password reset",
  "category_filter": null,
  "total_matches": 1,
  "results": [
    {
      "id": 1,
      "question": "How do I reset my password?",
      "answer": "To reset your password...",
      "category": "accounts",
      "helpful_count": 45,
      "unhelpful_count": 2
    }
  ]
}

Use Cases: - Customer: "How do I reset my password?" → AI searches → Returns exact match - Customer: "My account is locked" → AI searches → Returns related security articles - Customer: "Why are there fees?" → AI searches "fees" → Returns fee articles

2. get_faq_categories

Purpose: Show all available FAQ categories with article counts

Parameters: None

Response: 

{
  "categories": [
    {"name": "accounts", "article_count": 9},
    {"name": "disputes", "article_count": 1},
    {"name": "fees", "article_count": 1},
    {"name": "general", "article_count": 1},
    {"name": "security", "article_count": 4},
    {"name": "transactions", "article_count": 2},
    {"name": "transfers", "article_count": 2},
    {"name": "wallets", "article_count": 1}
  ],
  "total_articles": 20,
  "tip": "Use get_faq_by_category to browse FAQs in a specific category"
}

Use Cases: - Customer: "What topics do you have help for?" → AI shows categories - Customer: "Tell me about security" → AI shows security category

3. get_faq_by_category

Purpose: Browse all FAQs within a specific category

Parameters: - category (required): One of [general, accounts, transactions, security, disputes, fees, transfers, wallets, loans, technical] - limit (optional): Max results (default 10)

Response: 

{
  "category": "security",
  "total_in_category": 4,
  "faqs": [
    {
      "id": 2,
      "question": "Is my account secure?",
      "answer": "Yes, your account is protected by...",
      "keywords": "secure, encryption, protection, privacy, data, safe",
      "helpful_count": 78
    },
    ...
  ]
}

Use Cases: - Customer: "Show me all security articles" → AI retrieves category - Customer: "I want to learn about account security" → AI shows all security FAQs

REST API Endpoints

Search FAQs

POST /api/v1/faq/search
{
  "query": "transfer time",
  "category": "transfers",
  "limit": 10
}

Get Categories

GET /api/v1/faq/categories

Get Category FAQs

GET /api/v1/faq/category/{category}

Get Single FAQ

GET /api/v1/faq/{faq_id}

Mark as Helpful

POST /api/v1/faq/{faq_id}/helpful

Mark as Unhelpful

POST /api/v1/faq/{faq_id}/unhelpful

Permissions

All FAQ tools use access_ai_chat permission: - Available to all users with AI chat access - No special support permissions needed - Public knowledge base (available to all customers)

Example Workflows

Scenario 1: Customer Asks General Question

Customer: "How long do transfers take?"

AI Flow:
1. Calls search_faqs("transfer time")
2. Gets FAQ article about transfer durations
3. Responds with clear explanation:
   - Same bank: Instant to 1 hour
   - Domestic: 1-2 business days
   - International: 3-5 business days
4. Offers: "Would you like to file a dispute if your transfer is stuck?"

Scenario 2: Customer Wants to Browse

Customer: "What security topics do you cover?"

AI Flow:
1. Calls get_faq_categories()
2. Highlights security category (4 articles)
3. Calls get_faq_by_category("security")
4. Shows: Password reset, 2FA setup, lost card, fraud detection
5. Offers: "Which topic would you like to learn more about?"

Scenario 3: Proactive Issue Resolution

Customer: "My card isn't working"

AI Flow:
1. Asks clarifying questions
2. Searches for relevant FAQs
3. Shows possible causes:
   - Card expired → Link to renewal FAQ
   - Spending limit reached → Link to limits FAQ
   - Card frozen → Link to security FAQ
4. Suggests fixes based on situation

Scenario 4: Escalation with Context

Customer: "I read the FAQ but still don't understand"

AI Flow:
1. Acknowledges FAQ was unhelpful (marks unhelpful_count++)
2. Offers escalation: "Would you like to chat with support?"
3. Creates support ticket with FAQ ID for context
4. Support agent sees: "Customer confused about [FAQ topic]"

Key Features

✅ Smart Search - Full-text search on question, answer, keywords - Keyword matching for common variations - Category filtering for precision

✅ User Feedback - Track which FAQs are most helpful - Identify unhelpful articles for improvement - Analytics on customer needs

✅ AI Integration - AI proactively suggests relevant FAQs - AI interprets customer questions to find matches - AI can combine FAQ knowledge with other tools

✅ Self-Service Reduction - Estimated 70% of common questions resolved via FAQ - Reduces support team workload - Instant answers (no wait time)

✅ Continuous Improvement - Track unhelpful articles - Monitor search patterns - Add FAQs based on support tickets

Data Files Created

  1. models/faq.py - FAQ model definition
  2. controller/faq.py - FAQ business logic (search, retrieve)
  3. routers/faq.py - REST endpoints
  4. seed/faq_seed.json - 20 FAQ articles seed data
  5. db/schemas.py - Added FAQ schemas (FAQResponse, FAQSearchPayload, etc.)

Integration Points

  • ✅ AI Agent Tools (3 tools for search and browsing)
  • ✅ REST API for non-AI FAQ access
  • ✅ User feedback mechanism (helpful/unhelpful)
  • ✅ Full-text search optimization
  • ✅ Category-based organization
  • ✅ Permission-based access (public to all)

Future Enhancements

  1. Admin FAQ Management - CRUD endpoints for admins to manage FAQs
  2. Multilingual Support - Translate FAQs to multiple languages
  3. Analytics Dashboard - Track FAQ usage, search patterns, helpful rates
  4. AI-Generated FAQs - Auto-suggest FAQ topics based on support tickets
  5. Related FAQs - Show similar questions when viewing one FAQ
  6. Video FAQs - Support video answers alongside text
  7. Contextual FAQs - Show relevant FAQs based on user context/situation
  8. FAQ Rating System - Detailed ratings and comments from users