ConnectCloud Developers

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): "|" → 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:

{
  "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): "|" → 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:

{
  "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}}'

View as Markdown · Interactive reference · OpenAPI