Патерни та приклади Custom Data

Custom Data дозволяє зберігати свої дані (довідники, рейтинги, заявки) і використовувати їх у сценаріях. Але як саме? Список магазинів, C-SAT після діалогу, заявки на зворотний дзвінок, імпорт з зовнішніх таблиць — це різні сценарії. Документ описує шість типових варіантів і допоможе обрати потрібний.

Коли використовувати Custom Data

Custom Data призначено для:

Довідників та каталогів (магазини, міста, категорії)
Доменних сутностей (C-SAT, feedback, заявки на інтерв'ю)
Синхронізації з зовнішніми системами (CRM, Google Sheets)
Дашбордів Metabase/аналітики

Client Fields (/settings-page/client-fields) — для розширення таблиці Клієнтів кастомними полями. Для нових проєктів використовуйте Client Fields замість Custom Data з «розширенням контактів».

User Fields (/settings-page/user-fields) — для розширення профілів операторів. Використовуйте User Fields замість Custom Data для полів операторів.

Складні кейси: Custom Data підтримує розширені налаштування — графіки, валідацію, кольорову підсвітку, карту, слайдер фото. Якщо ваш сценарій потребує такого, дивіться Складні кейси Custom Data та довідник розширених налаштувань.

Патерн 1: CRUD (get/set/update)

Задача: Зберігати та читати доменні дані у сценарії (довідники, опитування, заявки).

Дії в сценарії: custom_modules__get, custom_modules__set, custom_modules__update

Приклади:

Домен	Поля моделі	Приклад послідовності
Довідник магазинів	city, address, lang_code	Користувач обирає місто → get за filters → показ магазинів
C-SAT / feedback	chat_id, rating, created_at	Після опитування → set → використання в Metabase
Заявки на інтерв'ю	id, interview_date, interview_time, status	Користувач обирає дату/час → set → оператор обробляє
VIP-список	email, phone, nickname, vip_status	get за email/phone → показ VIP-переваг або стандартний сценарій

Патерн 2: Довідники для роутингу

Задача: Користувач обирає зі списку (наприклад, місто) → сценарій показує відповідні варіанти (магазини) і роутить до потрібної гілки.

Послідовність: get → клавіатура → get за фільтром → повідомлення

Приклад:

get — завантажити магазини за lang_code (або всі)
Custom action або keyboard — витягнути унікальні міста
Message with Keyboard — користувач обирає місто
get — завантажити магазини за фільтром city
Message — показати магазини для обраного міста

Приклад моделі: stores — city (STRING), address (STRING), lang_code (STRING)

Патерн 3: Callback ID → запис

Задача: Показати список записів як inline-кнопки. При натисканні кнопки завантажити повний запис і продовжити сценарій з його даними.

Послідовність: завантажити список → згенерувати inline-кнопки (у кожній callback_data = id запису) → при натисканні викликати дію inline_call_back → отримати запис за id

Приклад:

Модель interview_requests — id, interview_date, interview_time, status
Користувач бачить список заявок як inline-кнопки
Кожна кнопка має callback_data = id запису
При натисканні → inline_call_back завантажує запис → сценарій продовжує з повними даними

Патерн 4: Видалення після завершення

Задача: Видалити запис після завершення процесу (інтерв'ю проведено, зворотний дзвінок оброблено), щоб список залишався актуальним.

Послідовність: custom action deleteInstance з instance_id, який збережено в стані сценарію

Приклад:

Модель interview_requests
Після завершення інтерв'ю оператором → custom action видаляє запис за id
Список залишається чистим

Патерн 5: Імпорт з Google Sheets

Задача: Синхронізувати категорії або інші дані з Google Sheets у Custom Data, щоб не вводити їх вручну.

Послідовність: custom action google_sheets_fetch_data — читає діапазон з таблиці, очищає модель і додає нові записи

Приклад:

Модель categories — колонки A:E відповідають структурі Sheets
Параметри action: spreadsheetId, sheetName, range, customDataTableName
Використання для AI-категоризації або довідників роутингу

Патерн 6: Metabase / аналітика

Задача: Використовувати Custom Data як джерело для дашбордів Metabase (кастомна метрика, середній рейтинг, метрики за період).

Послідовність: сценарій записує дані через custom_modules__set → Metabase читає їх через SQL або API

Приклад:

Модель c_sat — chat_id, rating, created_at, bot_id
Після C-SAT опитування → set record
Дашборди Metabase: CSAT за період, середній рейтинг

Підсумкова таблиця

Патерн	Дії в сценарії	Типове використання
CRUD	get, set, update	Довідники, feedback, заявки
Довідники для роутингу	get, keyboard	Місто → магазини, категорії
Callback ID → запис	inline_call_back	Inline-кнопки з id записів
Видалення після завершення	deleteInstance	Очищення після процесу
Імпорт з Google Sheets	google_sheets_fetch_data	Синхронізація категорій з Sheets
Metabase/аналітика	set	C-SAT, метрики в дашбордах

Пов'язані документи

Що таке Custom Data — загальні принципи та концепції
Складні кейси Custom Data — графіки, валідація, підсвітка, карта
Як отримати запис з Custom Data — інструкція з дією custom_modules__get
Як створити запис у Custom Data — інструкція з дією custom_modules__set
Як розширити контакти клієнта — для нових проєктів краще використовувати Client Fields