## Comment on the tickets linked to a ticket (desk:write, agent role)

`POST /api/desk/v1/items/{ref}/linked-comments`

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

Adds `body` as a comment (`visibility` internal by default; a public one is mailed to that ticket's requesters) to every ticket linked to this one – only links of `linkType` and `direction` (`outgoing`: this ticket is the link's source, `incoming`: its target, `any`: both) when set. Each linked ticket gets it once; merged tickets, tombstones, tickets the caller cannot comment on and – for an automation of a space – tickets of other spaces are left out and counted in `skipped`. One of the single steps automations and flows take on a ticket (ADR 0044): it needs neither the ticket's version nor its whole list. History, outbox, SLA and automations follow as for every change; a converted ticket is 409 `converted`.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `ref` | path | string | yes | Item id or number |

### Request body

`application/json` (required)

- `body` (string, required): The comment
- `direction` (string): Only links from this ticket (outgoing) or to it (incoming); any (default): both (one of `any`, `outgoing`, `incoming`)
- `linkType` (string): Only links of this type (key of a linkType entry)
- `visibility` (string): internal by default (one of `internal`, `public`)

Example:

```json
{
  "body": "Ursache gefunden: Der PoE-Switch im 2. OG wird heute getauscht.",
  "direction": "incoming",
  "linkType": "caused_by",
  "visibility": "internal"
}
```

### Responses

- **200** How many linked tickets got the comment (`application/json`)
- **400** Error (`application/json`)
- **403** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)
- **422** Error (`application/json`)

Fields of the 200 answer:

- `commented` (integer, required): Linked tickets that got the comment
- `skipped` (integer, required): Linked tickets left out (merged, read-only, not commentable for the caller, outside an automation's space)

Example 200 answer:

```json
{
  "commented": 2,
  "skipped": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/string/linked-comments' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"body":"Ursache gefunden: Der PoE-Switch im 2. OG wird heute getauscht.","direction":"incoming","linkType":"caused_by","visibility":"internal"}'
```
