# Списки

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

## Як влаштований список

Список складається з двох частин:

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

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

## Ідентифікатори

| Що | Як виглядає | Де взяти |
|---|---|---|
| Список (`schema_id`, `id` у відповідях) | Рядок із 24 символів: `6650a1f2c3d4e5f6a7b8c9d0` | Відповіді `getListSchemas` і `createListSchema` |
| Запис (`item_id`, `id` у відповідях) | Рядок із 24 символів, як у списку | Відповіді `getListItems` і `addListItem` |
| Поле (`slug`) | Літери, цифри, `-` і `_`, краще латиницею: `tsina` | Ключі об'єкта `fields` у відповіді `getListSchema` |
| Проєкт (`project_uuid`, `project` у відповідях) | UUID: `3f2b8c1e-…` | Адреса проєкту в кабінеті: `/projects/<uuid>/…` |
| Бот (`bot_id`) | Число | Адреса бота в кабінеті: `/bots/12345/…` |
| Контакт | Число | Методи контактів |

`slug` — це [ім'я поля в підстановках](https://support.watbot.org/uk/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` | «Грошовий» | Суму в гривнях, доларах тощо: `65` або `129.99` | Суму в тих самих одиницях: `65` |
| `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: `UAH`, `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.org/uk/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) | Видалити запис |