## Change a channel (comms:admin)

`PATCH /api/comms/v1/channels/{id}`

Module: Comms · operationId: `updateChannel` · Tag: Channels · Auth: access token (`Authorization: Bearer <accessToken>`)

Empty fields keep their value; secrets sent empty or as `********` keep the stored secret.

### Parameters

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

### Request body

`application/json` (required)

- `config` (object): The kind's configuration fields (FieldSpec keys that are not secret)
- `kind` (string): Only on create
- `name` (string): Display name (max length 80)
- `rev` (integer): Optimistic lock (0 skips the check)
- `secrets` (object): The kind's secret fields; empty or ******** keeps the stored value
- `status` (string): active or disabled (one of `active`, `disabled`)

Example:

```json
{
  "config": {
    "format": "teams_card"
  },
  "kind": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 0,
  "secrets": {
    "url": "https://muster-it.webhook.office.example/workflows/servicedesk"
  },
  "status": "active"
}
```

### Responses

- **200** Channel (`application/json`)
- **400** Error (`application/json`)
- **404** Error (`application/json`)
- **409** Error (`application/json`)

Fields of the 200 answer:

- `config` (object): The kind's public configuration. Kind `teams` (read-only): `teamName`, `channelName` and `conversationType` (`channel` or `groupChat`); the conversation's Teams ids stay in comms.
- `createdAt` (string (date-time)): Creation time
- `createdBy` (string): Who created the channel
- `id` (string (uuid)): Channel id
- `isDefault` (boolean): The tenant's default e-mail channel
- `kind` (string): Channel kind (see ChannelKind.kind)
- `lastCheckAt` (string (date-time)): Time of the last connection test
- `lastCheckOk` (boolean): Result of the last connection test
- `lastError` (string): Error of the last connection test
- `medium` (string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one of `email`, `webhook`, `teams`, `push`)
- `name` (string): Display name
- `rev` (integer): Revision for optimistic locking (send it back as `rev`)
- `secrets` (object): Which secret fields are set; values are never returned
- `status` (string): active channels send; disabled ones do not (one of `active`, `disabled`)
- `updatedAt` (string (date-time)): Time of the last change

Example 200 answer:

```json
{
  "config": {
    "format": "teams_card"
  },
  "createdAt": "2026-09-03T14:05:11Z",
  "createdBy": "sophie.huber@muster-it.example",
  "id": "9c4e2b7a-1d3f-4a6b-8c5d-2e7f9a1b3c4d",
  "isDefault": false,
  "kind": "webhook",
  "lastCheckAt": "2026-11-16T08:12:40Z",
  "lastCheckOk": true,
  "medium": "webhook",
  "name": "Teams-Kanal Service Desk",
  "rev": 2,
  "secrets": {
    "signingSecret": true,
    "url": true
  },
  "status": "active",
  "updatedAt": "2026-11-16T08:12:40Z"
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/comms/v1/channels/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"config":{"format":"teams_card"},"kind":"webhook","name":"Teams-Kanal Service Desk","rev":0,"secrets":{"url":"https://muster-it.webhook.office.example/workflows/servicedesk"},"status":"active"}'
```
