## Chat notifications

`POST /v1/chats/:chatId/mute`

Turns chat notifications off or back on for the user the call is made on behalf of. Other chat participants are not affected.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `chatId` (path) | number | yes | Chat ID (positive integer). A CRM entity chat is found via [Find a CRM entity chat](/docs/chats/discovery/find) |
| `mute` | boolean | yes | `true` turns notifications off, `false` turns them back on |

`MUTE` with the value `"Y"` or `"N"` is accepted instead of `mute`, as Bitrix24 spells it. Other body fields are not forwarded.

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/chats/456/mute \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mute": false}'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/chats/456/mute \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mute": false}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/456/mute', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mute: false }),
})

const { success, data } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/456/mute', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mute: false }),
})

const { success, data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.chatId` | number | Chat ID from the request |
| `data.muted` | boolean | The state that was set: `true` means notifications are off, `false` means they are on |

## Response example

```json
{
  "success": true,
  "data": {
    "chatId": 456,
    "muted": false
  }
}
```

## Error response example

400 — the body has no `mute` field:

```json
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Body field `mute` (boolean) is required: true switches the chat notifications off, false switches them back on."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_CHAT_ID` | `chatId` is not a positive integer — checked before the Bitrix24 call |
| 400 | `MISSING_PARAMS` | The body has no `mute`, including a request without a body. Nothing is sent to Bitrix24 |
| 400 | `INVALID_PARAMS` | `mute` is not `true` / `false`, and `MUTE` is not `"Y"` / `"N"`. Nothing is sent to Bitrix24 |
| 404 | `CHAT_NOT_FOUND_OR_NO_ACCESS` | The chat does not exist, the user is not a member, or notifications for this chat cannot be turned off |
| 403 | `SCOPE_DENIED` | The API key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only — changing notification settings counts as a write |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**The setting is personal.** Notifications change only for the user the call is made on behalf of. With a personal key, that is the key owner. To change the setting for an employee who opened your application, call the endpoint with the application key and that employee's `vibe_session_*` session in the `Authorization` header, as in the OAuth application examples. An administrator key cannot turn notifications off on someone else's behalf.

**An employee session lasts 24 hours.** A `vibe_session_*` session appears when the employee opens the application and stays valid for a day. If your application reacts to a Bitrix24 event, such as an observer being added to a task, an employee who has not opened the application recently has no valid session, and a call on their behalf fails. Change the setting at the moment the employee opens the application.

**`mute` is required.** The field is never guessed: a request without it is refused before the Bitrix24 call. This way a request that lost the field does not turn notifications off when it meant to turn them on.

## See also

- [Leave a chat](/docs/chats/management/leave)
- [Find a CRM entity chat](/docs/chats/discovery/find)
- [Chat management](/docs/chats/management)