HTTP routes

helpdesk.handler(request: Request): Promise<Response> serves every route below under basePath (/api/helpdesk by default). Paths match with or without a trailing slash; the widget and the agent UI request them with one. Ids are UUIDs. Request and response bodies are JSON unless a row says otherwise. Related guides: Receive email, Run jobs and retention.

import { helpdesk } from '@/lib/helpdesk';

const handle = (request: Request) => helpdesk.handler(request);
export { handle as GET, handle as POST, handle as PATCH, handle as PUT, handle as DELETE, handle as OPTIONS };

CallersCopy Anchor Link

A visitor token is issued by POST widget/conversations to an anonymous visitor, and stops working after 30 days unused. An invalid identity token is refused with 401.

A customer can see a conversation they opened, one they were added to as a participant, and one shared with a company the caller's identity lists in orgs. A conversation they cannot see answers 404. Routes marked author also require the caller to be the conversation's own contact, and answer 403 otherwise.

WidgetCopy Anchor Link

A conversation in widget/session and widget/conversations/{id} carries its kind, chat or ticket, typing, true while an agent writes a reply, respondBy, the time the team aims to answer by while nobody has, and ratingScore. widget/session says with realtime whether widget/events is there, carries with captcha the adapter's client when this caller must solve it (null otherwise), lists under the inbox the priorities this caller may pick with their descriptions (null for a visitor or a tier the inbox does not offer them to), and carries priorityLabels and ratingScale.

POST widget/conversations/{id}/rating takes { rating: 'good' | 'bad', comment? } on the default scale and { score: 1..5, comment? } when ratingScale is 5; the other shape is refused with 400.

Opening a conversationCopy Anchor Link

The body of POST widget/conversations, which helpdesk.createConversation(request, input) takes as well:

An unidentified caller on an inbox that is not public gets 401. A blocked contact or address gets 404. Over the rate limit, 429.

contextCopy Anchor Link

AgentCopy Anchor Link

Every route here requires an agent. The agent/deals, agent/canned and agent/overview routes answer 404 when features switched their section off. A viewer may call every GET, and of the rest only PATCH agent/me, POST agent/notifications/seen and the agent/views routes; anything else answers 403. Once any agent has the supervisor role, PUT agent/settings, DELETE agent/agents/{id} and GET agent/audit answer 403 to everyone else.

Every request that is not a GET and succeeded is written to audit_log with the agent, the route, the id in its path and the names of the fields it sent. POST agent/conversations/{id}/typing and POST agent/notifications/seen are not.

The inbox list reads inbox, status, assignee, q, tag, priority, days, tier, channel and sort from the query string; sort is waiting, priority or sla, the nearest deadline first.

Opening a conversation as an agentCopy Anchor Link

The body of POST agent/conversations, which helpdesk.openConversation() takes as well with agentUserId added:

A conversation opened this way has the channel agent, starts pending with the customer's turn, has no response target, and raises conversation.created with the agent's message. A blocked contact answers 404.

RateCopy Anchor Link

The links come in a customer-reply. A forged or expired link answers 404. A conversation already rated answers 200 and records nothing; one that is no longer resolved, or was merged, answers 409. With ratingScale: 5 the link names a score from 1 to 5, and a score of 1 or 2 opens the conversation again.

HealthCopy Anchor Link

InboundCopy Anchor Link

Without inboundWebhookSecret, or with another bearer token, it answers 401. The message is refused with 400 when empty, and with 413 over 25 MiB or when its headers exceed 64 KiB. Mail from a blocked address, and unsigned automated mail (an out-of-office or a bounce), is accepted with 202 and not stored; signed automated mail that answers a conversation is stored there as an internal system note. A message already stored, by Message-ID, is accepted and ignored. Signed mail from a sender over their hourly budget answers 429; unsigned mail over budget is dropped quietly.

JobsCopy Anchor Link

Without jobsSecret, or with another bearer token, it answers 401.

runJobs({ budgetMs }: { budgetMs?: number } = {}), with budgetMs 20,000 by default, wakes due snoozes, queues due reminders, queues due SLA notices, applies retentionDays, then works through due jobs until the budget is spent. It returns:

A failed job runs again after 2, 4, 8 and 16 minutes, and is kept with its last error after the fifth attempt. The job kinds are on Database.

Origins and CORSCopy Anchor Link

• A mutation is any method but GET, on any route but rate, inbound and jobs. A POST mutation must send Content-Type: application/json (415 otherwise). health takes only GET.
• A mutation that carries an Origin header must come from the origin of adminUrl, or, on a widget/* route, from an origin in an inbox's allowedOrigins. Otherwise it answers 403.
• widget/* responses to an allowed origin carry CORS headers: methods GET, POST, PATCH, OPTIONS, headers content-type, x-helpdesk-visitor, x-helpdesk-identity, max age 600 seconds. Agent routes never do.
• OPTIONS on any path answers 204.

ErrorsCopy Anchor Link

LimitsCopy Anchor Link

Over a customer limit, the route answers 429. Over the receipt, notice and triage caps, the conversation is stored and the email or triage is skipped.