Papercups — Open-Source Live Customer Chat Widget

Introduction

Papercups is an open-source customer messaging platform built with Elixir and React. It provides an embeddable chat widget for websites, a shared team inbox for managing conversations, and integrations with Slack and other tools so support teams can respond from wherever they work.

What Papercups Does

• Embeds a customizable live chat widget on any website or web application
• Routes customer messages to a shared team inbox with assignment and tagging
• Integrates with Slack so agents can reply to customers directly from Slack channels
• Tracks customer metadata and browsing context alongside conversations
• Provides a REST and WebSocket API for building custom integrations

Architecture Overview

Papercups is built on Elixir and Phoenix with Phoenix Channels for real-time WebSocket communication. The backend stores conversations and customer data in PostgreSQL. The chat widget is a lightweight React component that connects via WebSocket to the Phoenix server. Slack integration uses the Slack Events API to relay messages bidirectionally between Slack channels and the Papercups inbox.

Self-Hosting & Configuration

• Deploy with Docker Compose using the official docker-compose.yml
• Set DATABASE_URL for PostgreSQL and SECRET_KEY_BASE for session encryption
• Configure BACKEND_URL to point the widget to your self-hosted instance
• Connect Slack by creating a Slack app and adding the OAuth credentials
• Customize the widget appearance with color, title, and greeting options

Key Features

• Embeddable chat widget under 50 KB with customizable colors and greeting text
• Real-time messaging via WebSocket with typing indicators and read receipts
• Slack integration for replying to customer chats without leaving Slack
• Customer context sidebar showing page URL, browser, OS, and past conversations
• REST API for programmatic access to conversations, customers, and messages

Comparison with Similar Tools

• Chatwoot — more features including email, social media channels, and chatbots; larger and more complex to deploy
• Intercom — commercial platform with advanced automation and product tours; expensive at scale
• Crisp — freemium hosted chat with chatbot builder; not fully open source
• Tawk.to — free hosted widget; closed source and ad-supported

FAQ

Q: Is Papercups still maintained? A: The core project is stable and functional. Community contributions keep it running, though development pace has slowed since 2022.

Q: Can I use Papercups with React Native or mobile apps? A: Yes, React Native and Flutter SDKs are available for embedding chat in mobile applications.

Q: Does Papercups support chatbots? A: Basic automation rules exist. For advanced chatbots, integrate via the API or webhook events.

Q: What database does Papercups require? A: PostgreSQL is the only supported database backend.

Sources

• https://github.com/papercups-io/papercups
• https://papercups.io/