## Create a callback (desk:write)

`POST /api/desk/v1/callbacks`

Module: Desk · operationId: `createCallback` · Tag: Callbacks · Auth: access token (`Authorization: Bearer <accessToken>`)

The status is the `callbackStatus` entry with the `default` flag unless `status` names one; the responsible
person defaults to the caller; `responsibleRef: ""` creates it without one (the pool of unassigned callbacks,
`scope=unassigned`), and nobody is notified. The responsible person gets the notification
`desk.callback_notice` unless they created it themselves. Custom fields are those of `settings.callbacks.fields`
(`customFields`, keys without `cf.`).

The note must satisfy the tenant's note rules (`settings.callbacks.note`): required, minimum length, pattern
(each 400 `invalid`, field `note`, with a message for the person) and the optional AI check (422 `note_rejected`,
the message is the hint). The AI check never blocks when the AI is unavailable. A callback created in a status
with a customer mail behaves like a status change into it (`customerMail`, see `POST /callbacks/{id}/status`).

### Request body

`application/json` (required)

- `clearDesiredAt` (boolean): Removes the desired time
- `contact` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `contactName` (string): ≤ 200 characters
- `customFields` (object): Values of the custom fields of the callback form by key
- `customer` (Ref): Reference into another system (masterdata, ERP) with a name snapshot.
  - `id` (string, required): Id in the other system
  - `name` (string, required): Name at the time of the reference
  - `extra` (object): Further facts of the referenced record
- `desiredAt` (string (date-time)): When the contact wants to be called back
- `desiredHasTime` (boolean): desiredAt carries a time of day (false: only the date counts)
- `doneNote` (string): ≤ 10000 characters
- `note` (string): ≤ 10000 characters
- `origin` (string): Create only (ignored on change): the activity it is made from, `comms:interaction:<id>` or `comms:calendar:<id>` (400 otherwise); Arbeitsplatz › Aktivitäten „Rückruf anlegen“
- `phone` (string): Required on create; digits, a leading +, spaces and ( ) / - . (≤ 40)
- `reason` (string): Key of a callbackReason entry
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref; absent or null on create: the caller; "" = nobody (the pool of unassigned callbacks; on change it unassigns)
- `status` (string): Create only: a callbackStatus key (default: the default entry)
- `version` (integer): Required on change

Example:

```json
{
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleRef": "elias.gruber@muster-it.example"
}
```

### Responses

- **201** Created; `customerMail` is set when its status has a customer mail (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **422** note_rejected: the AI check refused the note (the message is the hint) (`application/json`)

Fields of the 201 answer:

- `closed` (boolean, read-only): The status carries the closed flag
- `closedAt` (string (date-time), nullable): When the callback was closed
- `closedBy` (string): Login (e-mail) of who closed the callback
- `contact` (object): Masterdata contact snapshot (only with a customer)
- `contactName` (string): Name of the person to call back
- `convertedAt` (string (date-time), nullable): When the callback was turned into a ticket
- `createdAt` (string (date-time)): When the callback was created
- `createdBy` (string): Login (e-mail) of who created the callback
- `createdByName` (string): Name of who created the callback
- `customFields` (object): Values of the fields of settings.callbacks.fields, keyed without cf.
- `customer` (object): Masterdata address snapshot
- `customerMail` (object): Only in the answer of a create or status change into a status with a customer mail: the draft of a manual mail; for an automatic one the mail as queued (`mode` `auto`, no `missing`) or, when it was not sent, why (`missing`). Never on reads.
- `desiredAt` (string (date-time), nullable): When the contact wants to be called back
- `desiredHasTime` (boolean): false: only the day of desiredAt counts
- `doneNote` (string): Result of the call
- `id` (string (uuid)): Id of the callback
- `item` (ItemSummary)
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `phase` (Phase): (one of `new`, `active`, `waiting`, `done`)
  - `spaceId` (string): Space of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
- `itemId` (string, nullable): The ticket it became
- `note` (string): Note of the callback
- `number` (integer): Per tenant
- `origin` (string): The call it was made from in Arbeitsplatz › Aktivitäten (`comms:interaction:<id>`, `comms:calendar:<id>`); "" none
- `overdue` (boolean, read-only): Open and the desired time (without time: the desired day) has passed
- `phone` (string): Phone number to call back
- `reason` (string): Key of a callbackReason entry, "" = none
- `responsibleName` (string): Name of the person responsible
- `responsibleRef` (string): User ref of the person who calls back; "" = nobody yet (the pool of unassigned callbacks)
- `status` (string): Key of a callbackStatus entry
- `updatedAt` (string (date-time)): When the callback was last changed
- `version` (integer): Version of the callback; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

```json
{
  "closed": false,
  "contact": {
    "id": "6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11",
    "name": "Katrin Stadler"
  },
  "contactName": "Katrin Stadler",
  "createdAt": "2026-11-17T15:20:00Z",
  "createdBy": "sophie.huber@muster-it.example",
  "createdByName": "Sophie Huber",
  "customFields": {},
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11",
    "name": "Alpenhotel Seeblick GmbH \u0026 Co. KG"
  },
  "desiredAt": "2026-11-19T08:00:00Z",
  "desiredHasTime": true,
  "doneNote": "",
  "id": "7b4c5d6e-8f9a-4b0c-9d2e-4f5a6b7c8d01",
  "itemId": "",
  "note": "Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.",
  "number": 12,
  "origin": "",
  "overdue": false,
  "phone": "+49 8652 987612",
  "reason": "callback_requested",
  "responsibleName": "Elias Gruber",
  "responsibleRef": "elias.gruber@muster-it.example",
  "status": "open",
  "updatedAt": "2026-11-17T15:20:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/callbacks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"contact":{"id":"6b8d0f2a-4c6e-4a8b-9d1f-3a5c7e9b1d11","name":"Katrin Stadler"},"contactName":"Katrin Stadler","customer":{"id":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c11","name":"Alpenhotel Seeblick GmbH \u0026 Co. KG"},"desiredAt":"2026-11-19T08:00:00Z","desiredHasTime":true,"note":"Frau Stadler möchte kurz zur Kassenanbindung sprechen, bevor die Frühschicht beginnt.","phone":"+49 8652 987612","reason":"callback_requested","responsibleRef":"elias.gruber@muster-it.example"}'
```
