Custom Data Patterns and Examples

When designing a bot scenario with Custom Data, you need to choose the right approach: CRUD, catalogs for routing, inline buttons, or import from a spreadsheet? This document describes six common patterns based on real scenarios. Use it to quickly pick the right option and understand the sequence of steps.

When to Use Custom Data

Custom Data is for:

Catalogs and directories (stores, cities, categories)
Domain entities (C-SAT, feedback, interview requests)
Sync with external systems (CRM, Google Sheets)
Metabase/analytics dashboards

Client Fields (/settings-page/client-fields) is for extending the Clients table with custom fields. Use Client Fields for new projects instead of Custom Data with "extend contacts".

User Fields (/settings-page/user-fields) is for extending operator profiles. Use User Fields instead of Custom Data for operator fields.

Advanced cases: Custom Data supports advanced settings — charts, validation, row highlighting, map, image slider. If your scenario needs this, see Advanced Custom Data Cases and the advanced options reference.

Pattern 1: CRUD (get/set/update)

Task: Store and read domain data in scenarios (catalogs, surveys, requests).

Scenario actions: custom_modules__get, custom_modules__set, custom_modules__update

Examples:

Domain	Model fields	Example flow
Stores catalog	city, address, lang_code	User selects city → get by filters → show stores
C-SAT / feedback	chat_id, rating, created_at	After survey → set record → use in Metabase
Interview requests	id, interview_date, interview_time, status	User selects date/time → set → operator processes
VIP list	email, phone, nickname, vip_status	get by email/phone → show VIP benefits or standard flow

Pattern 2: Catalogs for Routing

Task: User selects from a list (e.g. city) → scenario shows matching options (stores) and routes to the right branch.

Sequence: get → keyboard → get by filter → message

Example:

get — load stores by lang_code (or all stores)
Custom action or keyboard — extract unique cities from result
Message with Keyboard — user selects city
get — load stores by city filter
Message — show stores for selected city

Model example: stores — city (STRING), address (STRING), lang_code (STRING)

Pattern 3: Callback ID → Record

Task: Show a list of records as inline buttons. On click, load the full record and continue the scenario with its data.

Sequence: load list → generate inline buttons (each has callback_data = record id) → on click → call action inline_call_back → get record by id

Example:

Model interview_requests — id, interview_date, interview_time, status
User sees list of requests as inline buttons
Each button has callback_data = id of the record
On click → inline_call_back loads record → scenario continues with full data

Pattern 4: Delete After Completion

Task: Remove record after process is done (interview completed, callback handled) so the list stays up to date.

Sequence: custom action deleteInstance with instance_id saved in scenario state

Example:

Model interview_requests
After operator completes interview → custom action deletes record by id
Keeps list clean

Pattern 5: Import from Google Sheets

Task: Sync categories or other data from Google Sheets into Custom Data so you don't have to enter them manually.

Sequence: custom action google_sheets_fetch_data — reads range from sheet, clears model, adds new records

Example:

Model categories — columns A:E match Sheets structure
Action params: spreadsheetId, sheetName, range, customDataTableName
Use for AI categorization or routing catalogs

Pattern 6: Metabase / Analytics

Task: Use Custom Data as source for Metabase dashboards (CSAT, average rating, metrics by period).

Sequence: scenario writes data via custom_modules__set → Metabase reads from SQL or API

Example:

Model c_sat — chat_id, rating, created_at, bot_id
After C-SAT survey → set record
Metabase dashboards: CSAT by period, average rating

Summary Table

Pattern	Actions	Typical use
CRUD	get, set, update	Catalogs, feedback, requests
Catalogs for routing	get, keyboard	City → stores, categories
Callback ID → record	inline_call_back	Inline buttons with record IDs
Delete after completion	deleteInstance	Clean up after process
Google Sheets import	google_sheets_fetch_data	Sync categories from Sheets
Metabase/analytics	set	C-SAT, metrics dashboards

What is Custom Data — concepts and principles
Advanced Custom Data Cases — charts, validation, highlighting, map
How to get a record from Custom Data — step-by-step guide for custom_modules__get
How to create a record in Custom Data — step-by-step guide for custom_modules__set
How to extend client contacts — prefer Client Fields for new projects