rest api-driven request lifecycle management with department routing
Tiledesk exposes a comprehensive REST API built on Express.js that manages the full lifecycle of customer support requests (tickets) from creation through closure. The system implements configurable department-based routing logic that automatically assigns incoming requests to appropriate departments based on rules, availability, and skill matching. Request state transitions (open → assigned → closed) are tracked in MongoDB with real-time WebSocket notifications to connected agents, enabling synchronous multi-agent awareness of request status changes without polling.
Unique: Combines REST API for CRUD operations with WebSocket event streaming for real-time request state synchronization across agents, using MongoDB as the single source of truth and dependency injection to share routing logic across services
vs alternatives: Tighter real-time synchronization than REST-only systems like Zendesk API, with lower latency than polling-based alternatives due to native WebSocket integration in the core request service
multi-channel message routing and persistence with chat21 integration
Tiledesk implements a message handling layer that abstracts multiple communication channels (web chat, WhatsApp, Telegram, Facebook Messenger) through a unified message model stored in MongoDB. Messages are routed through the Chat21 integration layer, which normalizes incoming messages from different channels into a standard format, persists them with full conversation history, and broadcasts them to connected agents via WebSocket. The system maintains channel-specific metadata (phone numbers, user IDs, platform-specific fields) while presenting a unified conversation interface to support agents.
Unique: Uses Chat21 as a dedicated message normalization layer that abstracts channel-specific protocols, allowing Tiledesk to remain channel-agnostic while maintaining full conversation history in a single MongoDB collection with channel metadata preserved for audit and compliance
vs alternatives: More modular than monolithic platforms like Intercom (which embed channel logic), allowing independent Chat21 updates without Tiledesk server changes; simpler than building custom channel adapters for each platform
system services and background job execution with event-driven triggers
Tiledesk implements a system services layer that executes background jobs triggered by internal events or scheduled intervals. Services include request cleanup (archiving old closed requests), email digest generation, webhook retry processing, and knowledge base indexing. Services are implemented as Node.js modules that subscribe to events (via EventEmitter or RabbitMQ) or run on schedules (via node-cron or similar). Services are decoupled from the main request processing path, allowing long-running operations to complete without blocking API responses. The system maintains a service registry that tracks which services are running and their health status, enabling monitoring and restart capabilities.
Unique: Services are decoupled from request processing using event-driven architecture, allowing long-running operations to complete asynchronously; services can be triggered by events (request closed) or schedules (daily at midnight), with optional RabbitMQ for distributed execution
vs alternatives: Simpler than external job queues like Bull or Celery (no separate infrastructure), more flexible than cron-only scheduling (event-driven triggers), and more integrated than webhook-based job processing (native event system)
docker containerization with environment-based configuration
Tiledesk provides a Dockerfile and Docker Compose configuration for containerized deployment. The Docker image includes Node.js 16.17.0, all npm dependencies, and the Tiledesk application code. Configuration is managed through environment variables (loaded from .env file or Docker secrets), allowing the same image to be deployed across development, staging, and production without rebuilding. The Dockerfile supports both standalone deployment (with embedded MongoDB) and integration with external MongoDB and Redis instances. Docker Compose templates are provided for quick local development with MongoDB and Redis services pre-configured.
Unique: Dockerfile uses environment-based configuration (no hardcoded values), allowing the same image to be deployed across environments; Docker Compose templates provide quick local setup with MongoDB and Redis pre-configured, reducing onboarding friction
vs alternatives: More portable than source-based deployment (no dependency on local Node.js version), more flexible than hardcoded Docker images (environment-based config), and more convenient than manual Docker setup (Compose templates included)
jwt and passport.js-based authentication with role-based access control
Tiledesk implements a multi-strategy authentication system using Passport.js that supports JWT tokens, basic authentication, and OAuth (including Google OAuth). The system validates credentials against MongoDB user records and issues JWT tokens for stateless API access. Role-based access control (RBAC) is enforced at the middleware level, with roles including admin, agent, and guest, combined with project-level permissions to create fine-grained authorization rules. Each protected route checks both the user's role and their project membership before allowing access.
Unique: Combines Passport.js strategy pattern with project-level permission scoping, allowing a single user to have different roles across multiple projects; JWT tokens are signed with a server secret and validated on every request without database lookups, reducing auth latency
vs alternatives: More flexible than API-key-only systems (supports OAuth for SSO), more scalable than session-based auth (no server-side session storage), and more granular than simple role-based systems due to project-level permission isolation
faq and general knowledge base retrieval with semantic search integration
Tiledesk provides a dual knowledge base system: FAQ knowledge bases (structured Q&A pairs) and general knowledge bases (unstructured documents). Both are stored in MongoDB and indexed for retrieval. The system integrates with retrieval-augmented generation (RAG) capabilities, allowing bots and agents to query knowledge bases semantically to find relevant answers before responding to customers. Knowledge base entries are tagged, categorized, and versioned, with support for enabling/disabling entries without deletion. The retrieval layer supports both keyword matching and semantic similarity (via embeddings) to find the most relevant knowledge base articles.
Unique: Separates FAQ (structured Q&A) from general knowledge bases (unstructured documents) in MongoDB, allowing different retrieval strategies for each; integrates with RAG pipelines by exposing knowledge base queries as a service that bots can call during response generation
vs alternatives: More flexible than static FAQ lists (supports semantic search and versioning), more lightweight than dedicated vector databases like Pinecone (uses MongoDB for storage), and more integrated than external knowledge base tools (native to Tiledesk API)
bot handler execution with llm integration and context injection
Tiledesk implements a bot handler system that executes custom bot logic in response to incoming messages. Bot handlers are JavaScript functions that receive the full request context (customer message, conversation history, request metadata) and can call external LLMs (OpenAI, Anthropic, etc.) or execute custom logic. The system injects context from the request (customer name, department, previous messages) into the bot handler, allowing bots to make context-aware decisions. Bot handlers can query knowledge bases, call external APIs, or escalate to human agents based on custom conditions. The execution is asynchronous and supports timeout handling to prevent hung bots from blocking request processing.
Unique: Bot handlers receive full request context (conversation history, customer metadata, department info) injected at execution time, allowing bots to make decisions based on conversation state without explicit context passing; handlers are JavaScript functions deployed to the server, enabling rapid iteration without separate bot deployment infrastructure
vs alternatives: Tighter integration with request context than webhook-based bot systems (no HTTP round-trip latency), more flexible than template-based bots (supports arbitrary JavaScript logic), and simpler than agent frameworks like LangChain (no framework overhead, just functions)
real-time websocket communication with event-driven message broadcasting
Tiledesk uses WebSockets (via Socket.io or native WebSocket) to enable real-time bidirectional communication between the server and connected clients (agents, customers, dashboards). The system implements an event-driven architecture where message events, request state changes, and agent status updates are broadcast to all subscribed clients. Events are published through a central event emitter (Node.js EventEmitter or RabbitMQ if configured), and clients subscribe to specific event channels (e.g., 'request:123:message', 'agent:status'). The WebSocket layer maintains a registry of connected clients and their subscriptions, allowing selective broadcasting to avoid flooding all clients with irrelevant events.
Unique: Implements event-driven broadcasting where clients subscribe to specific event channels (request-scoped, agent-scoped) rather than receiving all events, reducing bandwidth and latency; uses Node.js EventEmitter for single-instance deployments with optional RabbitMQ for horizontal scaling
vs alternatives: Lower latency than polling-based REST APIs (no request/response overhead), more selective than broadcast-all systems (channel-based subscriptions), and more scalable than in-memory event emitters (RabbitMQ integration for multi-instance deployments)
+4 more capabilities