Списки#

Методы этого раздела создают и удаляют списки, меняют их поля и ведут записи: добавляют, читают, изменяют и удаляют. Например, сайт может сам пополнять список «Меню кофейни», а бот — показывать его людям.

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

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

• Схема — название списка и его поля. С ней работают методы на странице Списки и поля. В названиях методов схема так и называется: getListSchema, createListSchema.
• Записи — строки списка со значениями полей. С ними работают методы на странице Записи.

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

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

slug — это имя поля в подстановках: под ним значение лежит в записи и под ним же его читают блоки бота. Поля, созданные в кабинете, получают его автоматически; через API вы задаёте его сами.

Типы полей#

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

Пустое поле приходит в ответе как 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 в него можно записать только ссылку на файл, который лежит в интернете:

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

Внимание

Без "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. Если в списке несколько таких полей, там окажется значение последнего из них.

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

Важно

По умолчанию поле, созданное через 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.

Методы#