Support reference

Config

categories is classification; the guard and the verdicts are provenance; inboundAddresses is bounded by the MX constraint. Refusals carry an ordinary error code.

support({
  inboundAddresses: ["support@help.example.com"],
  ai: { enabled: true, model: "@cf/meta/llama-3.1-8b-instruct" },
  categories: defineSupportCategories({ /* yours, merged over the eight */ }),
  guard: {
    maxRawBytes: 2_000_000,
    maxPerSenderPerHour: 20,
    maxPerHour: 500,
    archiveSpam: true,
  },
})

Until inboundAddresses is set the inbox is inert — it ignores every message and says so once in the log.

A mailed reply is sent from the inbox the thread arrived at, under the name reply.fromName gives:

support({
  reply: {
    fromName: "{agent} at Acme",               // default "{agent}"; "Acme Support" is used for every reply
    replyToAddress: "support@help.example.com", // the Reply-To, by default the thread's inbox; also the sender for a thread whose inbox is not claimed
  },
})

{agent} is replaced by the reply’s agentName. With no agent name the email capability’s fromName is used. The addresses support may send as are inboundAddresses and reply.replyToAddress, declared through email’s enqueueAs (@pithy-sh/email ^0.9.0). A thread whose inbox is not claimed and no replyToAddress is refused. Each of those domains must be a sending domain on Email Service, which pithy doctor checks.

staff is off until you name it. It says which of your app’s own signed-in users work the inbox, by two powers from your own role catalog:

support({
  staff: { readPower: "support:read", assignPower: "support:assign" },
})

readPower lets a staff member join a thread’s presence room; assignPower lets them assign it. Both are held in the organization the request acts for, so staff needs organization. Both must sit only on roles in your catalog’s unassignable list, and not on the role organization({ ownership }) confers, so only an operator can confer them through the control plane. support() refuses the composition otherwise: an organization’s own administrator may hand out any assignable role, and anybody may found an organization and take its ownership role, so either would let a customer make themselves staff and read every other customer’s mail. Without staff, both answer to management clients only.

search is FTS5 by default, and search by meaning is off until you turn it on:

support({
  search: {
    fts: true,          // the default: a ranked word search; false keeps the LIKE scan
    semantic: true,     // or { model, dimensions }; off by default, @cf/baai/bge-m3 at 1024
  },
})

semantic costs a second inference per inbound message, on your own Workers AI binding, on top of classification — roughly double the per-message AI cost, and the volume guard bounds messages, not spend. On, pithy support provision creates a Vectorize index per environment and backfills it once; off, it drops the index. The model is pinned: change it and pithy vector reprocess --index support-messages re-embeds what the old one wrote, with no vector() composed. Vectors carry message ids and nothing else. How a query is answered is Search.

Enums

Priority — urgent (today) · normal (this week) · low (when there is time)

Sentiment — angry · frustrated · neutral · positive

Direction — inbound (arrived from the customer) · outbound (a reply this Worker sent)

Channel — email · app

Account link source — session · email_address · null

Categories — billing · account_access · bug_report · feature_request · abuse_report · privacy_request · spam · uncategorized, plus your own.

Routes

RouteVerified by
POST /support/feedbackuser — open or append to your own thread
GET /support/feedbackuser — my threads
GET /support/feedback/:iduser
GET /support/threadscontrol-plane — the inbox list. It takes no q: a query is a search
POST /support/threads/searchcontrol-plane — ranked threads by q, in keyword, semantic or hybrid mode, up to limit (20, at most 50). Everything in the body, which is strict
GET /support/threads/:idcontrol-plane
GET /support/repliescontrol-plane
POST /support/threads/:id/archivecontrol-plane
POST /support/threads/:id/assigncontrol-plane
POST /support/threads/:id/replycontrol-plane
POST /support/threads/:id/reclassifycontrol-plane
POST /support/threads/:id/flagscontrol-plane
POST /support/staff/threads/:id/assignuser — same-origin, and staff.assignPower in the organization they act for
POST /support/presence/ticketsuser — staff.readPower; without staff, nobody
GET /support/presence/rooms/:kind/:recordIda single-use ticket — the WebSocket upgrade

Scopes

Scope
support:threads:readThe inbox, a thread, the canned replies and the search. The search is a POST declared a read, readInBody: true, so the scope stays in the default grant. Also the scope a support.thread room ticket is minted with
support:threads:archive
support:threads:reply
support:threads:reclassify
support:threads:flag
support:threads:assignWho answers whom. Its own scope, because that is not the same permission as marking a thread done

Error codes

Code
support/not_found
support/invalid_categoryA declared key outside the effective taxonomy
support/rejectedThe guard refused it
support/unparseable_message
support/classification_failed
support/reply_failed

Thread columns worth knowing

Column
declaredCategoryThe submitter’s claim. Written once, never by the classifier
categoryThe model’s judgment. Overwritten on every classification
accountLinkSourcesession, email_address, or null
channelOn the thread and on every message
emailJobIdPresent exactly when a row is outbound and email. Ask channel, not this
assigneeRef, assigneeNameWho has the thread: an opaque reference and the name to show. Null when nobody has it
assignedAt, assignedByWhen it was last assigned, and by whom

Assignment

POST /support/threads/:id/assign takes { assignee: { ref, name } | null, note? }. ref is opaque, the participant shape presence rooms use, so a dashboard member, a user of your app and an agent are all assignable without support knowing which. null unassigns. The note, up to 500 characters, is shown to anybody who can read the thread, so it is a note to colleagues and never a place for the customer’s details.

Every change appends a row to pithy_support_assignments in the same batch as the change itself, so a handover never lands without its history. The conversation read returns that history as assignments, oldest first: the new and the previous assignee, who made the change, the note and the time.

Assigning the current assignee again changes nothing, records nothing, emits nothing, and answers changed: false. Every real change emits support/thread_assigned or support/thread_unassigned to audit.

The listing filters by assignee: GET /support/threads?assignee=<ref> for one person’s threads, or assignee=none for the threads nobody has. So none is never a valid ref.

Presence

One support.thread room per thread, keyed by its id, joined with support:threads:read and adding no scope. The activities are viewing and replying, and a client announces replying when its reply form opens. A management client mints its ticket at POST /control-plane/presence/tickets; a signed-in staff member mints one at POST /support/presence/tickets.

Threading

On In-Reply-To and References. Never on the subject.

An app submission is minted a message id on the way in, so a mailed reply threads back rather than opening a new conversation.

Recipient matching

On the SMTP envelope recipient. Never on a To: header.

What provisioning creates

An R2 bucket (only if something writes to it), a classification Worker per environment, the full-text index, a <project>-<env>-support-messages Vectorize index per environment while search.semantic is on, and an Email Routing rule per environment, <project>-<env>-support-inbound, sending each address that environment’s inboundAddresses claims to its Worker, on the zone that holds the address’s domain. Routing needs Email Routing already enabled for the domain and never enables it. The three routing flags replace that with one project-global rule, <project>-global-support-inbound. pithy secrets provision mints the deployed presence-ticket-key the thread room’s tickets are signed with.

License

MIT, like most of the kit. Nothing here is unlocked by a hosted dashboard — every route is reachable with a credential you issued.

ESC