## Список наборов стикеров

`GET /v1/chats/stickers/packs`

Возвращает наборы стикеров текущего пользователя постранично: сначала пользовательские `custom`, затем встроенные `vendor`. Чтобы получить следующую страницу, передайте `id` и `type` последнего набора предыдущей страницы.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|----------|
| `limit` | number | нет | Наборов на странице: по умолчанию 10, от 1 до 200. Значение вне диапазона приводится к границе, исходное и применённое значения возвращаются в `meta` |
| `lastId` | number | нет | Курсор: `id` последнего набора предыдущей страницы. Передаётся только вместе с `lastType` |
| `lastType` | string | нет | Курсор: `type` последнего набора предыдущей страницы — `vendor` или `custom`. Передаётся только вместе с `lastId` |

Без курсора возвращается первая страница. Другие параметры, повторный параметр или только одна половина курсора отклоняются с `400 INVALID_PARAMS` до обращения в Битрикс24.

## Примеры

### curl — личный ключ

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/stickers/packs?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/stickers/packs?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/stickers/packs?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Наборов:', data.packs.length, 'есть ещё:', data.hasNextPage)
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/stickers/packs?limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Наборов:', data.packs.length, 'есть ещё:', data.hasNextPage)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.packs` | array | Наборы страницы |
| `data.packs[].id` | number | ID набора. Уникален только вместе с `type`. Передаётся как `packId` в [получение набора](/docs/chats/stickers/pack-get) |
| `data.packs[].type` | string | `custom` — набор пользователя, `vendor` — встроенный набор |
| `data.packs[].name` | string | Название набора |
| `data.packs[].authorId` | number \| null | ID автора пользовательского набора, у встроенного — `null`. Профиль — по [ID пользователя](/docs/entities/users/get) |
| `data.packs[].isAdded` | boolean | Набор есть в списке пользователя |
| `data.stickers` | array | Стикеры наборов страницы, а на первой странице — и недавних стикеров |
| `data.stickers[].id` | number | ID стикера — для [удаления стикеров из набора](/docs/chats/stickers/pack-stickers) |
| `data.stickers[].packId` | number | ID набора стикера — совпадает с `data.packs[].id` |
| `data.stickers[].packType` | string | Вид набора стикера |
| `data.stickers[].uri` | string | Путь к картинке на портале Битрикс24 — относительный, без домена |
| `data.stickers[].type` | string | Тип стикера (`image`) |
| `data.stickers[].width` | number | Ширина картинки в пикселях |
| `data.stickers[].height` | number | Высота картинки в пикселях |
| `data.stickers[].sort` | number | Порядок стикера в наборе |
| `data.recentStickers` | array | Только на первой странице: недавно отправленные стикеры пользователя, не больше 12, новые первыми — `{ id, packId, packType }` |
| `data.hasNextPage` | boolean | Есть следующая страница |
| `meta.requestedLimit` | number | Переданный `limit` — только если он был приведён к границе |
| `meta.appliedLimit` | number | Применённый `limit` — только если он был приведён к границе |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "stickers": [
      { "id": 1, "uri": "/upload/im/stickers/3/1.png", "type": "image", "width": 512, "height": 512, "packId": 3, "packType": "custom", "sort": 1 },
      { "id": 2, "uri": "/bitrix/images/im/stickers/aiHelp/2.png?v1", "type": "image", "width": 512, "height": 512, "packId": 14, "packType": "vendor", "sort": 2 }
    ],
    "packs": [
      { "id": 3, "name": "Рабочие стикеры", "type": "custom", "authorId": 7, "isAdded": true },
      { "id": 14, "name": "ИИ, помоги", "type": "vendor", "authorId": null, "isAdded": true }
    ],
    "recentStickers": [
      { "id": 2, "packId": 14, "packType": "vendor" }
    ],
    "hasNextPage": true
  }
}
```

## Пример ответа при ошибке

400 — передана только половина курсора:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`lastId` needs `lastType`: pass the `id` and the `type` of the last pack of the previous page together."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Передан неизвестный параметр запроса |
| 400 | `INVALID_PARAMS` | Параметр передан больше одного раза |
| 400 | `INVALID_PARAMS` | `limit` не целое число |
| 400 | `INVALID_PARAMS` | `lastId` передан без `lastType` |
| 400 | `INVALID_PARAMS` | `lastType` передан без `lastId` |
| 400 | `INVALID_PARAMS` | `lastId` не положительное целое |
| 400 | `INVALID_PARAMS` | `lastType` не `vendor` и не `custom` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения запросил первую страницу — без `lastId` и `lastType`. Страница с курсором доступна и такому ключу |
| 404 | `ENTITY_NOT_FOUND` | Битрикс24 не нашёл объект. Код портала — в `error.b24Code`, если он был передан |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку. Код портала — в `error.b24Code` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ошибку сервера |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

- Последняя страница может оказаться пустой — с `hasNextPage: false`.
- Если набор-курсор удалили или убрали из своего списка между запросами, выдача пользовательских наборов начинается заново. Снимайте повторы по паре `type` и `id`.
- `recentStickers` приходит только на первой странице. Первый запрос удаляет строки недавних стикеров сверх 12. Поэтому он считается записью: ключ только для чтения получает `403 WRITE_BLOCKED_READONLY_KEY` до вызова Битрикс24. Страницы с курсором остаются чтением.
- `uri` — путь на портале Битрикс24. Полный адрес картинки — домен портала плюс `uri`.

## Смотрите также

- [Получить набор](/docs/chats/stickers/pack-get)
- [Недавние стикеры](/docs/chats/stickers/recent)
- [Стикеры](/docs/chats/stickers)