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 createname(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 valuestatus(string): active or disabled (one ofactive,disabled)
Example:
{
"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. Kindteams(read-only):teamName,channelNameandconversationType(channelorgroupChat); the conversation's Teams ids stay in comms.createdAt(string (date-time)): Creation timecreatedBy(string): Who created the channelid(string (uuid)): Channel idisDefault(boolean): The tenant's default e-mail channelkind(string): Channel kind (see ChannelKind.kind)lastCheckAt(string (date-time)): Time of the last connection testlastCheckOk(boolean): Result of the last connection testlastError(string): Error of the last connection testmedium(string): push is the platform channel that fans out to the devices of a person (ADR 0043); no caller routes to it (one ofemail,webhook,teams,push)name(string): Display namerev(integer): Revision for optimistic locking (send it back asrev)secrets(object): Which secret fields are set; values are never returnedstatus(string): active channels send; disabled ones do not (one ofactive,disabled)updatedAt(string (date-time)): Time of the last change
Example 200 answer:
{
"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
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"}'