@byo-oss/support
v0.5.0
Published
A better-auth plugin for customer support: tickets, replies and attachments in your own database.
Maintainers
Readme
@byo-oss/support
Customer support for better-auth apps: tickets, replies, internal notes, canned replies and attachments in your database, an in-app widget for customers and an inbox for your staff, and email in and out when you want it.
Community plugin — not affiliated with the better-auth team.
npm install @byo-oss/support- Your users, your organizations, your permissions. Tickets belong to better-auth users. A customer can share a ticket with their organization. Your staff are members of one organization you choose, with roles you control through better-auth's access control.
- One plugin, one migration, two components.
SupportWidgetfor customers,SupportInboxfor agents, both on headless hooks you can use instead. - Email when you want it. Agent replies are mailed to the requester through a
Mailer(Wraps on your own AWS SES account, or your own). Mail sent to your support address opens or continues a ticket, with an aligned-DKIM check. - Events, not a notification system. Every change emits an event; route them to staff and customers through
@byo-oss/notificationsor anything else. - A way out.
exportSupportData, a documented schema and a clean uninstall are part of the package. See Outgrowing this.
Install
npm install @byo-oss/supportRequires Node 20.18.1 or newer, better-auth ^1.7.16 (1.6 is not supported: its plugin API differs), @better-auth/core at the same version as better-auth (better-auth already depends on it; install it yourself when your package manager is strict about peers) and zod ^4.6.6. zod is a peer dependency, so support validates with your app's copy instead of bringing its own; npm and pnpm install it when your app doesn't list it (better-auth already depends on zod 4), and with Yarn you add it yourself. An app on zod older than 4.6.6 (zod 3 included) has to move to 4.6.6 or later first (npm stops with ERESOLVE). The better-auth organization plugin is required: the schema references organization, and your staff are an organization's members.
Optional peers, each behind its own import so the root never loads them:
| Package | Needed for |
|---|---|
| react (>=18) | @byo-oss/support/react |
| @wraps.dev/email | wrapsMailer from @byo-oss/support/wraps |
| @aws-sdk/client-s3 | s3Storage from @byo-oss/support/s3, and wrapsInbound |
| vitest (^4.1.12 || >=5.0.3) | @byo-oss/support/testing (ESM only) |
In a monorepo, add @byo-oss/support as a direct dependency of the web app's package (not only of a shared server package): the app imports @byo-oss/support/react, and Tailwind's @source path points into that package's node_modules.
The Mailer type comes from @byo-oss/mailer, which is a dependency of this package. Install it yourself if you import memoryMailer or PermanentMailError from it.
Setup
Five steps give you customers opening and following tickets (in-app, with polling) and agents working one queue: reply or leave a note, set status, priority, assignee and tags, in bulk. Email, inbound mail and attachments are add-ons further down.
Add the plugins.
organization()must come beforesupport(): migrations create tables in plugin order, andsupportTicketreferencesorganization. Create one organization for your team (the staff organization; see Seed the staff organization) and pass its id:// lib/auth.ts import { betterAuth } from "better-auth"; import { organization } from "better-auth/plugins/organization"; import { support } from "@byo-oss/support"; import { ac, roles } from "./access"; // step 2 export const auth = betterAuth({ // ...your existing config plugins: [ organization({ ac, roles }), // before support() support({ staffOrganizationId: process.env.SUPPORT_STAFF_ORGANIZATION_ID }), ], });Without
staffOrganizationId(and without your ownauthorize), every agent endpoint denies and the server logs one warning at boot. PassstaffOrganizationId: nullto run without agents on purpose (no warning). If the id is only known after boot, pass a function,() => id | null | undefined: it is called on every request that needs it.Grant staff the
supportactions. The organization plugin's default roles have none. SpreadsupportStatementsinto your access control and addsupportRolesto the roles you create. Import both from@byo-oss/support/client: access files are often shared with browser code, and that entry loads none of the server's mail parsing (the root exports them too). Agents are members of the staff organization whose role has them; a customer organization's owner is never an agent.// lib/access.ts import { createAccessControl } from "better-auth/plugins/access"; import { adminAc, defaultStatements, memberAc, ownerAc, } from "better-auth/plugins/organization/access"; import { supportRoles, supportStatements } from "@byo-oss/support/client"; export const ac = createAccessControl({ ...defaultStatements, ...supportStatements }); export const roles = { owner: ac.newRole({ ...ownerAc.statements, ...supportRoles.owner }), admin: ac.newRole({ ...adminAc.statements, ...supportRoles.admin }), member: ac.newRole({ ...memberAc.statements, ...supportRoles.member }), };supporthas five actions:read(the queue and any ticket),reply(agent replies and notes),update(status, priority, assignee, tags, bulk update, merge),manage(canned replies) anddelete(delete tickets).supportRolessuggestsownerandadminget all five andmembergetsread,replyandupdate; grant each role, custom roles included, only the actions its staff need. Roles apply in every organization, but support checks them only in the staff organization, so only that organization's members become agents: a customer organization'sownerholdingsupportactions in its own organization changes nothing. Support checks permissions, never role names.Run the migration. The plugin declares its tables; your existing better-auth workflow creates them:
npx @better-auth/cli migrate # or: generate, for drizzle/prismaIf your framework's auth config can't be loaded by the CLI, run the same migration from code with
getMigrationsfrombetter-auth/db/migration:import { getMigrations } from "better-auth/db/migration"; import { auth } from "./lib/auth"; const { runMigrations } = await getMigrations(auth.options); await runMigrations();It adds
supportTicket,supportCounter,supportTicketTag,supportMessageandsupportCannedReply, plussupportDeliveryonce you setmailerandsupportAttachmentonce you setattachments(run it again after you turn those on). Nothing is added touser,organizationormember.Because those two tables follow the options, a generated schema (drizzle or prisma through the better-auth CLI) only has them if the auth config the CLI loads passes
mailerandattachmentsthe way production does; a CLI-only config without them generates a schema that lacks them. No support table references itself, so the generated drizzle schema typechecks understrict.Add the client plugin:
// lib/auth-client.ts import { createAuthClient } from "better-auth/react"; import { supportClient } from "@byo-oss/support/client"; export const authClient = createAuthClient({ plugins: [supportClient()], });Render the components. The widget goes at the right end of your header, for signed-in customers; the inbox goes on a staff-only page:
"use client"; import { SupportInbox, SupportWidget } from "@byo-oss/support/react"; import { useRouter } from "next/navigation"; import { authClient } from "@/lib/auth-client"; export function HeaderSupport({ organizationId }: { organizationId?: string }) { const router = useRouter(); // organizationId: the customer's active organization, so tickets can be shared with teammates return ( <SupportWidget client={authClient} organizationId={organizationId} onNavigate={(href) => router.push(href)} /> ); } export function StaffQueue({ agents }: { agents: { id: string; name: string; image?: string | null }[] }) { const router = useRouter(); // agents: staff-organization members whose role grants support:read, for the assignee and @mention pickers return <SupportInbox client={authClient} agents={agents} onNavigate={(href) => router.push(href)} />; }onNavigatetakes your router:router.push(href)as above, ornavigate({ href })with TanStack Router. Without it, links to your app inside messages uselocation.assign. Buildagentsfrom the staff organization's members whose role grantssupport: ["read"], on the server or in the browser (see Staff list).Tailwind v4 skips
node_moduleswhen it scans for classes, so point it at the package or some classes won't be generated (see Tailwind). Polling pauses while the tab is hidden (see Polling for the cost), and every string has alabelsoverride. The widget is a popover for your header; for a page of its own, and for email and notification links, see Components.
Server code can open a ticket without the widget too: await auth.api.createSupportTicket({ headers, body: { subject, body } }).
For a complete, runnable wiring, see the example app in examples/tanstack-start: TanStack Start with better-auth on SQLite and an end-to-end suite. Run it with pnpm install, pnpm migrate, pnpm seed and pnpm dev from that directory (Node 22.13 or newer); its README has the details and the sign-ins.
For coding agents
AGENTS.md has the install steps, rules and repo conventions, and llms.txt is the full usage reference. The same setup, with a check after each step, ships as a skill: skills/support-setup/SKILL.md.
Options
support(options). Every option is optional; with none, nothing sends or receives email and nothing is stored outside your database.
| Option | Type | Default | Notes |
|---|---|---|---|
| staffOrganizationId | string | null | () => string \| null \| undefined | | The vendor's staff organization. Agents are its members whose role has support actions. A function is called on every request that needs the id (the default authorize and isAgent, and the staff check when a member leaves); it must be synchronous and must not throw (an async function is refused at boot; a function that throws or returns anything but a string, null or undefined, such as a Promise, counts as no staff organization and is logged once). null: no agents, on purpose (a custom authorize still decides, with organizationId undefined; pass isAgent too, or assignment and @mentions fail with NOT_AN_AGENT); unset: the same plus one warning at boot |
| authorize | ({ session, headers, organizationId, permissions }) => boolean \| Promise<boolean> | staff-organization check | Replaces the permission check on every agent endpoint. organizationId is always staffOrganizationId (as resolved for the request), never a ticket's organization. permissions is e.g. { support: ["reply"] }. Without a staff organization (null), pass isAgent as well: the default looks in the staff organization, so every assignment and @mention would fail with NOT_AN_AGENT |
| acceptSession | ({ session, headers, kind }) => boolean \| Promise<boolean> | refuses impersonated sessions | Called first on every session endpoint; kind is "customer" or "agent". false answers 403 SESSION_NOT_ACCEPTED |
| isAgent | (userId) => boolean \| Promise<boolean> | member of the staff organization whose role has support: ["read"] | Who can be assigned a ticket or @mentioned. Anyone else is NOT_AN_AGENT |
| mailer | Mailer | | Sends thread mail to requesters. Requires email. Unset: no outbound mail and no supportDelivery table |
| email | { from, replyDomain, appUrl, ticketPath?, replyDelay?, requireVerifiedEmail? } | | Required with mailer and with inbound |
| email.from | string | required | Sender of thread mail, e.g. "Acme Support <[email protected]>". Mail from this address is dropped as a loop |
| email.replyDomain | string | required | Replies go to support+<token>@<replyDomain>. A domain, not an address. Mail from any address on it is dropped as a loop |
| email.appUrl | string | required | Your app's origin, for the ticket link in mail |
| email.ticketPath | (id) => string | (id) => `/support/${id}` | Path of a ticket in your app. Set it if the default could collide with your routes (a top-level /:org segment, for example) |
| email.replyDelay | number (ms) | 120000 | Delay before an agent reply is mailed. Skipped if the requester saw the reply first. 0 sends at once; must be 0 or more |
| email.requireVerifiedEmail | boolean | true | Mail account holders only at a verified address |
| inbound | { source, newTickets?, maxPerSenderPerHour?, maxUnverifiedPerHour?, maxBytes?, resolver? } | | Receive email at /support/inbound. Requires email |
| inbound.source | SupportInboundSource | required | rawRelay(...) or wrapsInbound(...) |
| inbound.newTickets | boolean | true | Open a new ticket for mail that doesn't thread. A requester's reply to a closed ticket still opens its follow-up |
| inbound.maxPerSenderPerHour | number | 20 | Verified email replies stored per sender in the last hour before more are dropped |
| inbound.maxUnverifiedPerHour | number | 100 | Unverified messages stored in the last hour, across all senders, before more are dropped |
| inbound.maxBytes | number | 26214400 (25 MiB) | Largest raw message accepted |
| inbound.resolver | DkimResolver: (name, rrtype) => Promise<string[] \| string[][]> | system DNS | DNS TXT lookups for the DKIM check, for tests and custom DNS. Serve a test key from it to test inbound threading without patching node:dns (see Inbound email) |
| attachments | { storage, maxBytes?, allowedTypes? } | | Enable attachments. Unset: no supportAttachment table, uploads answer STORAGE_NOT_CONFIGURED |
| attachments.storage | SupportStorage | required | s3Storage(...), or your own |
| attachments.maxBytes | number | 10485760 (10 MiB) | Largest upload |
| attachments.allowedTypes | string[] | png, jpeg, gif, webp, pdf, plain text, csv, zip | Allowed content types. HTML, SVG and XHTML are refused at boot even if listed |
| onEvent | (event: ByoEvent) => void \| Promise<void> | | Receives every support event, after the write commits. Errors are logged, never thrown. See Events |
| organizationCleanup | boolean | true | Clean up after the organization plugin's delete, remove-member and leave endpoints. Turn off to keep history. See Lifecycle |
| autoCloseAfter | number (ms) | 604800000 (7 days) | The sweep closes tickets solved this long ago |
| maxAttempts | number | 5 | Attempts per delivery before it is marked failed |
| batchSize | number | 100 | Deliveries per sweep (and tickets auto-closed per sweep) |
| leaseMs | number (ms) | 300000 (5 min) | A claimed delivery older than this is presumed dead and retried |
| pageSize | number | 25 | Tickets per list page, 1 to 50 |
| categories | string[] | false | ["question", "bug", "feature", "sales"] | The kinds of support the widget offers as cards when a customer opens a ticket. The pick is stored as a tag on the ticket, so agents filter by it like any tag. Each must be a tag (a-z0-9_-, 1 to 50). false or []: no cards, and create-ticket refuses a category |
| schema | | | Rename tables and fields |
Boot validation throws a [@byo-oss/support] … error for: a staffOrganizationId that isn't a string, null or a function (or is an async function), mailer without email (or email without mailer), inbound without email, inbound without source, attachments without storage, a negative replyDelay, a replyDomain that contains @, pageSize over 50, a categories entry that isn't a tag, an option that must be a whole number but isn't (or is below its minimum: 0 for autoCloseAfter, inbound.maxPerSenderPerHour and inbound.maxUnverifiedPerHour, 1 for maxAttempts, batchSize, leaseMs, pageSize, inbound.maxBytes and attachments.maxBytes), and allowedTypes containing text/html, image/svg+xml or application/xhtml+xml. A missing organization() plugin throws an Error whose message contains ORGANIZATION_PLUGIN_REQUIRED.
Seed the staff organization
better-auth's createOrganization can't set an id, so to give the staff organization a fixed id (to keep in config) create it through the adapter, plus a member row that makes someone its owner. Run it once, for example from a seed script:
const ctx = await auth.$context;
const staffOrganizationId = "staff"; // what you pass as staffOrganizationId
await ctx.adapter.create({
model: "organization",
forceAllowId: true,
data: { id: staffOrganizationId, name: "Support team", slug: "support-team", createdAt: new Date() },
});
await ctx.adapter.create({
model: "member",
data: { organizationId: staffOrganizationId, userId: ownerUserId, role: "owner", createdAt: new Date() },
});The owner role has every support action once step 2 is done. The other route is to create the organization the normal way, from your admin UI or auth.api.createOrganization, and put the id it gets in SUPPORT_STAFF_ORGANIZATION_ID.
Access
Agents. Agent endpoints call
authorizewith{ organizationId: staffOrganizationId, permissions: { support: [...] } }. The default looks up the caller'smemberrow in the staff organization and asks the organization plugin whether the role grants the action. It works whether or not the staff organization is the session's active one.Customers. A customer sees a ticket if they are its requester, or it is shared with an organization (
visibility: "organization") they are a current member of. A requester who leaves the organization keeps their own tickets; teammates lose the shared ones at once. A teammate can read and reply and upload, nothing else. Only the requester can solve, reopen, rate, share or mark a ticket seen.Sessions.
acceptSessionruns first on every session endpoint. The default refuses sessions an admin is impersonating, reads included. Add your own credential rules, for example to refuse API-key or bearer sessions:support({ acceptSession: ({ session, headers }) => !session.session.impersonatedBy && !headers.get("authorization")?.startsWith("Bearer "), });acceptSessiononly runs once a request has a session. An API key or bearer token on its own gives one only through a plugin that turns it into a session (better-auth'sbearer, or API keys with sessions enabled); without such a plugin that request is unauthenticated and answered 401 beforeacceptSessionruns, so a rule like the one above applies when the header arrives next to a session cookie or through such a plugin.A guard of your own that runs before better-auth's handler (one that refuses impersonated sessions app-wide, say) answers support's requests first, so classify support's paths in it. The reads are
GET, under your better-auth base path (/api/authby default):/support/my-tickets,/support/ticket,/support/attachment,/support/agent/tickets,/support/agent/ticket,/support/agent/tags,/support/agent/cannedand/support/agent/attachment. Every other support endpoint isPOST.supportPathMethodsfrom@byo-oss/support/clienthas the same map for code.What customers get back. One serializer: ticket
id, number, subject, status, priority, channel, organizationId, visibility, rating, createdAt, updatedAt, lastMessageAt, solvedAt, unread, isRequester;isRequesteris false for an organization teammate viewing a shared ticket (the widget hides solve, reopen, rate and share for them; the server refuses those with 403); messages of kindreply, pluseventrows of typestatusandmerged. NeverreplyToken,assigneeId,agentSeenAt,mentions, notes, other events,verified,emailMessageIdor internal attachments. Agents appear by{ name, image }only.Statuses. A new ticket is
open. An agent reply setspendingunless the request sets astatus. A customer reply onpendingorsolvedreopens it. The requester can solve (fromopenorpending) and reopen (fromsolved). Agents can set any status. The sweep closessolvedtickets afterautoCloseAfter. Aclosedticket takes no replies (TICKET_CLOSED): mail to it opens a new ticket with afollowup_ofevent.Merging. An agent can merge a ticket into another with the same requester and the same organization (
MERGE_NOT_ALLOWEDotherwise). Messages, tags, attachments and deliveries move to the target; the strictervisibility(private) andverified(false) win, and the target keeps the laterlastMessageAtof the two; the source is closed withmergedIntoId. Every endpoint that takes a ticket id followsmergedIntoId, with the access rule re-applied to the target, exceptmergeSupportTicketsanddeleteSupportTickets, which act on the ids given.
Components
Widget: popover or inline
<SupportWidget /> is a popover by default: a launcher button with the unread count, and a panel that opens below it, 360 px wide at most, aligned to the launcher's right edge so it extends to the left. Put it at the right end of your header; near the left edge of the screen the panel would run off it. Escape or a click outside closes it.
variant="inline" renders the panel in place instead, at the full width of its container, with no launcher, and it never closes. Use it for a page of its own: "My tickets", or the page your email links open.
ticketIdopens that ticket's thread (a popover starts open unlessdefaultOpenoropensays otherwise). A new value opens that ticket;nullorundefinedafter a ticket goes back to the list. Back goes to the list.onTicketChange(id | null)is called when the user opens a ticket (a row, or the one they just created) with its id, and withnullwhen they go Back to the list or the new-ticket form. Sync your URL with it, so Back on an inline page doesn't leave the address on the old ticket. Changes that come from theticketIdprop never call it. If the user leaves the new-ticket form (Back) before the ticket is created, the widget stays where they went and doesn't report it; the ticket shows up in the list.defaultOpensets whether the popover starts open (default: open whenticketIdis set).openandonOpenChangecontrol the popover. The launcher, Escape and a click outside callonOpenChange, and the panel followsopen. When your app setsopentotrue(not the launcher) whileticketIdis set, the panel shows that ticket's thread. That is how the same link opens the same ticket again after the user closed the panel: setopenback totrue. The launcher reopens wherever the user left off; if your app declines a launcher click (keepsopenfalse), its own lateropenstill showsticketId's thread. SetopenfromonOpenChangein the same event: anopenthat turnstruein a later render (after anawait, in a transition, through a router navigation) counts as your app opening the panel and showsticketId's thread.
const [open, setOpen] = useState(Boolean(ticketId));
<SupportWidget client={authClient} ticketId={ticketId} open={open} onOpenChange={setOpen} />Deep links
Customers. Email links (ticketPath(id)) and in-app notifications should open a page with the inline widget, which works at any width and doesn't close on the first click. Pass onTicketChange so the URL follows the widget:
// /help?ticket=<id>, or whatever ticketPath returns
<SupportWidget
client={authClient}
variant="inline"
ticketId={ticket ?? null}
onTicketChange={(next) => router.push(next ? `/help?ticket=${next}` : "/help")}
onNavigate={(href) => router.push(href)}
/>onTicketChange(null) (Back to the list) needs an address too, so pick the list route together with ticketPath: the list at /help with ticketPath: (id) => `/help?ticket=${id}` as above, or one route with an optional id (/help/{-$id} in TanStack Router; in Next.js a layout, as for the inbox below) with ticketPath: (id) => `/help/${id}`.
Keep the page and the ticket on one route: a query parameter as above, an optional path parameter, or a layout route that renders the widget for both paths. Two sibling routes (/help and /help/:id, each rendering its own widget) remount the component every time the user opens a ticket or goes Back: it loads the list again from the first page and loses its scroll position and any pages loaded with "Load more".
Staff. SupportInbox takes ticketId (opens that ticket; null or undefined closes the thread) and onTicketChange(id | null), called when the user opens a ticket, goes Back, follows a merge to its target or deletes the open ticket. Map both to a route such as /staff/support/:id, so notification links open the ticket and the URL follows the inbox. Changes that come from the ticketId prop never call onTicketChange, so the round trip doesn't loop. A merge or delete that settles after the agent opened another ticket leaves that ticket open and reports nothing, and nothing is reported after the inbox unmounts.
Render the inbox once, for both /staff/support and /staff/support/:id: from one route with an optional :id, or from a layout route whose child only declares the param. Don't render it from two sibling routes. Moving between siblings unmounts one inbox and mounts another, which loses the search, the filters and the checked rows every time the user opens or closes a ticket. For example, a TanStack Router layout route /staff/support with a child /staff/support/$id that has no component of its own:
// routes/staff.support.tsx: renders for /staff/support and /staff/support/<id>
function StaffSupport() {
const navigate = useNavigate();
const { id } = useParams({ strict: false }); // set by the child route
const { agents } = Route.useLoaderData();
return (
<SupportInbox
client={authClient}
agents={agents}
ticketId={id ?? null}
onTicketChange={(next) => navigate({ href: next ? `/staff/support/${next}` : "/staff/support" })}
onNavigate={(href) => navigate({ href })}
/>
);
}With Next.js, render the inbox from app/staff/support/layout.tsx (a layout stays mounted as its child pages change), read the id with useParams(), give app/staff/support/page.tsx and app/staff/support/[id]/page.tsx nothing to render, and push the same paths with router.push.
Staff list (agents)
agents fills the inbox's assignee and @mention pickers. Keep only the staff organization's members whose role grants support: ["read"]: that is the check isAgent makes, so anyone else would show up in the pickers and fail with NOT_AN_AGENT when picked. Derive it from your roles' permissions, never from role names. A member can hold several roles ("admin,billing").
On the server, from the staff organization's members:
import { roles } from "./access"; // step 2
const canRead = (role: string) =>
role.split(",").some((name) => roles[name.trim() as keyof typeof roles]?.authorize({ support: ["read"] }).success);
const organization = await auth.api.getFullOrganization({ headers, query: { organizationId: staffOrganizationId } });
const agents = (organization?.members ?? [])
.filter((member) => canRead(member.role))
.map((member) => ({ id: member.userId, name: member.user.name, image: member.user.image }));In the browser (a single-page app with no server code of its own), from a staff member's session, with the same canRead, or better-auth's authClient.organization.checkRolePermission({ role, permissions: { support: ["read"] } }) for each of the member's roles when organizationClient was given your ac and roles:
const { data } = await authClient.organization.listMembers({
query: { organizationId: staffOrganizationId, limit: 100 },
});
const agents = (data?.members ?? [])
.filter((member) => canRead(member.role))
.map((member) => ({ id: member.userId, name: member.user.name, image: member.user.image }));Both read one page of members: getFullOrganization returns up to the organization plugin's membershipLimit (100 by default), and listMembers returns limit members (the organization plugin's membershipLimit, 100 by default) and a total. With a larger staff organization, page through listMembers with offset.
Inbox layout
Give SupportInbox a height: put it in a flex column with className="min-h-0 flex-1", or give its parent a fixed height. With a height, the queue, the thread and the details panel each scroll on their own and the composer stays at the bottom of the thread. Without one, the inbox grows with its content and the page scrolls instead, taking the ticket's header and the composer out of view on a long thread. It is never shorter than 28rem.
From md up the queue and the thread sit side by side, and from lg up the details panel (requester, status, priority, assignee, tags, merge, delete) is a third column. Below that, a Details button shows it. On a phone the queue and the thread take turns.
Queue rows show the requester, status, high and urgent priority, assignee and tags. An open ticket also shows how long the customer has waited since their last reply (only replies move lastMessageAt, and a customer reply reopens the ticket), quiet at first, amber from 6 hours and red from a day.
The composer keeps each ticket's unsent text and its Reply or Internal note choice while the agent opens other tickets, for as long as the inbox is mounted. Ctrl+Enter (Cmd+Enter) sends; a reply then goes to pending, waiting on the customer. Send and solve replies and sets the ticket to solved in one request; it is offered on open and pending tickets, for replies, not notes. The menu next to Send has Send and keep open (for "we're looking into it") and Send and close. Typing / as the whole message suggests canned replies, and @ suggests team members to mention; arrow keys move, Enter or Tab picks, Escape hides the list.
Keyboard: j and k move between tickets, Enter opens one, / searches, r and n start a reply or a note, e solves the open ticket and ? lists them. They act only while focus is in the inbox or on the page itself, never in a field or with a modifier held, so they don't take your app's own shortcuts. The ? sheet (also the keyboard button by the queue's heading) turns single-key shortcuts off, remembered in localStorage. With attachments on, files can also be dropped on the composer or pasted into it, and png, jpeg, gif and webp attachments up to 5 MB show a preview in the thread (in the widget too).
Kinds of support. With categories on (the default), the widget's New ticket, and its empty list, show a card per category: "Ask a question", "Report a bug", "Suggest a feature", "Talk to us". The card opens the form with that kind's heading and placeholder, and the ticket is created with the category as a tag. Word a category, or name one of your own, with labels.categories ({ [id]: { title, hint, placeholder } }, merged per category); a category without labels shows its id. In the inbox a category tag leads the row's tags, with an icon.
The widget names statuses in the customer's words (customerStatus: "With our team", "Awaiting your reply", "Solved", "Closed"). A status you renamed in status keeps your name there until you set customerStatus. Every relative time shows the full date on hover, from absoluteTime.
Polling
The components poll; there are no websockets. While the tab is hidden, nothing polls.
- Widget, closed popover: the ticket list every
badgePollInterval(60 s by default), for the launcher's unread count. That is one request a minute per signed-in tab on every page that shows the launcher. - Widget, open or inline: the ticket list and the open thread every
pollInterval(15 s by default). Opening the popover refreshes at once. - Inbox: the queue and the open ticket every
pollInterval(15 s by default).
0 turns either interval off. The two widget intervals are independent: pollInterval={0} leaves the badge poll on.
Wording, sizes and fields
Wording. The default copy never says "agent" or "inbox", which apps often use for their own AI agents and inbox: the staff view's heading is "Support queue", a reply from staff without a name shows as "Support", and the message of NOT_AN_AGENT (which your app may show) says "That user is not on the support team". The API keeps "agent" as the name of the staff role: SupportInbox and its agents prop, the /support/agent/* endpoints, isAgent, NOT_AN_AGENT, authorType: "agent" and the support.agent.* events. Rename anything on screen with labels.
Sizes. On a coarse pointer (a touch screen), every button, field, ticket row and checkbox label is at least 44 px tall, and the × buttons are 44 px wide as well. With a mouse or trackpad they keep their compact size (about 32 px). This uses Tailwind's pointer-coarse: variant, which needs Tailwind 4.1 or newer; on 4.0 the controls stay compact everywhere. Fields use 16 px text below the md breakpoint (text-base md:text-sm), so iOS doesn't zoom into a focused field. Your @source line already covers these classes.
Fields. fieldClassName, on both components, is added to every text input, select and textarea (not to checkboxes, radios or the file input). Like the other class props it appends with no merging; see Tailwind.
Email replies
Add a Mailer and email and every public agent reply is queued for the requester. Notes are never mailed.
npm install @wraps.dev/emailimport { support } from "@byo-oss/support";
import { wrapsMailer } from "@byo-oss/support/wraps";
support({
staffOrganizationId,
mailer: wrapsMailer({ from: "Acme Support <[email protected]>" }),
email: {
from: "Acme Support <[email protected]>", // the same address the mailer sends from
replyDomain: "reply.acme.com",
appUrl: "https://app.acme.com",
},
});wrapsMailer is re-exported from @byo-oss/mailer/wraps; it sends through your own AWS SES account, and the sender must be verified there. Any object with send(message) is a Mailer: resolve { id, messageId? }, throw to retry, throw PermanentMailError (from @byo-oss/mailer) for a send that can never succeed. Run testMailer from @byo-oss/mailer/testing against your own. @byo-oss/mailer also has sesMailer (@byo-oss/mailer/ses, for an SES v2 client you already have) and emailSdkMailer (@byo-oss/mailer/email-sdk, for the providers behind email-sdk); to import those subpaths, add @byo-oss/mailer as a direct dependency (pnpm doesn't expose a dependency's dependencies).
What gets sent:
- Subject
[#123] <subject>, Reply-Tosupport+<token>@<replyDomain>, a plain text body and an escaped HTML copy, and a link to the ticket (appUrlplusticketPath(id)). Route that path to a page that renders<SupportWidget variant="inline" ticketId={id} />(see Deep links): withticketIdthe widget shows that ticket's thread, Back returns to the list, and a ticket the signed-in user can't read shows the thread's error state. For exampleticketPath: (id) => `/help?ticket=${id}`with the help page readingticketfrom the query. SetticketPathwhenever the default/support/<id>could collide with your routes, for example a top-level/:orgsegment wheresupportwould be read as an organization slug. Attachments go as that link, not as files. - The address is resolved when the mail is sent: the account's email if verified (or any, with
requireVerifiedEmail: false), else the account-less requester'srequesterEmail. No address: the delivery isskipped. - Delay. A reply is due
replyDelayafter it was written (2 minutes by default) and skipped if the requester has seen the ticket since. WithreplyDelay: 0and better-auth'sadvanced.backgroundTasks.handlerset, it sends inline; otherwise the sweep sends it. - Threading uses the reply token in Reply-To.
In-Reply-ToandReferencesare added when a stored Message-ID is known: inbound mail always stores one, andwrapsMailerorsesMailersending through SES in us-east-1 reports the sent Message-ID, so your replies are threaded too. In other regions, or with a custom endpoint, they report none and replies thread by the token alone.Referenceskeeps the newest ids up to 900 characters (SES refuses a longer header) and leaves out ids that aren't printable ASCII.
Run the sweep on a schedule. A plugin can't run jobs, so delayed mail, retries, auto-closing solved tickets and pruning stale uploads happen when you call processSupportDeliveries from your scheduler, every minute or so. Without it, delayed replies never go out and solved tickets never close (the sweep works without a mailer too):
// app/api/cron/support/route.ts
export async function GET() {
const result = await auth.api.processSupportDeliveries({});
return Response.json(result); // { sent, skipped, retrying, failed, hasMore, closed, pruned }
}Call it again while hasMore is true. If you use several BYO plugins, one route can sweep them all with @byo-oss/core:
import { sweepAll } from "@byo-oss/core";
export async function GET() {
return Response.json(await sweepAll(auth, { budgetMs: 20_000 }));
}Protect the route the way your scheduler expects (a shared secret header, or a platform cron that isn't publicly reachable). processSupportDeliveries itself is server-only: it is never an HTTP route.
Each delivery is a row in supportDelivery with its status and the reason it was skipped or the last error.
Inbound email
Customers, and people with no account, can email your support address. Mail to support+<token>@<replyDomain> continues that ticket; any other mail your relay posts to the endpoint opens a new one, so route your public support address ([email protected]) to it as well as the reply domain. Add inbound (it needs email, for the reply domain and the loop guard):
import { rawRelay, support } from "@byo-oss/support";
support({
// ...mailer and email as above
inbound: { source: rawRelay({ secret: process.env.SUPPORT_INBOUND_SECRET! }) },
});The endpoint is POST <your auth base path>/support/inbound, for example https://app.acme.com/api/auth/support/inbound. It takes no session: the source authenticates the relay and reads the raw RFC 822 bytes. Route all mail for replyDomain, plus-addresses included, and your public support address to it.
rawRelay({ secret, maxBytes? }) works with any relay that POSTs the raw message (Content-Type: message/rfc822) with Authorization: Bearer <secret>: Postmark inbound, Mailgun routes, a Cloudflare Email Worker. The secret is compared in constant time (401 on a mismatch), a message over maxBytes (25 MiB by default) answers 413 and an empty body 400. The secret must not contain whitespace: the bearer token can't carry it, so rawRelay throws at boot rather than answer 401 to every message (trim a value read from a file). SES's spam and virus verdicts (below) apply only when the relay passes SES's headers through in the raw message; other relays don't add them.
wrapsInbound({ key, bucket, region, client?, maxBytes? }) from @byo-oss/support/wraps takes Wraps inbound mail (SES to S3, announced by an EventBridge email.received event). Point an EventBridge API destination at the endpoint with the header X-Wraps-Inbound-Key: <key>. The source reads rawS3Key from the event (the whole event or just its detail) and fetches that object. The key must not start or end with whitespace (header values arrive trimmed, so it could never match): wrapsInbound throws at boot instead. It needs @aws-sdk/client-s3 and a role that can read the bucket:
{
"Version": "2012-10-17",
"Statement": [
{ "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::YOUR_BUCKET/*" },
{ "Effect": "Allow", "Action": "s3:ListBucket", "Resource": "arn:aws:s3:::YOUR_BUCKET" }
]
}Grant s3:ListBucket as well as s3:GetObject. Without ListBucket, S3 reports a missing object as AccessDenied instead of NoSuchKey, so a message that is gone looks like a failure and the relay retries it forever. With it, a missing object answers 404 and is not retried; any other S3 error answers 502 and is.
One Wraps inbound stack emits an email.received event for every domain it receives mail for, so filter the EventBridge rule behind the API destination on detail.receivingDomain (your replyDomain). Without the filter, mail for every domain the stack receives reaches support and opens tickets.
{
"source": ["wraps.inbound"],
"detail-type": ["email.received"],
"detail": { "receivingDomain": ["support.acme.com"] }
}Matching is exact and case-sensitive, and Wraps takes receivingDomain from the message's first To address as written, so mail that reaches support only by Cc or Bcc, or with another address first in To, carries another domain (or none) and the rule skips it. Use [{ "equals-ignore-case": "support.acme.com" }] to match any case, and add another domain only if it receives nothing but support mail: Wraps receives every address on a domain and support doesn't check the recipient, so on a shared domain (sales@, billing@) every unthreaded message would open a ticket. Keep the public support address on a dedicated subdomain instead.
What the endpoint does with a message:
- Answers 202 for every message it took, dropped and duplicate ones included, so the relay stops retrying. Each drop is logged once through better-auth's logger, at
warn(a duplicate, a relay's retry, atinfo), with the reason and the sender's domain only:[@byo-oss/support] dropped an inbound email: auto_reply (sender domain: customer.com). better-auth logswarnby default; set itslogger: { level: "info" }to see duplicates too. A source's{ reject: status }is answered with that status, and a source that throws is answered 502 (retry). Withoutinboundthe endpoint answers 404INBOUND_NOT_CONFIGURED. - Drops mail SES found a virus in (below), mail from your own
fromaddress or any address atreplyDomain(loop guard), auto-replies (Auto-Submittedother thanno,X-Auto-Response-Suppress,Precedence: bulk|junk|auto_reply), bounces (empty return path,MAILER-DAEMON,postmaster, delivery reports), a Message-ID it already stored, mail with no sender, unparseable mail, and anything past the caps below. - Verifies the sender. A message is
verifiedwhen it carries a passing DKIM signature aligned with the From domain, whether or not the domain publishes DMARC. The relay's own authentication headers (Authentication-Resultsand the like) are ignored. The check reads DNS, so it needs Node'sdnsmodule: it does not run on edge runtimes. - Spam and virus verdicts. SES scans the mail it receives and adds
X-SES-Spam-VerdictandX-SES-Virus-Verdictat the top of the message, above every header the sender wrote. Support reads them from the raw message, so the rule is the same forwrapsInboundand for arawRelayfed from SES (Wraps'spamVerdictandvirusVerdictevent fields come from the same headers and aren't read). VirusFAIL: the message is dropped and support stores nothing of it, attachments included (withwrapsInbound, your Wraps bucket still holds the raw message and its parts). SpamFAIL: the message counts as unverified whatever its DKIM says, so it never appends to a ticket, never links to an account, counts towardmaxUnverifiedPerHourand opens a new ticket only undernewTickets.GRAY,PROCESSING_FAILEDor no verdict change nothing. Only the first copy of each header is read, which is SES's, so a copy the sender wrote further down can't hide aFAIL. Without SES scanning (turned off in the receipt rule, or another relay) a copy present is the sender's own; since onlyFAILacts, it can only make that sender's message stricter. - Caps.
maxPerSenderPerHourcounts verified email replies from that sender;maxUnverifiedPerHourcounts every unverified message, so forged mail never uses up a real customer's cap. - Threads by the reply token in a
support+<token>@<replyDomain>recipient, then byIn-Reply-ToandReferencesmatching a stored Message-ID. Never by subject. Merged tickets resolve to their target. - Appends only verified mail from the requester (an account's verified email, or the stored
requesterEmail), or, on an organization-shared ticket, from a member whose verified account has that address. Anything else opens a new private ticket with no organization, never linked to the thread. - Links to accounts only verified mail from a verified account. Unverified mail from an account holder's address is stored as an account-less sender (
requesterEmail), so a forgedFrom:can't put a ticket in someone's account. When a user later verifies that address, their verified tickets and messages are linked to them (linkSupportRequesterdoes the same on demand). - Stores the plain text part with the quoted reply stripped. The raw message is not stored. With
attachments, parts are stored under the same limits; a part that is over the limit, of a disallowed type or fails to store is dropped, and anattachment_droppedevent row records it.
Test your own source with testSupportInboundSource from @byo-oss/support/testing. To test threading end to end without real DNS, sign test mail with a key of your own (dkimSign from mailauth, say) and serve its public key through inbound.resolver:
const resolver: DkimResolver = async (name, rrtype) => {
if (rrtype === "TXT" && name === "test._domainkey.customer.test") return [[`v=DKIM1; k=rsa; p=${publicKey}`]];
throw Object.assign(new Error(`ENOTFOUND ${name}`), { code: "ENOTFOUND" });
};
support({ /* ... */ inbound: { source: rawRelay({ secret }), resolver } });Attachments
Add attachments and customers and agents can attach files to replies, agents can attach files to internal notes, and inbound mail keeps its attachment parts.
npm install @aws-sdk/client-s3import { s3Storage } from "@byo-oss/support/s3";
support({
attachments: {
storage: s3Storage({ bucket: "acme-support", region: "us-east-1" }),
// maxBytes: 10 * 1024 * 1024,
// allowedTypes: ["image/png", "application/pdf"],
},
});s3Storage({ bucket, region, endpoint?, forcePathStyle?, credentials?, client? }) works with S3 and S3-compatible stores (R2, MinIO: set endpoint, and forcePathStyle for MinIO). The role needs s3:PutObject, s3:GetObject, s3:DeleteObject and s3:ListBucket on the bucket. Blobs are stored under support/<organizationId or "_">/<attachmentId>.
SupportStorage is { put, get, delete, deletePrefix }: every method throws to fail the request, get resolves null for a missing key, and delete of a missing key resolves. Run testSupportStorage from @byo-oss/support/testing against your own; memoryStorage() from the same subpath is a store for tests.
- Uploading.
POST /support/upload?ticketId=…&filename=…with the file as the raw request body and its type asContent-Type(agents:/support/agent/upload, plusinternal=truefor a note). A missing or over-limitContent-Lengthanswers 413ATTACHMENT_TOO_LARGE, a type not inallowedTypesanswers 415ATTACHMENT_TYPE_NOT_ALLOWED, and the body is counted as it is read, so a header that lies can't store more than it claimed. The upload comes back unattached; pass its id inattachmentIds(up to 10) on the next reply or note. - Binding. Every id must belong to the same ticket, be uploaded by the caller, be unattached, and match the audience (an
internalupload only on a note); otherwiseATTACHMENT_NOT_USABLE. The sweep deletes uploads still unattached after 24 hours. - Reading. Attached files follow the ticket's read rule, and customers never get internal ones. An unattached file is readable only by its uploader and by agents. Files are served with
Content-Disposition: attachment,X-Content-Type-Options: nosniff,Content-Security-Policy: sandboxandCache-Control: private, no-store, and only png, jpeg, gif, webp and pdf keep their type; everything else isapplication/octet-stream. - Default allowed types:
image/png,image/jpeg,image/gif,image/webp,application/pdf,text/plain,text/csv,application/zip.
Lifecycle
Support cleans up after the organization plugin's own endpoints, with no wiring. After /organization/delete it deletes that organization's tickets; after /organization/remove-member and /organization/leave it unassigns the member's tickets if they left the staff organization (in a customer organization nothing changes: teammate access is checked live, and requesters keep their own tickets). A hook acts only when the endpoint succeeded, takes ids only from the response, and logs errors without failing it.
organizationCleanup: false turns the row cleanup off, for apps that keep history. On memory and MongoDB that keeps the organization's tickets; on SQL the organizationId foreign key still cascades the ticket rows away. The blobs under support/<orgId>/ are always removed when an organization is deleted, because cascaded tickets leave no row that points at them.
For deletes made any other way (a script, an admin tool, a direct database write), call the functions yourself. They run inside a better-auth transaction (runWithTransaction) when called in one, and are safe to run again:
import {
deleteMemberData,
deleteOrganizationData,
deleteSupportRequesterData,
linkSupportRequester,
} from "@byo-oss/support";
await deleteOrganizationData(auth, organizationId); // → { tickets }; also deletes the support/<orgId>/ blobs
await deleteMemberData(auth, { userId, organizationId }); // → { unassigned }
await deleteSupportRequesterData(auth, { email }); // → { tickets, messages }
await linkSupportRequester(auth, userId); // → { tickets, messages }A user is deleted. Foreign keys null
userId(requester, author, uploader) andassigneeIdon SQL; auser.deletehook does the same on adapters without them (memory, MongoDB) and clears any stored copy of their email (a user deleted outside better-auth keeps those email copies untildeleteSupportRequesterDataruns for the address). On every adapter the hook also removes their id from messagementionsand sets it to null inassigneeevent rows (from/to), which no foreign key reaches; it pages through every agent-authored message to do so, so a user delete costs time in proportion to that table. A user deleted outside better-auth keeps their id in mentions and assignee events; no exported function removes it.An account-less person (someone who only emailed) asks to be erased:
deleteSupportRequesterDatadeletes their tickets with all their messages, tags and attachments, and anonymizes their messages on other tickets.An organization is removed outside the organization plugin and leaves its blobs behind until
deleteOrganizationDataruns.With
@byo-oss/corethe fan-out reaches support through itsbyohooks, so one call cleans every BYO plugin:import { deleteMemberData, deleteOrganizationData } from "@byo-oss/core"; organization({ organizationHooks: { afterDeleteOrganization: async ({ organization }) => { await deleteOrganizationData(auth, organization.id); }, afterRemoveMember: async ({ member }) => { await deleteMemberData(auth, { userId: member.userId, organizationId: member.organizationId }); }, }, });Running this next to support's automatic hooks is safe. Add it for the other plugins' sake, and for deletes the endpoint hooks don't see.
Events to notifications
Support emits an event after every write that matters, through onEvent. Events are in-process and best-effort: a handler that throws is logged and never fails the request, and nothing is stored or retried.
Events fire after the write commits. Endpoint writes don't join a caller's transaction, so their events follow at once; sweepAll inside your runWithTransaction holds the sweep's support.ticket.status_changed events until it commits and drops them on rollback. Join with runWithTransaction, imported from @better-auth/core/context (better-auth doesn't export it). A plain adapter.transaction(trx => …) isn't joined at all, so the plugin's writes commit at once along with their events. Wrapping with runWithAdapter(trx, …) makes them join, but their events fire before the commit. Use runWithTransaction. On an adapter without transactions the events fire at once. If you call runWithTransaction yourself, pass { onAfterCommitHookError } so a hook queued earlier in the same transaction that throws can't skip the events queued after it. data carries ids, statuses and kinds, never message bodies, and always the ticket's visibility ("private" or "organization") besides the fields below.
| Event | userId | data (plus visibility) |
|---|---|---|
| support.ticket.created | requester | { ticketId, number, channel } |
| support.ticket.status_changed | requester | { ticketId, from, to } |
| support.ticket.assigned | the new assignee (absent when unassigned) | { ticketId, from, to } |
| support.ticket.merged | requester | { ticketId, sourceId, targetId } (subject is the target) |
| support.customer.replied | requester | { ticketId, messageId, channel } |
| support.agent.replied | requester | { ticketId, messageId, status } |
| support.note.added | none | { ticketId, messageId } |
| support.agent.mentioned | the mentioned agent (one event each) | { ticketId, messageId, kind } |
Every event also has type, occurredAt, actorId, organizationId (the ticket's, when it has one; left out of events about an internal note, see below) and subject: { type: "supportTicket", id }. The userId of an account-less requester is absent. A private ticket's events still carry its organizationId: consumers that fan out by organization must skip visibility: "private".
Wire them to @byo-oss/notifications with createEventBus from @byo-oss/core. Staff recipients are the staff organization's members whose role grants support: ["read"], read when the event is sent; derive them from your roles' permissions, never from a list of role names:
import { createEventBus } from "@byo-oss/core";
import { roles } from "./access"; // step 2
const staffOrganizationId = process.env.SUPPORT_STAFF_ORGANIZATION_ID!;
// staff-organization members whose role grants support:read, except the actor
async function supportStaff(exceptUserId?: string | null): Promise<string[]> {
const ctx = await auth.$context;
const members = await ctx.adapter.findMany<{ userId: string; role: string }>({
model: "member",
where: [{ field: "organizationId", value: staffOrganizationId }],
limit: 1000,
});
const canRead = (role: string) =>
role
.split(",") // a member can hold several roles
.some((name) => roles[name.trim() as keyof typeof roles]?.authorize({ support: ["read"] }).success);
return members.filter((m) => canRead(m.role) && m.userId !== exceptUserId).map((m) => m.userId);
}
const onEvent = createEventBus([
async (event): Promise<void> => {
const ticketId = event.subject.id;
switch (event.type) {
// staff: everyone who can read the queue, except whoever caused the event
case "support.ticket.created":
case "support.customer.replied": {
const title = event.type === "support.ticket.created" ? "New support ticket" : "Customer replied";
for (const userId of await supportStaff(event.actorId)) {
// the /staff/support layout renders <SupportInbox ticketId={id} /> for /staff/support/:id (see Deep links)
await auth.api.notify({
body: { userId, type: event.type, title, href: `/staff/support/${ticketId}` },
});
}
break;
}
// the one agent it is about
case "support.agent.mentioned":
case "support.ticket.assigned":
if (event.userId) {
await auth.api.notify({
body: {
userId: event.userId,
type: event.type,
title: event.type === "support.agent.mentioned" ? "You were mentioned" : "A ticket was assigned to you",
href: `/staff/support/${ticketId}`,
},
});
}
break;
// the requester, in-app
case "support.agent.replied":
if (event.userId) {
await auth.api.notify({
// the help page renders <SupportWidget variant="inline" ticketId={ticket} />
body: { userId: event.userId, type: event.type, title: "New reply to your ticket", href: `/help?ticket=${ticketId}` },
});
}
break;
}
},
]);
export const auth = betterAuth({
plugins: [organization({ ac, roles }), support({ staffOrganizationId, onEvent }), inbox()],
});If you use dynamic access control, check the organization's stored roles the same way. If your app already has a notification layer (a catalog of notification types, preferences, digests), route support's events through it instead of calling notify directly; the recipient rules below stay the same.
Which events go where:
- Staff:
support.ticket.created,support.customer.replied,support.ticket.assigned(to the new assignee) andsupport.agent.mentioned(to the mentioned agent). Notify only members of the staff organization whose role grantssupportactions; read members at send time, so a removed agent stops receiving them. - The requester:
support.agent.replied, andsupport.ticket.status_changedif you want to tell them a ticket was solved. Route byevent.userId. - Never to customers:
support.note.added. An internal note has its own event type so that forwardingsupport.agent.repliedto customers can't leak one. It carries nouserIdand, likesupport.agent.mentionedwithkind: "note", noorganizationId, so a handler that fans events out to a customer organization has nothing to fan a note out by. Keep it that way in your handler, and send it to staff or nowhere. A test (src/note-leaks.test.ts) fails if a note's text, id or files appear in a customer response, an event or an email. - With a
mailer, the requester also gets the reply by email. Use the in-app notification as the nudge and leave the email to support.
API
All of these are better-auth endpoints: call them through auth.api on the server (with { headers, body } or { headers, query }) or through authClient.support.* in the browser. Every endpoint is one of the kinds in the BYO conventions: own rows needs a session and works only on the caller's own tickets (and those shared with an organization they belong to); permission-gated needs a session and a support permission in the staff organization; server-only is never an HTTP route; credential-free takes no session and is verified by its inbound source.
| auth.api key | Method and path | Kind | Input | Returns |
|---|---|---|---|---|
| createSupportTicket | POST /support/create-ticket | own rows | body subject, body, organizationId?, visibility? ("private" default, or "organization"), category? (one of categories, stored as a tag) | { ticket } |
| listMySupportTickets | GET /support/my-tickets | own rows (and org-shared, where a member) | query status?, organizationId?, q?, cursor? | { tickets, nextCursor, features: { attachments, categories } } |
| getSupportTicket | GET /support/ticket | own rows | query id | { ticket, messages, attachments } (customer-visible only) |
| replyToSupportTicket | POST /support/reply | own rows | body ticketId, body, attachmentIds? | { message } |
| updateMySupportTicket | POST /support/update-mine | own rows (requester only) | body id, status? ("solved" or "open"), visibility?, rating? ("good" or "bad") | { ticket } |
| markSupportTicketSeen | POST /support/mark-seen | own rows (requester only) | body id | { ok: true } |
| uploadSupportAttachment | POST /support/upload | own rows | query ticketId, filename; raw body; Content-Type is the file's type | { attachment } (unattached) |
| getSupportAttachment | GET /support/attachment | own rows | query id | the file |
| listSupportTickets | GET /support/agent/tickets | permission-gated support:read | query status?, assignee? (a user id, "me" or "none"), tag?, organizationId?, requesterId? (the requester's user id), requesterEmail? (an account-less requester, any case), q?, cursor? | { tickets, nextCursor, counts, features: { attachments, merge, categories } } |
| getSupportTicketAsAgent | GET /support/agent/ticket | permission-gated support:read | query id | { ticket, messages, attachments } (every message, notes and events included) |
| replyAsSupportAgent | POST /support/agent/reply | permission-gated support:reply | body ticketId, body, internal? (a note), status?, mentions? (agent user ids, up to 20), attachmentIds? | { message } |
| updateSupportTickets | POST /support/agent/update | permission-gated support:update | body ids (1 to 100), status?, priority? (or null), assigneeId? (or null), addTags?, removeTags? | { updated }: the tickets matched, after merge-follow and dedupe, including any the update left unchanged |
| mergeSupportTickets | POST /support/agent/merge | permission-gated support:update | body sourceId, targetId | { ticket } (the target) |
| deleteSupportTickets | POST /support/agent/delete | permission-gated support:delete | body ids (1 to 100) | { deleted } |
| markSupportTicketSeenAsAgent | POST /support/agent/mark-seen | permission-gated support:read | body id | { ok: true } |
| listSupportTags | GET /support/agent/tags | permission-gated support:read | none | string[] (sorted, deduped) |
| listSupportCannedReplies | GET /support/agent/canned | permission-gated support:read | query q? (title contains) | canned replies, by title, up to 200 |
| saveSupportCannedReply | POST /support/agent/canned/save | permission-gated support:manage | body id? (omit to create), title, body | { cannedReply } |
| deleteSupportCannedReply | POST /support/agent/canned/delete | permission-gated support:manage | body id | { ok: true } |
| uploadSupportAttachmentAsAgent | POST /support/agent/upload | permission-gated support:reply | query ticketId, filename, internal? ("true"/"false"); raw body | { attachment } (unattached) |
| getSupportAttachmentAsAgent | GET /support/agent/attachment | permission-gated support:read | query id | the file |
| processSupportDeliveries | none | server-only | none | { sent, skipped, retrying, failed, hasMore, closed, pruned } |
| receiveSupportEmail | POST /support/inbound | credential-free, verified by its inbound source | the raw request | 202 { ok: true }, or the source's status |
Lists are newest lastMessageAt first, pageSize at a time, and nextCursor is opaque: pass it back as cursor (an invalid one answers INVALID_CURSOR). counts on the agent list is queue-wide and ignores the filters: { open, pending, unassigned, mine }. An unauthenticated call answers 401.
features tells a client what is switched on. Both lists return features.attachments and features.categories; listSupportTickets also returns features.merge. The components use it to hide the attach and merge controls and to offer the category cards (the widget) and mark category tags wit
