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. Owly automatically identifies customers across channels -- someone who emails first and later calls gets a unified profile with full conversation history.

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 & Cross-Channel Continuity

Every customer gets a unified profile across all channels -- conversations, notes, tags, and contact history in one place. Owly automatically resolves customer identity when someone switches channels (WhatsApp to Email to Phone), keeping the full context available to both the AI and your team.

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 with OpenAPI 3.0 spec at /api/openapi.json. Interactive documentation with live testing is available at /api-docs in the dashboard. All list endpoints are paginated (max 100/page) with standardized response format.

# Send a message and get AI response
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -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 (database, OpenAI, memory, uptime)
curl http://localhost:3000/api/health
# {"status": "ok", "version": "0.2.1", "services": {"database": "connected", "openai": "reachable"}, ...}

Every API response includes enterprise headers: X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-API-Version.

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)
├── helm/owly/               # Kubernetes Helm chart
│   ├── Chart.yaml
│   ├── values.yaml
│   └── templates/           # K8s manifests (deployment, service, ingress, hpa, etc.)
├── src/
│   ├── app/
│   │   ├── (auth)/          # Login, setup wizard
│   │   ├── (dashboard)/     # 19 dashboard pages
│   │   └── api/             # 60+ REST API endpoints
│   ├── components/
│   │   ├── layout/          # Sidebar, header
│   │   └── ui/              # 12 reusable components
│   └── lib/
│       ├── ai/              # AI engine, tools, types
│       ├── channels/        # WhatsApp, email, phone
│       ├── customer-resolver.ts  # Cross-channel identity resolution
│       ├── errors.ts        # Standardized error responses
│       ├── logger.ts        # Structured logging
│       ├── pagination.ts    # Shared pagination helper
│       ├── rate-limit.ts    # Rate limiting
│       ├── security.ts      # XSS/CRLF protection, secret masking
│       ├── validations.ts   # Zod input schemas
│       ├── webhook-delivery.ts   # Retry logic + HMAC signatures
│       └── hooks/           # Theme hook
├── tests/                   # 228 tests (unit, API, security)
├── docker-compose.yml
├── Dockerfile               # Multi-stage, non-root, healthcheck
└── .env.example

Documentation

Full documentation is available in the Wiki:

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

Deployment

Docker Compose (recommended for most users)

docker compose up -d

Kubernetes (Helm)

helm install owly helm/owly \
  --set database.host=your-postgres-host \
  --set database.password=your-password \
  --set secrets.jwtSecret=$(openssl rand -hex 32) \
  --set secrets.openaiApiKey=sk-... \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=support.yourdomain.com

The Helm chart includes startup/liveness/readiness probes, horizontal pod autoscaling, Ingress with TLS, PersistentVolumeClaim for WhatsApp sessions, and init container for database migrations. See helm/owly/values.yaml for all options.

Roadmap

• Cross-channel customer identity resolution
• Kubernetes Helm chart
• OpenAPI 3.0 specification
• Webhook delivery retry with HMAC signatures
• Pagination on all list endpoints
• Standardized error responses with request tracing
• Embeddable live chat widget for customer websites
• WebSocket real-time updates
• Vector embeddings for semantic knowledge search
• Role-based access control (RBAC)
• Telegram, Instagram, SMS channels
• Shopify / WooCommerce integration
• 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, Enterprise Grade
_{Built with Next.js 16, TypeScript, PostgreSQL, and OpenAI}