HandlingModule records who is dealing with a record, on the record itself: the handling field every BaseModel can carry, alongside share and stats. There is no separate queue — the records are the queue. It works on any datatype, and a person and an AI employee take work the same way.
A record gets handling when it arrives on a watched channel (AI employees' intake opens it); records nobody watches have none.
Routes
/handling/:datatype/:idJWT/handling/:datatype/:id/takeJWT/handling/:datatype/:id/doneJWT/handling/:datatype/:id/no-actionJWT/handling/:datatype/:id/releaseJWT:datatype must be a plain collection name and :id a record id, or the call answers 400. The caller is the signed-in user; without an email, take, done and no-action answer 401.
Lifecycle
status is one of open · in_progress · done · no_action.
take— succeeds only while nobody has it (nohandling, oropen). The check and the write are one conditional update, so two people can never both take it. Taking one you already hold is fine. Otherwise the answer is{ taken: false, handling, message }, with the message saying who has it and since when, or who finished it.done— body{ outcome }, a line saying what was done. Required.no-action— body{ reason }, why nothing needs doing. Required.release— body{ reason? }. Gives it back, or reopens a finished one:openfor anyone to take, clearing the holder and outcome.
done and no-action do nothing on a record already finished. Outcomes and notes are kept to 500 characters.
Threads. When the record carries a thread, the rest of that conversation in the same collection is taken, finished or released with it — a conversation is dealt with as one.
Events. Every change emits record.handling with { orgId, datatype, id, handling, previous }. AI employees listen to it; something taken but not finished within the configured handlingMinutes is released again for anyone to take.
The handling field
| Field | |
|---|---|
status | open · in_progress · done · no_action |
channel | What it arrived on (email, sms, social, ticket, order, form…) |
title | What it is, in a line |
thread | The conversation it belongs to |
since | When the current status began |
by, byName, takenAt | Who holds it |
doneAt, outcome | Set when finished |
history[] | status, at, by, byName, note — the last 50 changes |
See also AI employees.