Introduction
What Better Helpdesk is, the four pieces it is made of, and how these docs are arranged.
Better Helpdesk is an open-source (MIT) support inbox, ticketing system and lightweight CRM that you install into your own Next.js app as an npm package, better-helpdesk. It is a library, not a service: nothing runs beside your app, and there is no second login, database or deploy to look after. Your customers write in through a widget on your site, your support team answers them from a page inside your app, and every conversation is stored in the database you already run: Postgres, MySQL, SQL Server or SQLite.
In these docs an agent is a member of your support team. It is never an AI. AI is an optional adapter, and what it produces is a suggestion or a draft that an agent reviews.
The pieces
You add four things to your app, and that is the whole installation.
| Piece | What it is | Where it lives |
|---|---|---|
| The handler | One function from Request to Response, built by buildHelpdesk(), that serves every route of the helpdesk | A catch-all route such as app/api/helpdesk/[...slug]/route.ts |
| The agent UI | HelpdeskAdmin, a React component with the inbox, contacts, companies, deals and settings | A page of your app, such as /helpdesk |
| The widget | <helpdesk-widget>, a web component with a React wrapper and a standalone script | Any page of your site, or a site on another origin |
| The tables | The helpdesk's tables, created by better-helpdesk-migrate | Your own database |
Your app keeps the one thing a helpdesk usually takes from you: identity. A function you write, identify(request), reads your own session and says who is asking and whether they are an agent. Better Helpdesk stores no passwords and no sessions.
Everything else is optional and arrives as an adapter you pass in: sending email, receiving it, storing attachments, AI suggestions and drafts, and searching your own help pages. Background work, such as reminders and outgoing mail, runs when your own scheduler calls it. Leave an adapter out and the feature it powers is not there.
Who it is for
Better Helpdesk suits a team that already has a Next.js app with its own login and database, and wants support to live inside that product rather than next to it. It needs Next.js 15 or newer, Node.js 22.19 or newer, React 19, and PostgreSQL 14, MySQL 8.4 or SQL Server 2022 or newer, or SQLite. On another database, you can write your own adapter. Both interfaces ship in English, German, French and Italian. It is not built for support by phone or on social channels, or for a team that wants a hosted tool with its own logins.
Get started
The pages under Get started are the ones every installation needs, and the comparison for deciding whether it fits. Read them in order the first time; after that, you will mostly be in the topics below.
Quickstart
Start from an empty Next.js app and answer your first conversation.
Install in an existing app
Add the handler, the agent UI and the widget to the app you already have.
How it works
Why the package runs inside your app instead of beside it, and what each part does once it is there.
Compared with
Better Helpdesk next to Chatwoot, Libredesk, Intercom and Zendesk, feature by feature.
Vocabulary
The words these docs give a fixed meaning, starting with agent.
Topics
Everything after a working installation is arranged by the part of the helpdesk it concerns, not by the kind of page. Within a topic the tasks come first, then the concepts behind them where a topic has any, then the reference you consult while you work. You don't need to read a topic before you need what it covers.
Database
Connect Postgres, MySQL, SQL Server or SQLite, write an adapter for another database, and report from the tables.
Sign-in and identity
Tell the helpdesk who is asking, from your own session or with a signed token on another origin.
Widget
Put the launcher on your pages, or show a customer their conversations on a page of your app.
Inbox and team
Set up inboxes, add and remove agents, block a sender and store attachments.
Send replies and receipts through your own mail provider, and turn incoming mail into conversations.
AI and help search
Suggestions and draft replies from a language model you connect, and articles from your own documentation while a customer types.
Your app and CRM
Call the helpdesk from your server code, run your own code on its events, and track companies and deals.
Theming and languages
Your colors, corners and dark mode, and the wording in English, German, French and Italian.
Operations
Go to production, schedule the jobs, move over from another helpdesk, and read what the helpdesk defends against.
Reference
Every option of HelpdeskConfig, every adapter interface, route and package export.