owly

Features · Screenshots · Quick Start · Configuration · API · Tech Stack · Wiki · Roadmap

What is Owly?

Owly is a self-hosted AI customer support agent that small businesses and individuals can run on their own machines -- completely free. Connect your WhatsApp, Email, and Phone channels, add your business knowledge, and let the AI handle customer inquiries 24/7.

Features

Multi-Channel Support

Connect all your customer communication channels in one place.

Connect and manage all channels from one screen

AI-Powered Conversations

Owly uses OpenAI GPT (extensible to Claude, Ollama) with your knowledge base to provide accurate, on-brand responses. During conversations, the AI can autonomously:

• Create tickets when customers report problems
• Route issues to the right department based on expertise matching
• Send internal emails to notify team members about urgent issues
• Look up customer history for context-aware support
• Trigger webhooks to notify external systems
• Schedule follow-ups for proactive customer care

Unified inbox with conversation thread and admin takeover

Customer CRM

Every customer gets a unified profile across all channels -- conversations, notes, tags, and contact history in one place.

Customer profiles with notes, tags, and cross-channel history

Knowledge Base

Train your AI with your business information. Organize entries into categories, set priorities, and test responses before going live.

Categories with entry counts and color coding

Entries with priority levels and active toggles

Automation Engine

Automate repetitive tasks with rule-based automation, business hours, SLA tracking, and canned responses.

Auto-route, auto-tag, auto-reply, keyword alerts

Quick reply templates with shortcuts

Weekly schedule with timezone and offline messages

Response time targets per channel and priority

Team & Ticket Management

Organize your team into departments, track issues with a full ticket system, and monitor performance.

Departments, members, expertise, and availability

Priority levels, assignments, and status tracking

Analytics & Insights

Monitor your support performance with charts, metrics, and team performance tracking.

Conversation trends, channel breakdown, ticket distribution, and satisfaction scores

Administration & API

Manage users, API keys, webhooks, and explore the full REST API with interactive documentation.

Multi-admin with roles and API key management

Interactive API docs with live request testing

Dark Mode

Full dark theme with persistent preference, applied across all 19 pages.

Dark mode dashboard with consistent styling across all components

More Features

6-tab settings: General, AI, Voice, Phone, Email, WhatsApp

Webhook management with payload preview and testing

Quick Start

Prerequisites

• Node.js 20+
• PostgreSQL 16+

Option 1: npm

# Clone the repository
git clone https://github.com/hsperus/owly.git
cd owly

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your database URL and API keys

# Run database migrations
npx prisma migrate dev

# (Optional) Load sample data with a default admin account
npm run db:seed
# Default login: username=admin, password=admin123

# Start the development server
npm run dev

Option 2: Docker Compose

git clone https://github.com/hsperus/owly.git
cd owly

cp .env.example .env
# Edit .env with your API keys

docker compose up -d

Open http://localhost:3000 -- the setup wizard will guide you through the initial configuration.

Clean login page with Owly branding

Configuration

All configuration is done through the admin dashboard -- no config files to edit after initial setup:

API

Owly provides a full REST API. Interactive documentation with live testing is available at /api-docs in the dashboard.

# Send a message and get AI response
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"message": "What are your business hours?", "channel": "api"}'

# Response:
# {"conversationId": "...", "response": "We are open Monday to Friday, 9 AM to 6 PM..."}

# Health check
curl http://localhost:3000/api/health
# {"status": "ok", "version": "0.1.0", "database": "connected"}

Tech Stack

Project Structure

owly/
├── prisma/                  # Database schema, migrations, seed
├── public/                  # Static assets (logo)
├── docs/
│   ├── screenshots/         # UI screenshots (20 images)
│   └── wiki/                # Full documentation (25 pages)
├── src/
│   ├── app/
│   │   ├── (auth)/          # Login, setup wizard
│   │   ├── (dashboard)/     # 19 dashboard pages
│   │   └── api/             # 55+ REST API endpoints
│   ├── components/
│   │   ├── layout/          # Sidebar, header
│   │   └── ui/              # 12 reusable components
│   └── lib/
│       ├── ai/              # AI engine, tools, types
│       ├── channels/        # WhatsApp, email, phone
│       └── hooks/           # Theme hook
├── docker-compose.yml
├── Dockerfile
└── .env.example

Documentation

Full documentation is available in the Wiki:

• Installation Guide
• Setup Wizard
• Quick Start Tutorial
• API Reference
• AI Tool System
• Architecture

Roadmap

• Embeddable live chat widget for customer websites
• WebSocket real-time updates
• Vector embeddings for semantic knowledge search
• Visual AI tool builder
• Public knowledge base (self-service)
• Customer self-service portal
• Visual workflow builder
• Telegram, Instagram, SMS channels
• Shopify / WooCommerce integration
• Sentiment analysis
• Mobile admin (PWA)
• Multi-tenant / white-label

Contributing

Contributions are welcome! See the Contributing Guide for details.

# Fork, clone, and create a branch
git checkout -b feature/your-feature

# Make changes and commit
git commit -m 'feat: add your feature'

# Push and open a PR
git push origin feature/your-feature

License

MIT License - see LICENSE for details.

Owly -- AI Customer Support, Made Simple
_{Built with Next.js, TypeScript, and PostgreSQL}