Structured Data

Import product catalogs, price lists, and service menus from spreadsheets or an API so your agent gives precise answers

Structured Data#

Structured Data lets you provide organized business information -- such as product catalogs, service menus, and price lists -- so your agent can give precise, accurate answers about specific items, prices, and availability.

What Is Structured Data?#

Unlike regular documents or text sources, Structured Data is organized information in a table format. Each row represents a specific item (a product, service, menu item, etc.) with defined attributes like name, price, description, and availability.

This means your agent does not guess about prices or product details -- it looks up the exact information from your data.

Common examples:

• Product catalogs with names, descriptions, and prices
• Service offerings with pricing tiers
• Restaurant or cafe menus
• Team member directories
• Location or branch information

How It Works#

1. Import: Upload a spreadsheet, pick one from Google Drive, or connect an API endpoint
2. Map: Define what each column represents
3. Index: Each row is indexed so your agent can look up specific items
4. Answer: When a customer asks about a specific product or service, the agent finds the exact match and responds with accurate data

Adding Structured Data#

There are three ways to bring in structured data.

File Upload#

1. Go to your agent's dashboard
2. Click Sources in the sidebar, then open Structured Data
3. Click Add Data Source
4. Select File Upload and choose a spreadsheet (XLSX, XLS, or CSV)
5. Map each column to a data field (name, price, description, category, etc.)
6. Save and train your agent

Google Drive#

1. Click Add Data Source and select Google Drive
2. Connect your Google account (if not already connected)
3. Pick a spreadsheet using the Google Picker
4. Map each column to a data field
5. Save and train your agent

API Endpoint#

1. Click Add Data Source and select API endpoint
2. Enter the endpoint URL that returns your data
3. Map the returned fields to data fields
4. Set a sync frequency so the data stays current

Filter Current Live Data#

For a connected Google Sheet or API, Live Data Lookup can answer normal customer questions across multiple current rows. You do not need to write formulas or code.

Set it up once:

1. Connect the Google Sheet or API
2. Confirm the column names and detected types
3. Enable Live Data Lookup

The agent can then combine filters, sort the results, and return a short matching list.

For a table with Travel Start and Travel End, a customer can ask, "Which packages include December 5?" AlonChat checks that the start is on or before December 5 and the end is on or after December 5. The customer and owner do not need to build those conditions.

Normal chat builds those conditions from the customer's question. For deterministic automation, the same capability is available without code:

• In a Procedure, add the Live Data source with @Look up live data, then configure its conditions below the Procedure steps. A value can be fixed or come from a customer detail the Procedure collected.
• In a Workflow, add Run an action, choose Live Data Lookup, and configure the source, match-all or match-any conditions, sorting, maximum results, and returned fields. Values can come from a captured answer, contact field, contact attribute, or a guaranteed earlier Tool result.
• Workflow results are saved under the result name (for example, matching_packages) so later steps can use matchCount, matches, hasMore, and the returned row fields.

Use Match all for combinations such as travel start on/before the requested date and travel end on/after it. Use Match any when either condition is acceptable.

For reliable results:

• Keep one record per row
• Use consistent date values, preferably YYYY-MM-DD
• Keep number columns numeric apart from a consistent currency label
• Use consistent yes/no or true/false values
• Correct a detected column type in Configure if it is wrong

Live filtering reads refreshable Google Sheet and API sources. Uploaded spreadsheets are static snapshots and do not provide current-row filtering. Results can be cached briefly, and very large sources have a bounded scan, so split sources larger than 50,000 rows when complete counts are important.

Data Types and Use Cases#

Spreadsheet Best Practices#

Spreadsheet Format#

Good spreadsheet structure:

| Name            | Price  | Description              | Category    | Available |
|-----------------|--------|--------------------------|-------------|-----------|
| Haircut         | ₱500   | Standard haircut         | Services    | Yes       |
| Coloring        | ₱1,800 | Full hair coloring       | Services    | Yes       |
| Solo Package    | ₱700   | One haircut and styling  | Packages    | Yes       |
| Family Package  | ₱2,500 | Four haircuts and styling| Packages    | Yes       |

Tips for good data:

• Use clear, descriptive column headers in the first row
• Keep one type of data per sheet
• Use consistent formatting (e.g., always "$30" not sometimes "30 dollars")
• Include all relevant details your customers might ask about
• Mark items as available or unavailable

What to Avoid#

• Merged cells (they break column mapping)
• Multiple unrelated tables on one sheet
• Empty rows in the middle of your data
• Abbreviations without explanation
• Leaving important fields blank

Syncing Data#

Structured Data can be synced automatically to stay up-to-date:

1. Click Configure Sync on your data source
2. Set a sync frequency: Manual (default), Hourly, Every 6 hours, Daily, or Weekly
3. AlonChat pulls the latest data from your source on schedule

When you update prices or add new products in your source, your agent picks up the changes at the next sync. With Manual, you trigger a sync yourself whenever you want to refresh.

Example Conversations#

Product Lookup#

Customer: "What's the price of the Blue Widget?" Agent: Looks up the exact price from your product catalog and responds with accurate information.

Service Inquiry#

Customer: "How much does a consultation cost?" Agent: Retrieves the exact pricing from your service list.

Menu Question#

Customer: "What pizzas do you have and how much are they?" Agent: Lists available pizzas with current prices from your menu data.

Comparison#

Customer: "What's included in the family package versus the solo package?" Agent: Compares inclusions and prices using your structured package data.

Best Practices#

Do:

• Use clear column headers that describe the data
• Keep data up-to-date (especially prices and availability)
• Include all relevant details customers might ask about
• Use consistent formatting across all rows
• Set up automatic syncing for frequently changing data

Don't:

• Leave important fields empty
• Duplicate entries across multiple sheets
• Use abbreviations your customers would not understand
• Forget to sync after updating your spreadsheet

Troubleshooting#

"Agent giving wrong prices"#

• Check that your source has the latest prices
• Verify the sync ran recently (check last sync time)
• Trigger a manual sync and retrain

"Agent can't find a product"#

• Verify the product exists in your spreadsheet
• Check that the column mapping is correct
• Make sure the row is not hidden or filtered out in the sheet

"Sync failed"#

• Re-authorize your Google account connection
• Check that the spreadsheet has not been deleted or moved
• Verify sharing permissions on the spreadsheet

Next Steps#

• Time-Sensitive Content -- Add promotions and events with expiration dates
• Q&A Sources -- Create specific Q&A pairs
• Sources Overview -- All source types at a glance