Events
Every HelpdeskEvent kind passed to onEvent, its payload, and what raises it.
onEvent(event: HelpdeskEvent): Promise<void> in the configuration is called once a change is stored. HelpdeskEvent is a union told apart by kind, exported as a type from better-helpdesk. Related guide: React to events.
The call is awaited inside the request that made the change, including the inbound email webhook and runJobs. What it throws is logged as [helpdesk] onEvent {kind} failed and does not change the response.
Conversation and Message are the stored rows, exported as types. Their fields are the columns of conversation and message in camel case.
conversation.created
Prop
Type
Raised by:
POST widget/conversations- An inbound email that does not thread into an existing conversation
helpdesk.createConversation(request, input)called from host codePOST agent/conversationsandhelpdesk.openConversation(), wheremessageis the agent's opening message
message.created
Prop
Type
Raised by:
- An agent's reply or internal note,
POST agent/conversations/{id}/messages, and each reply or note ofPOST agent/conversations/bulk helpdesk.addNote()from host code- A customer's message on an existing conversation,
POST widget/conversations/{id}/messages - An inbound email that threads into an existing conversation
A customer message on a resolved conversation reopens it and raises only message.created; its conversation.status is open. The first message of a new conversation raises conversation.created instead. An automated inbound email (an out-of-office or a bounce) raises nothing. When it is signed and answers a conversation, it is stored there as an internal system note; otherwise it is dropped.
sla.warning and sla.breach
Prop
Type
Raised by runJobs, once per target per conversation: the warning once the configured share of the target has passed, the breach once the deadline has, each at the run that finds it. A conversation whose deadline is already past when the run looks gets the breach alone. The same run writes a timeline row and queues the agent-sla email. Set service levels says what to hang on these, such as a PagerDuty incident.
conversation.updated
Prop
Type
Raised by:
| Change | agentId |
|---|---|
PATCH agent/conversations/{id} | The agent |
helpdesk.changeConversation() from host code | The agent named, else null |
POST agent/conversations/bulk, once per conversation changed | The agent |
Accepting an AI suggestion, POST agent/conversations/{id}/suggestion | The agent |
The customer resolving it, PATCH widget/conversations/{id} | null |
| The customer rating it, in the widget or from an email link | null |
runJobs waking a snoozed conversation | null |
Changes that raise no event
- Writes through
helpdesk.store, so a handler that writes there cannot set itself off. - Merging conversations, adding a participant, dismissing an AI suggestion, and the suggestion that triage stores.
- A customer sharing a conversation with their company, or no longer sharing it.
- Conversations unassigned because their agent was removed from the team.
- Changes to contacts, companies, deals and activities.
Timeline rows
A conversation.updated also writes rows to conversation_event for each of these fields that changed: status, priority, tier, assigneeId, type, inbox, title, tags, snoozedUntil, rating. The row's data is { from, to }, with by: 'customer' added when the customer made the change. The SLA fields written alongside a status change, such as slaPausedAt, appear in before but get no row.
Track customers, companies and deals
Bring your organizations in as companies, set the lead and deal stages your team uses, add your own fields, and link each customer to your own tools.
Theme the widget and the agent UI
Give the widget and the agent UI your app's colors, corners and dark mode through CSS custom properties.