Skip to main content

FAQ Knowledge Base System

The FAQ (Frequently Asked Questions) system provides a self-service knowledge base for both customers and staff, reducing support ticket volume and enabling faster issue resolution.

See also: Support Tickets <support_tickets> for ticket management, Customer Care <customer_care> for customer support features.

Overview​

The FAQ system enables:

  1. Self-Service — Customers find answers without creating tickets
  2. Knowledge Base — Centralized repository of solutions
  3. Staff Resource — Quick reference for support staff
  4. Continuous Improvement — Track which FAQs are most helpful
  5. Multi-Category — Organize FAQs by topic and tags
  6. Visibility Control — Public vs internal FAQs
  7. Analytics — View counts and helpfulness ratings

Key Features​

FAQ Management​

  • Create FAQs — Write questions and detailed answers
  • Rich Content — Markdown formatting, images, code blocks
  • Categorization — Organize by category and tags
  • Visibility — Control customer vs staff-only access
  • Search — Full-text search across titles and content
  • Versioning — Track changes and updates over time

Analytics​

  • View Tracking — Count how many times FAQ is viewed
  • Helpfulness — Customers rate if FAQ was helpful
  • Popular FAQs — Most viewed questions
  • Most Helpful — Highest rated solutions
  • Low Performers — FAQs marked as unhelpful (need improvement)

Organization​

  • Categories — Group related FAQs (Billing, Technical, Account, etc.)
  • Tags — Multiple tags per FAQ for cross-categorization
  • Search — Quick find by keyword
  • Filtering — Filter by category, tags, visibility
  • Sorting — By date, views, helpfulness, alphabetical

FAQ Structure​

Required Fields​

  • Question — Clear, concise question (the FAQ title)
  • Answer — Detailed response with step-by-step instructions
  • Category — Primary categorization
  • Visibility — Customer-visible or staff-only

Optional Fields​

  • Tags — Additional categorization keywords
  • Related FAQs — Links to similar questions (future feature)
  • Attachments — Screenshots, documents, videos (future feature)
  • Author — Staff member who created FAQ
  • Last Updated — When FAQ was last modified

Example FAQ​

Question: How do I check my data usage?

Category: Account Management

Tags: data, usage, balance, self-care

Answer:

You can check your current data usage in several ways:

## Via Self-Care Portal

1. Log in to your account at portal.example.com
2. Go to **Services** tab
3. Click on your mobile service
4. View **Balance** section
5. Your data usage displays as "Data Used / Total Data"

## Via Mobile App

1. Open the mobile app
2. Tap **My Services**
3. Select your mobile line
4. Data usage shows on the overview screen

## Via SMS

Send **BAL** to 123456 to receive your current balance via SMS.

## Need Help?

If you can't see your usage, please contact support at support@example.com

Visibility: Customer Visible

Viewing and Editing FAQs​

When viewing an FAQ, all markdown formatting is rendered as rich HTML with proper styling for headers, lists, code blocks, and links.

FAQ Detail View Figure 1: FAQ detail view showing rendered markdown content with formatted headers, lists, and code blocks

The FAQ detail page provides:

  • Rendered Content — Markdown automatically converted to formatted HTML
  • Statistics — View count and helpfulness ratings
  • Edit Mode — Inline editing with markdown support
  • Visibility Toggle — Show/hide from customers
  • Quick Actions — Copy link, delete FAQ

Customer View​

Customers see a clean, formatted view of FAQs without edit capabilities:

FAQ Customer View Figure 2: Customer-facing FAQ view with helpfulness rating and clean formatting

Creating FAQs​

Via Web UI​

  1. Navigate to Support → FAQs
  2. Click Create FAQ
  3. Fill in FAQ details:
    • Question (title)
    • Answer (content with markdown)
    • Category
    • Tags (comma-separated)
    • Visibility (customer-visible checkbox)
  4. Click Create

Via API​

POST /crm/faq/

Required Permission: create_faq

Request:

{
  "question": "How do I reset my password?",
  "answer": "To reset your password:\n1. Go to login page\n2. Click 'Forgot Password'\n3. Enter your email\n4. Check your inbox for reset link\n5. Click link and set new password",
  "category": "Account",
  "tags": "password,login,account,reset",
  "is_visible_to_customer": true
}

Response:

{
  "faq_id": 42,
  "question": "How do I reset my password?",
  "answer": "To reset your password:\n1. Go to login page...",
  "category": "Account",
  "tags": "password,login,account,reset",
  "is_visible_to_customer": true,
  "view_count": 0,
  "helpful_count": 0,
  "not_helpful_count": 0,
  "created": "2026-01-07T10:00:00Z",
  "last_modified": "2026-01-07T10:00:00Z",
  "created_by_user": {
    "id": 1,
    "username": "admin",
    "first_name": "Admin",
    "last_name": "User"
  }
}

Editing FAQs​

Updating Content​

  1. Open FAQ from list
  2. Click Edit
  3. Modify question, answer, or metadata
  4. Click Save

Changes are tracked with:

  • Last modified timestamp
  • Last modified by user
  • Change history (audit log)

Toggling Visibility​

Control whether customers can see an FAQ:

  1. Open FAQ
  2. Click Visibility toggle
  3. Choose:
    • Visible to Customers — Appears in customer portal
    • Staff Only — Only visible to support staff
  4. Save changes

Use Cases for Staff-Only:

  • Internal procedures and workflows
  • Troubleshooting guides with sensitive info
  • Draft FAQs awaiting approval
  • Deprecated solutions kept for reference

FAQ Categories​

Standard Categories​

Organize FAQs into logical groups:

  • Account Management — Login, passwords, profiles
  • Billing — Invoices, payments, charges
  • Technical Support — Service issues, troubleshooting
  • Features — How to use specific features
  • Mobile Services — SIM cards, data, roaming
  • Internet Services — Connectivity, speeds, equipment
  • VoIP Services — Calling, voicemail, features
  • IPTV Services — Channels, streaming, devices

Creating Categories​

Categories are created automatically when used in an FAQ. To standardize:

  1. Use consistent category names
  2. Follow naming conventions
  3. Review category list periodically
  4. Merge duplicate/similar categories

Category Management​

View All Categories:

GET /crm/faq/categories

Returns list of all categories with FAQ counts.

Customer View:

GET /crm/faq/customer/categories

Returns only categories with visible FAQs.

Tags​

Purpose​

Tags provide cross-cutting organization:

  • Single FAQ can have multiple tags
  • Tags supplement category structure
  • Enable flexible filtering and search
  • Help customers find related content

Tag Examples​

  • Technical: troubleshooting, error, bug, fix, reset
  • Account: login, password, profile, settings, security
  • Billing: invoice, payment, charge, refund, dispute
  • Service: activation, deactivation, upgrade, change
  • Platform: mobile, web, app, portal, self-care

Best Practices​

  1. Consistent Naming — Use lowercase, singular form
  2. Specific Tags — "password-reset" not just "password"
  3. Avoid Redundancy — Don't duplicate category in tags
  4. Limit Count — 3-5 tags per FAQ
  5. Standardize — Maintain tag glossary

Customer FAQ Portal​

Accessing FAQs​

Customers access FAQs through:

  1. Self-Care Portal — Dedicated FAQ section
  2. During Ticket Creation — "Check these FAQs first" suggestions
  3. Search — Global search includes FAQ content
  4. Email — Links in automated responses

FAQ Display​

Customer view shows:

  • Question — FAQ title/question
  • Answer — Full formatted content
  • Category — For browsing related FAQs
  • Tags — Additional navigation
  • Helpful Rating — Thumbs up/down feedback
  • Related FAQs — Similar questions (future)

Search and Filtering​

Customers can:

  • Search — Full-text search across all visible FAQs
  • Filter by Category — View FAQs in specific category
  • Filter by Tag — Find FAQs with specific tags
  • Sort — By popularity, recency, or alphabetically
  • Browse — Explore all FAQs or category listings

Rating FAQs​

Customers provide feedback:

  1. Read FAQ
  2. Scroll to bottom
  3. Click Was this helpful?
  4. Select Yes or No
  5. Rating recorded

Ratings help identify:

  • Helpful FAQs — High yes votes
  • Needs Improvement — High no votes
  • Outdated Content — Declining helpfulness
  • Popular Topics — High views + high ratings

Staff FAQ Tools​

Internal FAQs​

Staff-only FAQs for:

  • Procedures — Internal workflows and processes
  • Troubleshooting — Advanced diagnostic steps
  • Escalation — When and how to escalate issues
  • Tools — How to use internal systems
  • Policies — Company policies and guidelines

Quick Reference​

Staff can:

  • Search All FAQs — Including staff-only content
  • View Analytics — See which FAQs are most useful
  • Copy Links — Share FAQ links with customers
  • Suggest Edits — Propose improvements to FAQs
  • Create from Ticket — Convert ticket resolution to FAQ

FAQ Analytics​

Track FAQ performance:

View Count:

  • Total views per FAQ
  • Views over time
  • Most popular FAQs
  • Trending FAQs (sudden spikes)

Helpfulness:

  • Helpful votes (thumbs up)
  • Not helpful votes (thumbs down)
  • Helpfulness ratio
  • Most/least helpful FAQs

API Endpoints:

GET /crm/faq/popular?limit=10
GET /crm/faq/helpful?limit=10

Continuous Improvement​

Use analytics to:

  1. Identify Gaps — Common searches with no results
  2. Update Content — Improve low-rated FAQs
  3. Retire Outdated — Remove or update obsolete FAQs
  4. Promote Best — Feature highly-rated FAQs
  5. Create New — Add FAQs for recurring tickets

Markdown Formatting​

FAQ answers support markdown for rich formatting:

Text Formatting​

**Bold text** for emphasis
*Italic text* for subtle emphasis
~~Strikethrough~~ for deprecated info
`inline code` for technical terms

Headers​

## Section Header
### Subsection Header
#### Minor Heading

Lists​

Ordered List:
1. First step
2. Second step
3. Third step

Unordered List:
- Point one
- Point two
- Point three
[Link text](https://example.com)
[Email support](mailto:support@example.com)

Code Blocks​

```bash
command --with-flags
```

```json
&#123;
  "example": "data"
&#125;
```

Images​

<!-- ![Alt text](./image-url.png) -->

Tables​

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

Blockquotes​

> Important note or tip
> Continues on multiple lines

API Reference​

Get All FAQs (Staff)​

GET /crm/faq/

Required Permission: view_faq

Query Parameters:

  • page — Page number (default: 1)
  • per_page — Results per page (default: 20)
  • sort — Sort field (created, view_count, helpful_count)
  • order — Sort order (asc, desc)
  • search — Search query
  • category — Filter by category
  • tags — Filter by tags (comma-separated)
  • is_visible_to_customer — Filter by visibility (true/false)

Get Customer FAQs​

GET /crm/faq/customer

Authentication Required: Yes Permission: Any authenticated user

Returns only customer-visible FAQs.

Get Single FAQ​

GET /crm/faq/faq_id/{faq_id}

Staff View: Does not increment view count

GET /crm/faq/customer/faq_id/{faq_id}

Customer View: Increments view count

Update FAQ​

PATCH /crm/faq/faq_id/{faq_id}

Required Permission: update_faq

Delete FAQ​

DELETE /crm/faq/faq_id/{faq_id}

Required Permission: delete_faq

Performs soft delete (marks as deleted, preserves data).

Toggle Visibility​

POST /crm/faq/faq_id/{faq_id}/visibility

Required Permission: manage_faq_visibility

Request:

{
  "is_visible_to_customer": true
}

Mark FAQ Helpful​

POST /crm/faq/faq_id/{faq_id}/helpful

Authentication Required: Yes Permission: Any authenticated user

Request:

{
  "is_helpful": true
}
GET /crm/faq/popular?limit=10

Returns FAQs sorted by view count.

Get Most Helpful FAQs​

GET /crm/faq/helpful?limit=10

Returns FAQs sorted by helpful count.

Best Practices​

Content Writing​

  1. Clear Questions — Use natural language customers would use
  2. Complete Answers — Include all steps, no assumptions
  3. Screenshots — Add visual aids for complex procedures
  4. Links — Reference related FAQs and resources
  5. Testing — Verify instructions are accurate

Organization​

  1. Consistent Categories — Use standardized category names
  2. Specific Tags — Use descriptive, searchable tags
  3. Avoid Duplication — Merge similar FAQs
  4. Cross-Reference — Link related FAQs together
  5. Regular Review — Update outdated content quarterly

Maintenance​

  1. Monitor Analytics — Track views and helpfulness
  2. Update Regularly — Keep content current
  3. Retire Old FAQs — Remove obsolete information
  4. Incorporate Feedback — Improve based on ratings
  5. Create from Tickets — Turn common issues into FAQs

Troubleshooting​

Issue: FAQ not appearing for customers

  • Solution: Check "Visible to Customers" setting is enabled
  • Solution: Verify FAQ is not marked as deleted
  • Solution: Clear customer portal cache

Issue: Search not finding FAQ

  • Solution: Check spelling and try different keywords
  • Solution: Verify FAQ is in correct category
  • Solution: Add more relevant tags to FAQ

Issue: Analytics not updating

  • Solution: Wait for cache refresh (may take a few minutes)
  • Solution: Check view tracking is enabled
  • Solution: Verify customer is authenticated when viewing

Issue: Cannot edit FAQ

  • Solution: Verify you have update_faq permission
  • Solution: Check FAQ is not locked by another user
  • Solution: Confirm FAQ exists and is not deleted
Last updated on