Opencom

Open-source customer messaging platform - an alternative to Intercom.

Documentation

Quick Links

| Document | Description | | ------------------------------------------------------------------------ | -------------------------------------------- | | Contributing Guide | Development setup, code style, PR guidelines | | OSS Documentation Hub | Canonical hub for all documentation | | Architecture & Repo Map | System topology and code navigation | | Setup & Deploy | Self-hosting and deployment paths |

Reference

| Document | Description | | ------------------------------------ | -------------------------------------------------------------- | | Data Model | Complete database schema reference (50+ tables) | | Backend API | Convex queries, mutations, and actions | | Widget SDK | Embeddable widget client-side API | | Mobile SDKs | React Native, iOS (Swift), Android (Kotlin) SDK guides | | Security | RBAC, HMAC identity verification, audit logs, webhook security | | Testing | Unit, integration, E2E testing guide and CI pipeline | | Scripts | Build, deploy, security, and utility script reference |

Contributor Workflow

| Document | Description | | ---------------------------------------------------------------------- | ------------------------------------------------- | | Testing & Verification | Verification workflows for contributors | | Security & Operations | Security boundaries and operational readiness | | Source-of-Truth Contract | Documentation ownership and update rules | | Feature Audit | Comprehensive feature inventory and test coverage |

Features

• Chat - Real-time messaging with customers via embeddable widget and email channel
• Product Tours - Guide users through your product with WYSIWYG editor
• Knowledge Base - Self-service help center with collections and articles
• Mobile Apps - iOS and Android admin apps for on-the-go support with push notifications
• Campaigns - Targeted outbound messaging with audience rules and trigger conditions
• Series - Multi-step automated message sequences
• Surveys - In-app surveys (NPS, rating, text, multiple choice) with analytics
• Tickets - Issue tracking with priority, status, and agent assignment
• Segments - Dynamic visitor grouping by attributes and behavior
• Reports - Analytics dashboards for conversations, response times, and satisfaction
• AI Agent - Automated responses using knowledge base with confidence scoring and human handoff
• Email Channel - Send and receive emails as conversations via Resend integration
• Tooltips - Contextual UI hints attached to page elements
• Outbound Messages - Chat, post, and banner messages with trigger conditions
• Checklists - Onboarding task lists for visitors
• Carousels - Multi-screen promotional content for mobile SDKs
• CSAT - Customer satisfaction ratings on conversations
• Identity Verification - HMAC-based visitor identity verification
• Native SDKs - React Native, iOS (Swift), and Android (Kotlin) SDKs

Tech Stack

• Frontend: React, Next.js, Tailwind CSS, Shadcn UI
• Mobile: React Native / Expo
• Backend: Convex (serverless)
• Package Manager: PNPM

Project Structure

opencom/
├── apps/
│   ├── web/              # Next.js dashboard for agents/admins
│   ├── mobile/           # Expo app for iOS/Android (Admin App)
│   ├── widget/           # Embeddable chat widget for websites (Vite)
│   └── landing/          # Next.js marketing/landing page
├── packages/
│   ├── convex/           # Convex schema and functions (backend)
│   ├── types/            # Shared TypeScript types
│   ├── ui/               # Shared React components
│   ├── sdk-core/         # Shared SDK business logic
│   ├── react-native-sdk/ # React Native SDK for customer apps
│   ├── ios-sdk/          # Native iOS SDK (Swift, SPM + CocoaPods)
│   └── android-sdk/      # Native Android SDK (Kotlin)
└── openspec/             # Reserved structure for future spec workflows

App Naming Convention

| App | Purpose | Location | Users | | ----------------- | --------------------------------------------------------- | --------------------------- | -------------------------- | | Admin App | Agent/teammate mobile app for responding to conversations | apps/mobile | Support agents | | Mobile SDK | Embeddable SDK for customer mobile apps | packages/react-native-sdk | End users of customer apps | | Web Widget | Embeddable widget for customer websites | apps/widget | Website visitors | | Web Dashboard | Admin dashboard for managing workspace | apps/web | Admins and agents | | Landing Page | Marketing website | apps/landing | Public visitors |

Getting Started

For the canonical setup paths (quickstart, self-host, env vars, deployment profiles), use: docs/open-source/setup-self-host-and-deploy.md

Quick Start (Self-Hosters)

The fastest way to get Opencom running locally:

# Clone the repository
git clone https://github.com/opencom-org/opencom.git
cd opencom

# Run the setup script
./scripts/setup.sh

The setup script will:

1. Check prerequisites (Node.js 18+, PNPM 9+)
2. Install dependencies
3. Create a Convex project and deploy
4. Prompt for your admin email and password
5. Create your workspace and admin account
6. Generate all .env.local files
7. Start the web dashboard and widget

Prerequisites:

• Node.js 18+
• PNPM 9+ (npm install -g pnpm)
• Convex account (free at convex.dev)

Non-interactive mode (for CI/scripts):

./scripts/setup.sh --email admin@example.com --password yourpassword --non-interactive --skip-dev

Update environment files:

./scripts/update-env.sh --url https://your-project.convex.cloud --workspace your_workspace_id

Manual Setup

If you prefer manual setup:

# Install dependencies
pnpm install

# Navigate to convex package
cd packages/convex

# Login to Convex
npx convex login

# Initialize and deploy
npx convex dev

Then create .env.local files manually (see Environment Variables Reference below).

Development

# Start all apps
pnpm dev

# Start specific app
pnpm dev:web      # Next.js dashboard
pnpm dev:mobile   # Expo mobile app
pnpm dev:widget   # Widget dev server
pnpm dev:convex   # Convex backend

# Build all apps
pnpm build

# Lint
pnpm lint

# Format
pnpm format

Deployment Options

Opencom supports multiple deployment configurations depending on your needs:

| Option | Backend | Web App | Mobile Apps | Best For | | ------ | ----------- | ----------- | ----------- | ------------------------------ | | A | Hosted | Hosted | Hosted | Quick start, no infrastructure | | B | Self-hosted | Hosted | Hosted | Data control with hosted apps | | C | Self-hosted | Self-hosted | Hosted | Full web control | | D | Self-hosted | Self-hosted | Self-hosted | Complete self-hosting |

Option A: Fully Hosted (Recommended for Getting Started)

The simplest way to use Opencom:

1. Sign up at app.opencom.dev
2. Create a workspace
3. Copy the widget snippet from Settings → Widget Installation
4. Add the snippet to your website

No infrastructure setup required. Your data is stored on the default Opencom Convex instance.

Option B: Self-Hosted Backend with Hosted Apps

Control your data while using the hosted web and mobile apps.

1. Create a Convex project:

# Clone the repository
git clone https://github.com/opencom-org/opencom.git
cd opencom

# Install dependencies
pnpm install

# Navigate to convex package
cd packages/convex

# Login to Convex
npx convex login

# Create and deploy your project
npx convex dev --once

2. Configure environment variables in Convex Dashboard:

Go to your Convex dashboard → Settings → Environment Variables and set:

| Variable | Required | Description | | ---------------- | --------- | ------------------------------------------------------------------------ | | AUTH_SECRET | Yes | Random string for JWT signing (generate with openssl rand -base64 32) | | RESEND_API_KEY | For email | API key from Resend for sending emails | | EMAIL_FROM | For email | Email address to send from (e.g., YourCompany<noreply@yourdomain.com>) |

3. Connect hosted apps to your backend:

• Web: Go to [app.opencom.dev](https://