## Set the status of a callback (desk:write)

`POST /api/desk/v1/callbacks/{id}/status`

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

Any status may follow any other (also reopening a closed one); a closed status stamps `closedAt`/`closedBy`,
an open one clears them. A converted callback keeps its status (409 `converted`). An open callback may move to
its own status again (one more try, e.g. not reached again): a new version, a history line `status_changed`
with `from` = `to` and the status's customer mail as for any move into it; a closed callback moving to its own
status is 422 `same_status`.

Customer mail: when `settings.callbacks.statusMail` ties a text to the new status, the move triggers the mail to the
callback's contact. In mode `auto` the mail is queued in the same transaction (once per move into the status;
history `customer_mail`) and the answer's `customerMail` has `mode` `auto` and no `missing`; when it could not be
sent `customerMail.missing` says why (history `customer_mail_skipped`; the status change succeeds anyway). In mode `manual` nothing is sent and
the answer's `customerMail` is the rendered draft for the client to show; send it with
`POST /callbacks/{id}/customer-mail`.

### Parameters

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

### Request body

`application/json` (required)

- `status` (string, required): Key of a callbackStatus entry
- `version` (integer, required)
- `doneNote` (string): Result of the call (≤ 10000 characters)

Example:

```json
{
  "doneNote": "Kassenanbindung besprochen; Termin vor Ort am Freitag vereinbart.",
  "status": "done",
  "version": 2
}
```

### Responses

- **200** Updated; `customerMail` is set when the new status has a customer mail (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** version_conflict or converted (`application/json`)
- **422** same_status: a closed callback moved to its own status (`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 POST 'https://api.mbcom.cloud/api/desk/v1/callbacks/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/status' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"doneNote":"Kassenanbindung besprochen; Termin vor Ort am Freitag vereinbart.","status":"done","version":2}'
```
