# Papercups — Open-Source Live Customer Chat Widget

> A self-hosted, open-source customer messaging platform with an embeddable chat widget, real-time Slack integration, and a shared inbox for support teams.

## Install

Save in your project root:

# Papercups — Open-Source Live Customer Chat Widget

## Quick Use
```html
<!-- Add the chat widget to your site -->
<script>
  window.Papercups = {
    config: {
      accountId: "your-account-id",
      title: "Welcome!",
      subtitle: "Ask us anything.",
      primaryColor: "#1890ff",
      baseUrl: "https://app.papercups.io"
    }
  };
</script>
<script async src="https://app.papercups.io/widget.js"></script>
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-84dfc852
Author: AI Open Source