Save tenant-wide settings (desk:admin)
PUT /api/desk/v1/settings
Module: Desk · operationId: setSettings · Tag: Configuration · Auth: access token (Authorization: Bearer <accessToken>)
Request body
application/json (required)
ai(object): AI features of the desk (triage, subject, summary, draftReply). Triage withautoApplyapplies each proposed value that reachesthresholdand leaves the rest pending; text fields read from the ticket are always suggestions. Draft replies never apply or run automatically; meeting summaries are never applied automatically. An applied summary fills the ticket's summary field (undo restores the previous one); withautoApplyit fills it on its own unless a person wrote the summary (the suggestion then waits).features(object): Settings per feature key (enabled, auto, autoApply, threshold)
callbacks(object): Callback settings: the custom fields of the form (in order), the rules for the note and the mails to customers.mailTextsandstatusMail: absent = the defaults (a manual mail text for the statusnot_reached, while that status exists),[]= none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the modeauto.fields(array of object): Custom fields of the callback form in orderkey(string, required): Key of a custom field (without cf.)required(boolean): The field must be filled
mailTexts(array of object): Mail texts for customers. Placeholders: {{name}}, {{nummer}}, {{telefon}}, {{kunde}}, {{grund}}, {{gewuenscht}}, {{status}}, {{mitarbeiter}}; unknown ones are refused.body(string, required): Text (placeholders allowed) (max length 8000)key(string, required): Lower-case letters, digits, - and _; uniquename(string, required): Name of the mail text (max length 120)subject(string, required): Subject (placeholders allowed) (max length 200)
note(object): Rules for the note of a callback (on create and when it changes); checked in the order required, minLength, pattern, aiCheck. Existing notes are not checked again.aiCheck(boolean): The AI judges whether the note gives an understandable reason (422note_rejectedwith a hint); an unavailable AI accepts the noteminLength(integer): Minimum characters of a non-empty note; 0 = off (max 2000)pattern(string): Go (RE2) regular expression the note must contain a match of; anchor with ^ and $ for a full match (max length 500)patternMessage(string): Shown instead of the pattern; required with a pattern (max length 200)required(boolean): The note must not be empty
statusMail(array of object): Ties a mail text to a callbackStatus; a status without an entry sends nothing. Archived statuses may stay (they just stop firing).mode(string, required): manual: the person decides when the status is set; auto: the mail is sent with the move into the status (one ofmanual,auto)status(string, required): Key of a callbackStatus entry, oncetext(string, required): Key of a mail text
mail(object): Mail rules of the tenant; empty fields use the defaults.aiClassify(boolean): The AI decides about unclear mail at or above aiThresholdaiThreshold(number): Confidence the AI needs to decide about unclear mail (max 1)aiTrim(boolean): The AI finds the main text of a long received mail (over 1500 characters) the rules could not trim (default false)blockedExtensions(array of string): Default: executables and scriptsbulkPolicy(string): Newsletters and bulk mail: drop (default) or make a ticket (one ofdrop,ticket)foreignSubjectMatch(boolean): A [#N] subject token appends mail of senders who are no participantfromName(string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one ofagentWithMailbox,agent,mailbox)maxAttachmentBytes(integer): Per file, default 20 MB, max. 40 MBmaxTotalBytes(integer): Per mail, default 35 MB, max. 40 MBperSender10min(integer): Above: appended quietly (default 10)perSenderHour(integer): Above: held in the mail log (default 30)
priorityMatrix(object): Priority from impact and urgencycells(object): "|" → priority keyimpacts(array of object): Impact levelskey(string): Key of the levellabel(string): Label of the level
urgencies(array of object): Urgency levelskey(string): Key of the levellabel(string): Label of the level
time(object): No longer used: rules for time entries and hourly billing (self approval, hour unit, tax rate, traffic light) are HR's work settings (ADR 0040); ignored on write and no longer returned
Example:
{
"callbacks": {
"note": {
"aiCheck": false,
"minLength": 10,
"required": true
}
},
"mail": {
"aiClassify": true,
"aiThreshold": 0.8,
"aiTrim": true,
"blockedExtensions": [
"exe",
"bat",
"js"
],
"bulkPolicy": "drop",
"fromName": "agentWithMailbox",
"maxAttachmentBytes": 20971520,
"maxTotalBytes": 31457280,
"perSender10min": 10,
"perSenderHour": 30
}
}
Responses
- 200 Saved (
application/json) - 400 Error (
application/json) - 403 Error (
application/json)
Fields of the 200 answer:
ai(object): AI features of the desk (triage, subject, summary, draftReply). Triage withautoApplyapplies each proposed value that reachesthresholdand leaves the rest pending; text fields read from the ticket are always suggestions. Draft replies never apply or run automatically; meeting summaries are never applied automatically. An applied summary fills the ticket's summary field (undo restores the previous one); withautoApplyit fills it on its own unless a person wrote the summary (the suggestion then waits).features(object): Settings per feature key (enabled, auto, autoApply, threshold)
callbacks(object): Callback settings: the custom fields of the form (in order), the rules for the note and the mails to customers.mailTextsandstatusMail: absent = the defaults (a manual mail text for the statusnot_reached, while that status exists),[]= none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the modeauto.fields(array of object): Custom fields of the callback form in orderkey(string, required): Key of a custom field (without cf.)required(boolean): The field must be filled
mailTexts(array of object): Mail texts for customers. Placeholders: {{name}}, {{nummer}}, {{telefon}}, {{kunde}}, {{grund}}, {{gewuenscht}}, {{status}}, {{mitarbeiter}}; unknown ones are refused.body(string, required): Text (placeholders allowed) (max length 8000)key(string, required): Lower-case letters, digits, - and _; uniquename(string, required): Name of the mail text (max length 120)subject(string, required): Subject (placeholders allowed) (max length 200)
note(object): Rules for the note of a callback (on create and when it changes); checked in the order required, minLength, pattern, aiCheck. Existing notes are not checked again.aiCheck(boolean): The AI judges whether the note gives an understandable reason (422note_rejectedwith a hint); an unavailable AI accepts the noteminLength(integer): Minimum characters of a non-empty note; 0 = off (max 2000)pattern(string): Go (RE2) regular expression the note must contain a match of; anchor with ^ and $ for a full match (max length 500)patternMessage(string): Shown instead of the pattern; required with a pattern (max length 200)required(boolean): The note must not be empty
statusMail(array of object): Ties a mail text to a callbackStatus; a status without an entry sends nothing. Archived statuses may stay (they just stop firing).mode(string, required): manual: the person decides when the status is set; auto: the mail is sent with the move into the status (one ofmanual,auto)status(string, required): Key of a callbackStatus entry, oncetext(string, required): Key of a mail text
mail(object): Mail rules of the tenant; empty fields use the defaults.aiClassify(boolean): The AI decides about unclear mail at or above aiThresholdaiThreshold(number): Confidence the AI needs to decide about unclear mail (max 1)aiTrim(boolean): The AI finds the main text of a long received mail (over 1500 characters) the rules could not trim (default false)blockedExtensions(array of string): Default: executables and scriptsbulkPolicy(string): Newsletters and bulk mail: drop (default) or make a ticket (one ofdrop,ticket)foreignSubjectMatch(boolean): A [#N] subject token appends mail of senders who are no participantfromName(string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one ofagentWithMailbox,agent,mailbox)maxAttachmentBytes(integer): Per file, default 20 MB, max. 40 MBmaxTotalBytes(integer): Per mail, default 35 MB, max. 40 MBperSender10min(integer): Above: appended quietly (default 10)perSenderHour(integer): Above: held in the mail log (default 30)
priorityMatrix(object): Priority from impact and urgencycells(object): "|" → priority keyimpacts(array of object): Impact levelskey(string): Key of the levellabel(string): Label of the level
urgencies(array of object): Urgency levelskey(string): Key of the levellabel(string): Label of the level
time(object): No longer used: rules for time entries and hourly billing (self approval, hour unit, tax rate, traffic light) are HR's work settings (ADR 0040); ignored on write and no longer returned
Example 200 answer:
{
"ai": {
"features": {
"summary": {
"auto": true,
"autoApply": true,
"enabled": true,
"threshold": 0.8
},
"triage": {
"auto": true,
"autoApply": false,
"enabled": true,
"threshold": 0.85
}
}
},
"callbacks": {
"fields": [],
"note": {
"aiCheck": false,
"minLength": 10,
"required": true
},
"statusMail": [
{
"mode": "manual",
"status": "not_reached",
"text": "nicht-erreicht"
}
]
},
"mail": {
"aiClassify": true,
"aiThreshold": 0.8,
"aiTrim": true,
"blockedExtensions": [
"exe",
"bat",
"js"
],
"bulkPolicy": "drop",
"foreignSubjectMatch": false,
"fromName": "agentWithMailbox",
"maxAttachmentBytes": 20971520,
"maxTotalBytes": 31457280,
"perSender10min": 10,
"perSenderHour": 30
},
"priorityMatrix": {
"cells": {
"gering|hoch": "normal",
"gering|mittel": "niedrig",
"gering|niedrig": "niedrig",
"hoch|hoch": "kritisch",
"hoch|mittel": "hoch",
"hoch|niedrig": "hoch",
"mittel|hoch": "hoch",
"mittel|mittel": "normal",
"mittel|niedrig": "normal"
},
"impacts": [
{
"key": "gering",
"label": "Gering"
},
{
"key": "mittel",
"label": "Mittel"
},
{
"key": "hoch",
"label": "Hoch"
}
],
"urgencies": [
{
"key": "niedrig",
"label": "Niedrig"
},
{
"key": "mittel",
"label": "Mittel"
},
{
"key": "hoch",
"label": "Hoch"
}
]
}
}
Example request
curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/settings' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"callbacks":{"note":{"aiCheck":false,"minLength":10,"required":true}},"mail":{"aiClassify":true,"aiThreshold":0.8,"aiTrim":true,"blockedExtensions":["exe","bat","js"],"bulkPolicy":"drop","fromName":"agentWithMailbox","maxAttachmentBytes":20971520,"maxTotalBytes":31457280,"perSender10min":10,"perSenderHour":30}}'