## Change a callback at its version (desk:write)

`PATCH /api/desk/v1/callbacks/{id}`

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

Present keys are applied (`clearDesiredAt: true` removes the desired time); `version` is required. The status
changes through `POST /callbacks/{id}/status` (`status` here is 400). A closed callback takes only `doneNote`
(409 `callback_closed`), a converted one too (409 `converted`). A new responsible person (another than the
caller) gets the notification – also when an unassigned callback is assigned; `responsibleRef: ""` puts it back
into the pool (history and outbox `assigned`, no notification). A changed `note` is checked against the note
rules like on create (400 `invalid` on field `note`, 422 `note_rejected`); an unchanged note is not checked again.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes |  |

### 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
{
  "desiredAt": "2026-11-19T12:00:00Z",
  "responsibleRef": "",
  "version": 1
}
```

### Responses

- **200** Updated (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict, callback_closed or converted (`application/json`)
- **422** note_rejected: the AI check refused the changed note (the message is the hint) (`application/json`)

Fields of the 200 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 200 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 PATCH 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"desiredAt":"2026-11-19T12:00:00Z","responsibleRef":"","version":1}'
```
