ConnectCloud Developers

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:

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

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

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

View as Markdown · Interactive reference · OpenAPI