# Introduction

URL: https://better-helpdesk.com/docs/

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 [#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 [#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](/docs/database/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 [#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.

<Cards>
  <Card title="Quickstart" href="/docs/quickstart">
    Start from an empty Next.js app and answer your first conversation.
  </Card>

  <Card title="Install in an existing app" href="/docs/installation">
    Add the handler, the agent UI and the widget to the app you already have.
  </Card>

  <Card title="How it works" href="/docs/how-it-works">
    Why the package runs inside your app instead of beside it, and what each part does once it is there.
  </Card>

  <Card title="Compared with" href="/docs/compared">
    Better Helpdesk next to Chatwoot, Libredesk, Intercom and Zendesk, feature by feature.
  </Card>

  <Card title="Vocabulary" href="/docs/vocabulary">
    The words these docs give a fixed meaning, starting with *agent*.
  </Card>
</Cards>

## Topics [#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.

<Cards>
  <Card title="Database" href="/docs/database/connect">
    Connect Postgres, MySQL, SQL Server or SQLite, write an adapter for another database, and report from the tables.
  </Card>

  <Card title="Sign-in and identity" href="/docs/identity/sign-in">
    Tell the helpdesk who is asking, from your own session or with a signed token on another origin.
  </Card>

  <Card title="Widget" href="/docs/widget/add">
    Put the launcher on your pages, or show a customer their conversations on a page of your app.
  </Card>

  <Card title="Inbox and team" href="/docs/inbox/setup">
    Set up inboxes, add and remove agents, block a sender and store attachments.
  </Card>

  <Card title="Email" href="/docs/email/send">
    Send replies and receipts through your own mail provider, and turn incoming mail into conversations.
  </Card>

  <Card title="AI and help search" href="/docs/ai/suggestions">
    Suggestions and draft replies from a language model you connect, and articles from your own documentation while a customer types.
  </Card>

  <Card title="Your app and CRM" href="/docs/app/own-code">
    Call the helpdesk from your server code, run your own code on its events, and track companies and deals.
  </Card>

  <Card title="Theming and languages" href="/docs/customize/theming">
    Your colors, corners and dark mode, and the wording in English, German, French and Italian.
  </Card>

  <Card title="Operations" href="/docs/operations/production">
    Go to production, schedule the jobs, move over from another helpdesk, and read what the helpdesk defends against.
  </Card>

  <Card title="Reference" href="/docs/reference/configuration">
    Every option of `HelpdeskConfig`, every adapter interface, route and package export.
  </Card>
</Cards>