owly

AI-powered customer support agent with WhatsApp, Email & Phone channels

Automatically checked · GitHub checked 2026-11-12

owly

Before you switch

Evaluate hosting, migration and feature requirements before switching.

Overview

Owly

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

CI License Version Tests Helm Node TypeScript Next.js PostgreSQL PRs Welcome

Owly Demo


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.


Zero Cost
No monthly fees. You only pay
for AI API usage.



Your Data, Your Server
Everything runs on your machine.
Complete privacy.



Multi-Channel
WhatsApp, Email, and Phone
from a single dashboard.



5-Minute Setup
Docker Compose or npm.
Guided setup wizard.



Features

Multi-Channel Support

Connect all your customer communication channels in one place.

WhatsApp

Connect via QR code scan or Business API. Handles text, images, voice messages, and documents.

Email

IMAP/SMTP with any provider. Branded HTML templates with automatic thread tracking.

Phone

Twilio Voice with OpenAI Whisper (STT) and ElevenLabs (TTS) for natural voice conversations.

Channel Management
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

Conversations
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 Management
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.

Knowledge Base Categories
Categories with entry counts and color coding
Knowledge Base Entries
Entries with priority levels and active toggles

Automation Engine

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

Automation Rules
Auto-route, auto-tag, auto-reply, keyword alerts
Canned Responses
Quick reply templates with shortcuts
Business Hours
Weekly schedule with timezone and offline messages
SLA Rules
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.

Team Management
Departments, members, expertise, and availability
Ticket System
Priority levels, assignments, and status tracking

Analytics & Insights

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

Analytics Dashboard
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.

Administration
Multi-admin with roles and API key management
API Documentation
Interactive API docs with live request testing

Dark Mode

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

Dark Mode
Dark mode dashboard with consistent styling across all components

More Features

Settings
6-tab settings: General, AI, Voice, Phone, Email, WhatsApp
Webhooks
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.

Login Page
Clean login page with Owly branding


Configuration

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

SettingLocationDescription
Business profileSettings > GeneralName, description, welcome message, tone
AI providerSettings > AI ConfigurationOpenAI / Claude / Ollama, model, API key
VoiceSettings > VoiceElevenLabs API key and voice selection
PhoneSettings > PhoneTwilio Account SID, auth token, phone number
EmailSettings > EmailSMTP and IMAP server configuration
WhatsAppChannels > WhatsAppQR code scan or Business API
TeamTeamDepartments, members, expertise areas
SLASLA RulesResponse and resolution time targets
ScheduleBusiness HoursWeekly availability and offline messages
AutomationAutomationAuto-route, auto-tag, auto-reply rules
TemplatesCanned ResponsesPre-written reply templates
IntegrationsWebhooksExternal service connections

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.

View all endpoints
MethodEndpointDescription
POST/api/chatSend message, get AI response
GET POST/api/conversationsList or create conversations
GET PUT DELETE/api/conversations/:idManage a conversation
POST/api/conversations/:id/messagesAdd message (admin takeover)
POST/api/conversations/:id/satisfactionRate conversation (1-5)
POST/api/conversations/:id/notesAdd internal note
GET POST/api/customersList or create customers
GET PUT DELETE/api/customers/:idManage a customer
GET/api/customers/:id/conversationsCross-channel conversation timeline
GET POST/api/ticketsList or create tickets
GET PUT DELETE/api/tickets/:idManage a ticket
GET POST/api/knowledge/categoriesKnowledge categories
GET POST/api/knowledge/entriesKnowledge entries
POST/api/knowledge/testTest AI with a question
GET PUT/api/settingsApplication settings
GET/api/analytics?period=7dAnalytics data
GET/api/export?type=conversations&format=csvExport (CSV/JSON)
GET POST/api/automationAutomation rules
GET PUT/api/business-hoursBusiness hours config
GET POST/api/slaSLA rules
GET POST/api/canned-responsesCanned responses
GET POST/api/webhooksWebhook management
POST/api/webhooks/testTest a webhook
GET POST/api/webhooks/:id/deliveriesDelivery log and retry
GET POST/api/admin/usersAdmin user management
GET POST/api/admin/api-keysAPI key management
GET/api/activityActivity audit log
GET/api/healthHealth check
GET/api/openapi.jsonOpenAPI 3.0 specification

Tech Stack

LayerTechnology
FrameworkNext.js 16 (App Router)
LanguageTypeScript 5
DatabasePostgreSQL 16 + Prisma 7
UITailwind CSS 4 + Radix UI
AIOpenAI GPT (extensible to Claude, Ollama)
Voice TTSElevenLabs
Voice STTOpenAI Whisper
PhoneTwilio Voice API
WhatsAppwhatsapp-web.js
AuthJWT + bcrypt (12 rounds)
ValidationZod schemas on all endpoints
TestingVitest (274 tests)
ChartsPure CSS/SVG (zero dependencies)
DeploymentDocker Compose / Kubernetes (Helm)

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:


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
Owly -- AI Customer Support, Enterprise Grade
Built with Next.js 16, TypeScript, PostgreSQL, and OpenAI