Helpdesk · Integrate

Events and integrations

Ticket events for your plugin, inbound email, Shop, and the core hooks Helpdesk builds on.

Ticket events

Helpdesk emits a plugin hook when a ticket changes. Every payload is { ticketId, number, status }.

Event	When
`justflows.helpdesk.ticket.created`	A ticket is opened, by a customer or by staff.
`justflows.helpdesk.ticket.replied`	Staff post a public reply.
`justflows.helpdesk.ticket.noted`	Staff add an internal note.
`justflows.helpdesk.ticket.status_changed`	The status changes.
`justflows.helpdesk.ticket.escalated`	A site escalates the ticket to the platform desk.
`justflows.helpdesk.ticket.<name>`	An automation with a webhook action fires; `<name>` is the action's name (letters and underscores).

typescript

ctx.hooks.action("justflows.helpdesk.ticket.created", async (event) => {
  // { ticketId, number, status }
  await notifyChat(`New ticket ${event.number}`);
});

Hook names a plugin emits must start with its own id, so Helpdesk’s events are always under justflows.helpdesk.. Read the ticket itself through the routes when you need more than the payload.

Inbound email

When JUSTFLOWS_INBOUND_MAIL_SECRET is set, mail posted to core’s POST /api/mail/inbound reaches Helpdesk through the email.received action and the email.route filter. A message opens a ticket, or becomes a reply when its subject carries the ticket’s reply token, such as [SUP-9-replytoken]. The token belongs to one ticket, so a reply in the platform mailbox is filed on the site that owns it even when ticket numbers repeat across sites. Quoted history is left off the thread.

Shop

With Shop active, Helpdesk listens to justflows.shop.order.created, .paid, .payment_failed, .shipped, and .refunded to keep order snapshots for tickets, and can open a ticket when a payment fails. Refunds and returns from a ticket go through Shop’s own routes with ctx.plugins.call, as the current staff session.

Core hooks Helpdesk uses

Hook	What Helpdesk does
`auth.login`	A guest who signs in with the same verified email keeps their tickets.
`user.deleted`	Removes the person's name and email from their tickets and destroys their files and sensitive messages. Ticket counts stay.
`account.sections`	Adds tickets, and help for Shop orders, to the account page.
`html.head`	Adds the support popup to public pages.
`seo.sitemapPaths`	Lists the public tickets page in the sitemap.
`staticExport.exclude`	Keeps the support pages out of static exports.
`theme.css`	Adds the support page styles.

Helpdesk also uses ctx.databases.forSite for the network inbox on the main site, ctx.captcha for the Discussion CAPTCHA provider, and ctx.ai.complete for reply suggestions without tools.