## 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 with `autoApply` applies each proposed value that reaches `threshold` and 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); with `autoApply` it 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. `mailTexts` and `statusMail`: absent = the defaults (a manual mail text for the status `not_reached`, while that status exists), `[]` = none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the mode `auto`.
  - `fields` (array of object): Custom fields of the callback form in order
    - `key` (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 _; unique
    - `name` (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 (422 `note_rejected` with a hint); an unavailable AI accepts the note
    - `minLength` (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 of `manual`, `auto`)
    - `status` (string, required): Key of a callbackStatus entry, once
    - `text` (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 aiThreshold
  - `aiThreshold` (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 scripts
  - `bulkPolicy` (string): Newsletters and bulk mail: drop (default) or make a ticket (one of `drop`, `ticket`)
  - `foreignSubjectMatch` (boolean): A [#N] subject token appends mail of senders who are no participant
  - `fromName` (string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one of `agentWithMailbox`, `agent`, `mailbox`)
  - `maxAttachmentBytes` (integer): Per file, default 20 MB, max. 40 MB
  - `maxTotalBytes` (integer): Per mail, default 35 MB, max. 40 MB
  - `perSender10min` (integer): Above: appended quietly (default 10)
  - `perSenderHour` (integer): Above: held in the mail log (default 30)
- `priorityMatrix` (object): Priority from impact and urgency
  - `cells` (object): "<impact>|<urgency>" → priority key
  - `impacts` (array of object): Impact levels
    - `key` (string): Key of the level
    - `label` (string): Label of the level
  - `urgencies` (array of object): Urgency levels
    - `key` (string): Key of the level
    - `label` (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:

```json
{
  "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 with `autoApply` applies each proposed value that reaches `threshold` and 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); with `autoApply` it 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. `mailTexts` and `statusMail`: absent = the defaults (a manual mail text for the status `not_reached`, while that status exists), `[]` = none; the defaults apply only while both are absent. Nothing is sent automatically unless a status mail has the mode `auto`.
  - `fields` (array of object): Custom fields of the callback form in order
    - `key` (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 _; unique
    - `name` (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 (422 `note_rejected` with a hint); an unavailable AI accepts the note
    - `minLength` (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 of `manual`, `auto`)
    - `status` (string, required): Key of a callbackStatus entry, once
    - `text` (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 aiThreshold
  - `aiThreshold` (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 scripts
  - `bulkPolicy` (string): Newsletters and bulk mail: drop (default) or make a ticket (one of `drop`, `ticket`)
  - `foreignSubjectMatch` (boolean): A [#N] subject token appends mail of senders who are no participant
  - `fromName` (string): Sender name of answers: "Anna Agent (Support)" (default), "Anna Agent" or "Support" (one of `agentWithMailbox`, `agent`, `mailbox`)
  - `maxAttachmentBytes` (integer): Per file, default 20 MB, max. 40 MB
  - `maxTotalBytes` (integer): Per mail, default 35 MB, max. 40 MB
  - `perSender10min` (integer): Above: appended quietly (default 10)
  - `perSenderHour` (integer): Above: held in the mail log (default 30)
- `priorityMatrix` (object): Priority from impact and urgency
  - `cells` (object): "<impact>|<urgency>" → priority key
  - `impacts` (array of object): Impact levels
    - `key` (string): Key of the level
    - `label` (string): Label of the level
  - `urgencies` (array of object): Urgency levels
    - `key` (string): Key of the level
    - `label` (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:

```json
{
  "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

```bash
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}}'
```
