# Списки

Методы этого раздела создают и удаляют [списки](https://support.watbot.ru/lists), меняют их поля и ведут записи: добавляют, читают, изменяют и удаляют. Например, сайт может сам пополнять список «Меню кофейни», а бот — показывать его людям.

## Как устроен список

Список состоит из двух частей:

- **Схема** — название списка и его поля. С ней работают методы на странице [Списки и поля](https://support.watbot.ru/api/lists/schemas). В названиях методов схема так и называется: `getListSchema`, `createListSchema`.
- **Записи** — строки списка со значениями полей. С ними работают методы на странице [Записи](https://support.watbot.ru/api/lists/items).

Списки принадлежат проекту. Создать список можно в проекте или в боте — тогда он тоже попадает в проект этого бота. Через API доступны все списки проектов, владелец которых — хозяин ключа: и созданные в ботах, и созданные прямо в проекте.

## Идентификаторы

| Что | Как выглядит | Где взять |
|---|---|---|
| Список (`schema_id`, `id` в ответах) | Строка из 24 символов: `6650a1f2c3d4e5f6a7b8c9d0` | Ответы `getListSchemas` и `createListSchema` |
| Запись (`item_id`, `id` в ответах) | Строка из 24 символов, как у списка | Ответы `getListItems` и `addListItem` |
| Поле (`slug`) | Буквы, цифры, `-` и `_`, лучше латиницей: `price` | Ключи объекта `fields` в ответе `getListSchema` |
| Проект (`project_uuid`, `project` в ответах) | UUID: `3f2b8c1e-…` | Адрес проекта в кабинете: `/projects/<uuid>/…` |
| Бот (`bot_id`) | Число | Адрес бота в кабинете: `/bots/12345/…` |
| Контакт | Число | Методы контактов |

`slug` — это [имя поля в подстановках](https://support.watbot.ru/lists/create#имя-поля-в-подстановках): под ним значение лежит в записи и под ним же его читают блоки бота. Поля, созданные в кабинете, получают его автоматически; через API вы задаёте его сами.

## Типы полей

Тип задаётся при создании поля в параметре `type` и потом не меняется.

| `type` | Тип в кабинете | Что передавать | Что приходит в ответе |
|---|---|---|---|
| `string` | «Текст» | Строку | Строку |
| `number` | «Число» | Число или строку с числом: `12`, `"4.5"` | Число |
| `bool` | «Логический» | `true` или `false` (подойдут и `1`, `0`) | `true` или `false` |
| `date` | «Дата» | Дату в любом понятном формате: `"2026-10-15"` | Дату и время в UTC: `"2026-10-15T00:00:00.000000Z"` |
| `datetime` | «Дата и время» | Дату и время: `"2026-10-15 14:30"` или `"2026-10-15T14:30:00+03:00"` | Дату и время в UTC |
| `money` | «Денежный» | Сумму в рублях, долларах и т. п.: `350` или `199.99` | Сумму в тех же единицах: `350` |
| `file` | «Файл» | Объект со ссылкой — см. ниже | Объект с описанием файла |
| `image` | «Картинка» | Объект со ссылкой — см. ниже | Объект с описанием файла |
| `contact` | «ID контакта» | Номер контакта | Номер контакта |
| `bot` | «ID бота» | Номер бота | Номер бота |

Пустое поле приходит в ответе как `null`.

### Дата и время

Время без часового пояса считается временем UTC: `"2026-10-15 14:30"` сохранится как 14:30 UTC. Чтобы передать местное время, укажите пояс: `"2026-10-15T14:30:00+03:00"`. Поле `date` время не обрезает: если передать дату со временем, время сохранится.

### Деньги

Валюта задаётся у поля при его создании (`currency`) и в записи не передаётся. Это трёхбуквенный код по ISO 4217: `RUB`, `USD`, `EUR`. В `createListSchema` валюту можно не указывать — тогда `USD`; в `addListSchemaField` она обязательна. Неизвестный код — `422`.

Сумму передавайте в основных единицах — рублях, а не копейках. Она округляется до знаков валюты (у рубля и доллара — два), половина — в большую сторону: `0.295` сохранится как `0.30`.

### Файлы и картинки

Значение поля `file` или `image` — объект. Через API в него можно записать только ссылку на файл, который лежит в интернете:

```json
{
  "url": "https://example.com/menu/cappuccino.jpg",
  "storage": "url",
  "name": "cappuccino.jpg",
  "type": "image"
}
```

| Ключ | Обязательный | Описание |
|---|---|---|
| `url` | да | Ссылка `http://` или `https://` |
| `storage` | да | Всегда `"url"` |
| `name` | нет | Имя файла |
| `type` | нет | Вид файла: `image`, `video`, `audio` или `document` |
| `mime_type` | нет | MIME-тип: `image/jpeg` |
| `size` | нет | Размер в байтах |
| `caption` | нет | Подпись |

> [!WARNING]
> Без `"storage": "url"` или со ссылкой другого вида (не `http`/`https`) значение молча не сохранится — в поле окажется `null`, ошибки не будет.

Другие ключи (например, `uuid` или `path`) игнорируются: в поле сохраняется только внешняя ссылка, и в ответе она приходит такой же, какой её передали. Ссылку на файл из хранилища платформы — ту, что приходит в ответах на файлы, загруженные в кабинете, — можно записать только в пределах своего аккаунта; ссылка на файл другого аккаунта не сохранится — в поле окажется `null`. Если в `updateListItem` передать файл, который уже лежит в записи, например целую запись из `getListItems`, он останется как был.

В ответе файл описан объектом с ключами `type`, `mime_type`, `created_at`, `name`, `size`, `storage`, `caption`, `meta` (ширина, высота, длительность, кодек) и `url`. Ссылки на файлы, загруженные в кабинете, — временные: скачивайте файл сразу или запрашивайте запись заново.

### Контакт и бот

В поля `contact` и `bot` передают номер. Контакт должен принадлежать вашему боту, бот — вам: иначе ответ `403`. Несуществующий номер не пройдёт проверку — `422`.

Кроме значения самого поля, запись получает служебные `contact_id` или `bot_id` — по ним работает отбор в [`getListItems`](10-items.md#getlistitems). Если в списке несколько таких полей, там окажется значение последнего из них.

## Настройки поля

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `is_required` | логический | `true` | «Обязательность заполнения поля»: без значения запись не добавится |
| `is_hidden` | логический | `false` | «Скрыть поле из интерфейса»: поля не видно в таблице записей кабинета. API отдаёт его как обычно |
| `is_encryptable` | логический | `false` | «Зашифровать поле»: значение хранится зашифрованным. API отдаёт его расшифрованным. В кабинете шифрование есть только у типов `string` и `number` — ставьте его только им. По зашифрованным полям не работают фильтры |

> [!IMPORTANT]
> По умолчанию поле, созданное через API, обязательное — в отличие от кабинета. Если поле можно оставлять пустым, передайте `"is_required": false`.

## Ограничения

- В проекте — не больше 5000 списков.
- При создании списка — от 1 до 30 полей.
- Название списка и поля — до 255 символов.
- Нельзя использовать служебные имена полей: `id`, `_id`, `contact`, `contact_id`, `bot`, `bot_id`, `user`, `user_id`, `project`, `project_id`, `data`, `schema_id`, `created_at`, `updated_at`, `deleted_at` и любые имена, которые начинаются с `__`. На такой `slug` API ответит `422` с текстом «The slug is reserved.».

Общие правила — ключ, частота запросов, коды ошибок — описаны на странице [API](https://support.watbot.ru/api#ошибки).

## Методы

| Метод | Что делает |
|---|---|
| [`getListSchemas`](05-schemas.md#getlistschemas) | Все списки ваших проектов |
| [`getListSchema`](05-schemas.md#getlistschema) | Один список с полями |
| [`createListSchema`](05-schemas.md#createlistschema) | Создать список |
| [`deleteListSchema`](05-schemas.md#deletelistschema) | Удалить список |
| [`addListSchemaField`](05-schemas.md#addlistschemafield) | Добавить поле |
| [`deleteListSchemaField`](05-schemas.md#deletelistschemafield) | Удалить поле |
| [`getListItems`](10-items.md#getlistitems) | Записи списка с отбором и сортировкой |
| [`addListItem`](10-items.md#addlistitem) | Добавить запись |
| [`updateListItem`](10-items.md#updatelistitem) | Изменить запись |
| [`deleteListItem`](10-items.md#deletelistitem) | Удалить запись |