## Unread starting from a message

`POST /v1/chats/messages/:messageId/unread`

Makes the given message the first unread one in a dialog, without marking the whole chat unread the way the chat-level mark does.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `messageId` (path) | number | yes | Message ID, a positive integer — the `id` field of a message from the [message history](/docs/chats/messages/list) or [chat loading](/docs/chats/messages/load) |

There are no query parameters: any parameter is refused with `400 INVALID_PARAMS`.

## Request body fields

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `dialogId` | string \| number | yes | The dialog that holds the message: `chatXXX` for a group chat, a user ID for a personal one, `me` for the current user's personal dialog. `chatXXX` is the `id` field of a [recent dialogs](/docs/chats/discovery/recent) row, a user ID comes from the [user list](/docs/entities/users/list) |

Other body fields are refused with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1001/unread" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dialogId": "chat42" }'
```

### curl — OAuth application

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

### JavaScript — personal key

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

const { success } = await res.json()
console.log('Mark set:', success)
```

### JavaScript — OAuth application

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

const { success } = await res.json()
console.log('Mark set:', success)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | boolean | `true` — the mark is set |

## Response example

```json
{
  "success": true,
  "data": true
}
```

## Error response example

404 — the message is not in the given dialog:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Message is not in the specified dialog. Nothing was changed."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `messageId` is not a positive integer or equals `9007199254740991`, `dialogId` is missing or does not look like a user ID, `chatXXX` or `me`, or another body field or a query parameter was sent. Checked before any Bitrix24 call |
| 401 | `MISSING_API_KEY` | `X-Api-Key` was not sent |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |
| 403 | `SCOPE_DENIED` | The API key lacks the `im` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only. Checked before any Bitrix24 call |
| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access |
| 404 | `ENTITY_NOT_FOUND` | The message is not in the given dialog or belongs to another dialog. The mark is not set |
| 422 | `BITRIX_ERROR` | Bitrix24 refused the operation. The refusal text is in `error.message` |
| 429 | `RATE_LIMITED` | The Bitrix24 request limit was exceeded. Retry after the pause in the `Retry-After` header |
| 502 | `ME_ALIAS_RESOLUTION_FAILED` | The current user could not be determined for `me` |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable, returned a server error or did not confirm the mark |
| 503 | `BITRIX_TIMEOUT` | Bitrix24 did not respond in time, and it is unknown whether the mark was set. Retry after the pause in the `Retry-After` header |

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

## Known specifics

Messages and chats have three different marks — pick the one that fits the task:

| Route | Action |
|---|---|
| [`POST /v1/chats/:dialogId/unread`](/docs/chats/management/unread-create) | Mark the whole chat unread |
| [`POST /v1/chats/messages/:messageId/mark`](/docs/chats/messages/mark) | A "read later" pointer. It does not move an existing mark |
| `POST /v1/chats/messages/:messageId/unread` | Make the message the first unread one in the given dialog |

## See also

- [Set the "unread" mark](/docs/chats/management/unread-create)
- [Read later](/docs/chats/messages/mark)
- [Messages](/docs/chats/messages)
- [Errors](/docs/errors)