On this page
- Every feature starts off
- Where a feature runs
- Add your own provider
- What a provider receives
- Work runs in the background
- Reply drafts
- Triage suggestions
- What AI does by itself, per channel
- When AI acts on its own
- When intake's model fails
- Limits
- AI chat
- History and usage
- Who can change AI settings
- Sign in with a subscription
- For developers and AI agents
Every feature starts off
No AI feature runs until an admin turns it on, on Colliedesk Cloud too. Turning a feature on is your consent that its ticket data goes to the provider it uses; Colliedesk records who agreed and when, and asks again whenever the feature moves to another provider. Turn a feature off at any time in Settings → AI & agents → Features.
Each feature is one row there: its name, a short line, its state (On · Suggest, On, Off) and its switch. The switch turns the feature on or off and saves at once, and the page says Saved with Undo, which puts the switch back as it was. Turning on Chat intake asks first: a panel says what goes to the model, who processes it and how to turn it off, and the feature stays off until you tick the agreement and choose Agree and turn on. The agreement is the act of turning the feature on, which the history records with who did it. Undo after you turned chat intake off puts it back on at once, without the panel: you agreed to it moments before, and the history records the change; once the Saved message is gone, the switch asks again. Pictures and the customer's profile have their own switches (below). The rest of the row opens the feature's settings in a panel beside the list: its provider and model, its automatic runs, its Default for channels and the channels that differ. Choices in the panel save at once; Done closes it. Without a provider yet, one notice offers Add provider and the setup guide. A switch that is off has its reason in the lock beside it: no provider yet, no provider picked for that feature (open its row and pick one), or you are not an admin. On a phone the tabs (Features, Providers, AI chat, Usage, History) scroll sideways, with a fade at the edge that hides some.
A line that would only explain sits in the ⓘ beside the name instead. It opens on hover, on keyboard focus and by tap, and Escape closes it. Automatic runs, the models of a provider, Usage and History each have one.
The setup flow offers one of them to a new team: its Turn on AI drafts step turns Reply drafts on with Default for channels set to Suggest, through the same call as Settings, so the consent is recorded the same way. It leaves triage suggestions off.
Where a feature runs
Each feature (Triage suggestions, Reply drafts, and Chat intake for chat channels) picks one of:
- The server's provider. Set by the server operator for every workspace. On Colliedesk Cloud it is Colliedesk AI: Anthropic's Claude models, run for HC Labs and included in your plan. On your own server it is whatever the operator configured (see environment variables); without one, Settings offers Add provider and the setup guide. You pick only the provider: the operator picks the model each feature runs on it, Settings shows it, and when the operator changes it your features follow. If the operator switches the server's provider off, nobody can pick it, and the features set to it stop: Settings shows it greyed, and says why when you point at it or tab to it. They run again once it is on, or pick another provider.
- A provider you add. Your workspace pays that provider directly.
- None. The feature stays off.
Add your own provider
In Settings → AI & agents → Providers, admins choose Add provider:
- Anthropic: an API key from console.anthropic.com. Requests go to the Claude API.
- OpenAI: an API key from platform.openai.com. The address is filled in.
- OpenRouter: one OpenRouter key for hundreds of models. The address is filled in.
- Other or self-hosted: any OpenAI-compatible server (Groq, vLLM, Ollama, LM Studio). Enter the
base URL with its version path, for example
http://localhost:11434/v1.
After the key (and the address), choose Load models: Colliedesk asks the provider which models
the key may use and lists them, so you tick the ones you want instead of typing names. The list holds
only models that answer what Colliedesk sends (a JSON answer, and a reasoning effort): for Anthropic,
the Claude models whose capabilities say so; for OpenAI, its reasoning models (GPT-5 and later, the o
series), not the older GPT-4 and GPT-3.5 or the image, audio and embedding models; for OpenRouter, the
models that take structured output, without the batch-only entries. A model the provider has retired
or set to shut down is left out. If a check still refuses a model, the message names it. With many
models, a search box finds one whatever the punctuation or spacing: gpt5 mini finds gpt-5-mini.
Loading the list saves nothing and costs nothing. A server that keeps no list (some self-hosted ones) says so; type
the model names then, separated by commas.
Pick the models you want to use; the first is the default. Before anything is saved, Colliedesk sends one small request to the first model. If the provider refuses (a wrong key, a model it does not have, an account out of credit), nothing is saved and Settings says why. That request is billed by the provider like any other.
A workspace can add 5 providers. Keys are encrypted on the server and never shown again: you see their last 4 characters. Change key checks the new key first; if it fails, the old key keeps working. Check sends the same small request again and shows whether the provider still works. At most 10 checks a minute run in a workspace.
Delete erases the key at once. The features that used the provider turn off and stay off until an admin picks another provider: Colliedesk never moves your data to another provider on its own. To undo a delete, add the provider again.
A base URL must be a public https address. A server on your own network (an Ollama on the same
machine) works only when the server operator allows private addresses; then a provider without a key
is accepted too.
What a provider receives
A feature that is on sends its provider the ticket's messages, the customer's name, matching published
knowledge base articles, and short excerpts of similar solved tickets with other customers' names and
emails removed. Private notes are never sent. Colliedesk does not keep what it sent the provider, nor the
provider's answers, apart from the draft or suggestion itself. A draft keeps its text and the request
that asked for it until 90 days after it ended, and both are in the export (ai-drafts.ndjson). Each provider keeps data under its own
policy; read it before you add one, for example Anthropic's.
To keep data on your own servers, add an OpenAI-compatible provider on your network (vLLM, Ollama) and use it for every feature.
OpenRouter: which providers serve your requests
OpenRouter sends each request to one of the companies that serve the model. Its routing keeps your
requests on some of them: data_collection: deny only on providers that do not store or train on what
they are sent, zdr: true only on providers with zero data retention
(OpenRouter's provider routing). The routing
cannot be changed in the app yet; a developer or an AI agent sets it on the provider
(For developers and AI agents).
A model that no such provider serves fails its check, so you know before a feature uses it. Tightening
the routing takes effect at once. Loosening it (deny to allow, zero retention off) lets customers' data
reach more providers. Other providers have no routing, and refuse it.
On OpenRouter, a feature's effort goes to the models OpenRouter lists as reasoning at that effort; another model answers without one, as before.
Work runs in the background
Suggestions and drafts run as background tasks, so no screen waits for a model: a task that hits a busy provider tries again a little later (three times at most), and one whose feature was turned off meanwhile is dropped without calling anyone. A locked workspace runs none.
Reply drafts
With Reply drafts on, the reply box of a conversation has Draft with AI; while they are off it shows Draft with AI and Off to admins only, as a link to Settings → AI & agents; agents see no AI tool until it is on. Say what the reply should say (optional, up to 2,000 characters: "offer a refund", "ask for the order number"), or leave it empty for a reply to the customer's newest message. You keep working while it is written; the conversation never waits for the model.
The draft arrives as plain text with:
- Sources: the knowledge base articles and solved tickets it used, named by Colliedesk, never by the model. A source the model invents is dropped.
- Missing information: what the reply needs that no source said, instead of a guess.
- Check before sending: an email address, a number of six digits or more, or another customer's
name that is in the draft but not in this conversation. A model can copy one from a past ticket or
be told to add one by a message; read them before you send. A word in an alphabet the conversation
does not use (a model slipping into another language) is listed too, and so is a masked detail
(
[email],[number],[company]) copied from a past ticket for you to fill in. Where the model copied[customer], Colliedesk puts this customer's name (or leaves the greeting without one). A link, with or withouthttps://, that neither this conversation nor a knowledge base article the draft was given holds is listed too: a past ticket never vouches for a link, since another customer wrote it.
Replace puts the draft in the reply box in place of what you typed; Insert below adds it under your text; Discard throws it away. Nothing is sent until you press Send, and you can edit every word. Asking again replaces your earlier draft. Stop ends one still being written; it is not counted. A draft nobody used for 7 days expires, and resolving or closing the conversation discards it.
Colliedesk keeps how each draft ended (sent nearly as written, sent edited, discarded, replaced, expired), so a team can see whether drafts help, and an article's Used by AI box says how many drafts used it this month. A reply sent from a draft says so on the timeline: from an AI draft, sent as written or from an AI draft, edited. A draft that failed says why, with Try again (the same prompt) and, when a setting is the cause (the provider's key or credit, the included AI), the way to Settings → AI & agents. A draft's text and prompt are erased 90 days after it ended; the numbers stay. At most 30 drafts a minute are asked for in a workspace.
Write a draft when a customer writes
Admins can let drafts write themselves: Settings → AI & agents, under Reply drafts, set Default for channels to Suggest (or do it on one channel, in its AI tab). A dialog says first what it would have meant in the last 30 days (how many customer messages, about what a draft costs, and how much of the included AI it may use, or that your own key is billed). It is Off until an admin picks Suggest, and goes back to Off when drafts turn off or move to another provider; it stays Off until an admin picks Suggest again.
Each new customer message (by email, the web form or a problem report) then gets a draft. It waits a minute for more messages from the customer, so several in a row get one draft, which answers them all. Imported tickets, auto-replies, bounces and mail that fails its sender check get none, and neither does a message a teammate has answered by the time the draft would be written. A newer customer message replaces a draft nobody used once its new draft is written (until then, and if a limit stops the new one, the earlier draft stays); a person who asks for a draft with Draft with AI replaces the automatic one.
The draft waits above the reply box for everyone on the team, with its sources: Use draft puts it in an empty reply box; with text in the box, Insert below or Replace my text; Discard throws it away. AI never sends: a person reads it and presses Send. When the model thinks the message needs no reply (a thank-you), the draft is folded with Show draft. On a short screen every draft starts folded to one line with its buttons, so the conversation stays in view; Hide folds an open one.
Automatic drafts stop at 100 a day (UTC; admins change it in Automatic runs), at 5 per conversation in 24 hours, and, on the server's provider, once they used half of the month's included AI: the other half stays for drafts people ask for and for triage. Paused, the conversation and Settings say until when; Draft with AI keeps working. Restoring a workspace from a backup turns the automatic mode off.
Triage suggestions
With Triage suggestions on, a new ticket's first customer message (by email, the web form, or from an AI agent or a program) asks the model for tags, a priority and the teammate best placed to answer. It reads the ticket, your matching knowledge base articles, and how your team sorted similar solved tickets. The suggestion appears at the top of the conversation's details as Suggested by AI within a few seconds, with a one-sentence reason and the articles and tickets it rests on. While it is written you keep working; Cancel stops it. On a narrow screen the Show details button says AI suggestion while one waits.
It names only your own tags and active teammates; anything else the model names is dropped. What the conversation already has is not suggested, and a field someone changed before the suggestion came is left alone: the card says "Not suggested: you set Urgent before this arrived".
Nothing changes until someone accepts. Each part (tags, priority, assignee) has Accept; Accept all (or Accept the rest) takes what is left, and Dismiss drops it. Tags are added, never removed, and anything accepted is changed back like any other change. Suggest again asks by hand. When the automatic limit below is reached, the card says automatic suggestions are paused until the next midnight UTC (shown in your timezone) and Suggest now still asks for one. A failure says why and what to do next, for example to open Settings → AI & agents when the included AI is used up.
Imported tickets get no suggestion. A suggestion nobody used for 7 days expires; its reason is erased 90 days after it ended. Colliedesk keeps whether each one was accepted, in part, or dismissed.
Apply suggestions automatically
Admins can let suggestions apply by themselves: Settings → AI & agents, under Triage suggestions, set Default for channels to Auto (or do it on one channel, in its AI tab; a dialog says what it does first). Turning triage on starts at Suggest; moving it to another provider goes back to Suggest, and it stays there until an admin picks Auto again. Off makes suggestions only when someone asks. Pick what applies by itself: Tags and Priority (the default) and Assignee. A part not picked waits for someone to accept it, as above.
It only fills what nobody set: tags are added, never removed; the priority is set only while it is still Normal on a ticket a customer started (by email, the web form or a problem report); a teammate is assigned only when nobody is. What it leaves says why on the card ("Not set: Sam Ortiz was already assigned"). Only the suggestion a new ticket gets applies by itself; one asked for with Suggest again waits for a person.
Each change shows Applied by AI on the conversation's timeline and in its details, with Undo for each part and Undo all. Undo takes back only what is still AI's: a part someone changed since is kept, and the card says so. Apply again applies it once more, filling only what is still empty. A teammate AI assigns gets the "Assigned to you by AI" notification. It costs nothing more: it uses the suggestion already made. Settings shows how many suggestions AI applied and how many were undone in the last 30 days. Restoring a workspace from a backup turns the automatic mode off.
What AI does by itself, per channel
Each feature has a level: what it does without anyone asking.
| Feature | Off | Suggest | Auto |
|---|---|---|---|
| Triage | Only when someone presses Suggest | Suggests for every new conversation | Applies the picked parts by itself (above), with Undo |
| Reply drafts | Only Draft with AI | Writes a draft when a customer writes | Never: AI never sends |
| Intake (chat channels only) | The channel's rules decide | Every message a customer wrote waits in Review with AI's suggestion; a person decides | AI applies what it is sure enough of (the scope's threshold); everything else waits in Review with its suggestion. Until a channel's own decisions show AI is ready for an action, that action waits in Review too |
The workspace's level is Default for channels in each feature's panel (open its row) in Settings → AI & agents. A channel can set its own level for a feature, and a chat channel for each of its scopes (one-to-one messages, groups), for example triage Auto on the support mailbox and Off on the sales one. A scope without its own level follows the channel, and the channel follows the workspace. A level never goes past what the workspace allows: while a feature is off for the workspace, it is off on every channel, whatever the channel says. People can always ask by hand (Suggest, Draft with AI) while the feature is on.
Email and web forms have no intake: every message or form sent is a conversation, as the channel's rules always made it, and triage and drafts run after it is created. Intake is for chat channels, where many short messages arrive and some are not requests. Chat intake has its row in Built-in AI only once the workspace has a chat channel, and its default for channels is Off or Suggest: Auto is set on each chat channel's scope, where its readiness is known.
When a feature moves to another provider, or is turned on again, its consent is new: every channel that ran it by itself goes a step down (Auto to Suggest; drafts written by themselves to drafts asked for), and the history says why. Another model of the same provider changes nothing else: levels stay, and intake's labels keep counting. Restoring a workspace from a backup lowers levels as a new provider does.
People with ai_settings:update (the Admin role has it) set a channel's levels in Settings → Channels →
On a chat channel, the AI tab has an Intake row for each scope that collects messages, and under the table, for each scope where intake does more than the rules, its Intake settings: how sure AI must be to open, add or set aside on its own (each with its default shown), whether it may add alone while the customer has two or more open conversations (it may by default: sure enough, it adds to the one it names; ticked, every such card waits for a person however sure AI is), how long a resolved conversation can be reopened, when a card is too old to decide alone, what AI reads besides the messages (a source that needs a consent says so, with a link to Built-in AI), the words and patterns to hide or mask (below) and the channel's own instructions. A Last 7 days line says how many cards came, how many AI decided by itself, how many of its decisions people changed and how many wait, with a link to them in Review.
Before intake's AI reads a chat, names become "Customer A" or "Team 1", passwords and codes are hidden,
and phone numbers, email addresses, IBANs and the numbers after an English account or ID word ("account
number", "passport") are masked. A channel in another language adds its own words in intake's settings:
Words that mark a secret for the words that come before a password or a code, Words before a bank
account number and Words before an identity document number, and Patterns to mask for the shapes
of an identifier no word names (a national ID number, a phone number written without its prefix): each a
pattern in RE2 syntax with what AI sees instead ([phone], [id number], [account number] or
[hidden]), at most 20 of 200 characters; a pattern that can match no character at all (an empty
string, a word boundary alone), is too large or does not compile is refused.
Taking a word or a pattern out masks less; like any change to intake's settings, it needs ai_settings:update.
Intake may also send pictures customers sent, the customer's profile, or an integration's data, only once an admin agreed to each: in Settings → AI & agents under Chat intake (Images customers sent, The customer's profile, each a switch that gives or takes back the consent and says Saved with Undo). The conversation's own text is covered by turning the feature on. Pictures go to intake's AI only when the workspace agreed to send them, the channel's images source is on, and its model (and its fallback model) reads pictures, as the provider says: every Claude model does; on OpenRouter, a model that lists images among its inputs. At most four of a card's pictures go, each at most 5 MB, never with messages that talk about a password or a code. A card that is only pictures is then decided like any other.
When AI acts on its own
At Auto, intake's AI opens, joins or sets aside a card by itself only for an action its labels show it
gets right on that channel's scope (it never writes to the customer: a conversation it opens sends the
channel's own received notice, if it has one, as when the rules open one); any other action stays a suggestion on the card, which waits
for a person in Review. Labels are only explicit ones: a person who decides a card as AI suggested (it was right), decides
otherwise or moves the messages AI placed (it was wrong), and offline evaluations an operator recorded for
this server's prompt version, on whichever model they ran (collie intake-eval, see
Score AI intake on your own cases). A decision nobody looked at counts for nothing: silence
is not a label.
| Action | Opens with | Never with |
|---|---|---|
| Open a conversation | 30 labels, 90 % right | more than one conversation opened for chatter in a week |
| Add to a conversation | 30 labels, 95 % right | a new request merged into an old conversation (by people's labels in the last 30 days, or in an evaluation) |
| Set aside | 30 labels, 95 % right | a request set aside (by people's labels in the last 30 days, or in an evaluation) |
People's labels count for 30 days, and an evaluation for the prompt version it ran; both keep counting when
intake moves to another model. A newer run of the same dataset replaces it. Since cards at Auto go to the rules when AI may not act, most
never reach a person: in practice a gate opens with an evaluation, or with an admin's override.
An admin may open an action by hand before its labels do, with a reason (Let it … alone anyway, below;
it needs ai_settings:update).
Raising intake to Auto on a scope opens a dialog first: each action with whether it is ready ("ready · 38 of 40 right") or stays a suggestion and why ("until 30 decisions are labelled (12 of 30)", "7 wrong of 40 (needs 95 % right)"), an estimate of the AI calls and their cost over 30 days from the messages that came, and for an admin, Let it … alone anyway with the reason the history keeps. The level and the override are saved together. Lowering a level never asks.
When intake moves to another provider, a scope at Auto goes back to Suggest and the AI tab says so ("Groups: Auto was lowered to Suggest on Oct 24, 2026: intake moved to another provider, which needs consent again") with Turn Auto back on, which asks with the same dialog. Another model keeps the level.
When intake's model fails
Intake can have a fallback model: another of its provider's models, tried once when its model times out, is busy, refuses for its rate, is gone, or answers what Colliedesk cannot read. A refused key or an account out of credit is not tried again on the other model. Each call is in the usage. The fallback model cannot be set in the app yet; a developer or an AI agent sets it (For developers and AI agents). The provider cannot drop a model intake uses this way. A new fallback model keeps intake's levels, as another model does.
Limits
Automatic runs. Work Colliedesk starts on its own (a triage suggestion for each new ticket, a draft for each customer message when that is on) stops at 300 a day (UTC) and 30 a minute in a workspace, of which 100 a day may be drafts, whichever provider runs it, so a flood of tickets cannot run up a bill. Intake's decisions on chat channels count too, at most 300 a day of them (
intake_per_day), so a busy group cannot spend the day's triage and drafts. Past the daily limit automatic suggestions wait until 00:00 UTC; what an agent asks for still runs. Admins change both numbers in Settings → AI & agents → Features (open Triage suggestions, then Automatic runs, Change). Each task counts once, however many times it is retried.Included AI. The server's provider can come with a monthly allowance (on Colliedesk Cloud, included in your plan). When it is used up, features on the server's provider stop until the first day of the next month (UTC), and Settings says so; your own providers keep working. Settings → AI & agents → Usage shows what is used. A call that starts sets aside the most it can cost, so calls running at the same time never spend more than is left; the last few cents of a month can stay unused.
AI chat. The help center's AI chat has limits of its own and never uses the included AI above, so customers asking questions cannot stop your team's drafts and suggestions.
AI chat
AI chat answers your customers on the help center from your published articles. It is a feature of this page like the others (provider, model, on or off), and it needs a Help chat channel too. Its use, its chats and their transcripts are on the AI chat tab; see AI chat.
History and usage
Settings → AI & agents → History lists who added, changed or deleted a provider or a key, and who turned a feature on, off or elsewhere, with keys shown only by their last 4 characters. Every call to a provider leaves one usage record (the feature, the model, tokens in and out, whether it failed, and for the server's provider its cost at that day's prices), never the text sent or received. When the provider reports what a call cost (OpenRouter does with every answer), that is kept too, in the provider's own unit: OpenRouter's credits, never converted to dollars. Settings → AI & agents → Usage sums a month per feature and provider. Both are in the export.
Who can change AI settings
Everyone with ai_settings:read sees these settings; changing them needs ai_settings:update, and
adding a provider or replacing its key ai_settings:manage_credentials (the Admin role holds both).
Sign in with a subscription
A Claude Pro or Max plan, or a Gemini subscription, cannot be used: their terms do not allow another application to use them. Use an API key.
For developers and AI agents
An AI agent does what its token's permissions allow, at once, as when a person does it. A call without the permission is refused and says which one is missing. The tools are listed in MCP.
Settings:
ai_settings:readreads the settings.ai_settings:updatechanges features, levels and providers.ai_settings:manage_credentialsis needed on the two calls that carry a key.- OpenRouter routing is
routingonPOST /api/v1/ai/providersandPATCH /api/v1/ai/providers/{id}, or on the MCP toolscolliedesk_ai_provider_addandcolliedesk_ai_provider_update. Loosening it needsai_settings:update, like any other change to it. - Intake's fallback model is
fallback_modelonPUT /api/v1/ai/slots/intakeorcolliedesk_ai_slot_set. An empty string removes it. - Image and profile consent:
colliedesk_ai_source_consent_set, taken back withcolliedesk_ai_source_consent_remove.
Levels per channel and intake:
- A channel's levels are
PUT /api/v1/channels/{id}/ai/{slot}and the MCP toolscolliedesk_channel_ai_setandcolliedesk_channel_ai_get. Raising or lowering a level, and changing intake's settings, needsai_settings:update. - Intake's masking settings are
redact_keywords(words before a password or a code),contact_labelswithaccountandid(words before a bank account or an identity document number), andredact_patterns(each a pattern with itsmask:phone,id_number,account_numberorhidden). - An admin opens an action before its labels do with
gate_overrideand agate_override_reason(ai_settings:update). - Readiness is
GET /api/v1/channels/{id}/ai/intake/readiness?scope=: each action's gate, labels, what it misses, what AI did on its own, how much people corrected, and what a month costs. MCP:colliedesk_channel_ai_intake_readiness_get. - Evaluations are
POST/GET /api/v1/channels/{id}/ai/intake/evaluations. MCP:colliedesk_channel_ai_intake_evaluation_record(needsai_settings:update) andcolliedesk_channel_ai_intake_evaluations_list(needschannels:read).
Drafts, triage and replies:
- With
ai_assist:create, an agent asks for a reply draft, reads it and discards it like a person (colliedesk_ai_draft_create,colliedesk_ai_draft_get,colliedesk_ai_drafts_list,colliedesk_ai_draft_discard). - With the same permission, it reads, asks for, applies and dismisses triage suggestions
(
colliedesk_ai_triage_get,_create,_accept,_dismiss). - It can leave its own written reply as a draft for a person to send (
colliedesk_reply_draft). - Sending a reply needs
messages:send. A token that replies from a draft passes its id (ai_draft_idoncolliedesk_reply_send), so the draft records how close the reply stayed to it, as when a person sends it.
Was this page helpful?
Updated
This page is rendered from the repository. Spot a mistake? Open an issue or a pull request.