Set up Shopify product search and recommendations
A connected Shopify store supplies product information to omotto. The catalog setup controls how that information is understood, searched and presented. It does not edit your products in Shopify.
How it works
Section titled “How it works”| Layer | What it is for |
|---|---|
| Synced product information | A searchable copy of product names, descriptions, types, tags, collections, buying options and selected extra fields. |
| Catalog brief | A generated overview of the catalog’s categories, terminology and positioning. It is not a list of every product. |
| Operator notes | Your durable corrections and extra catalog guidance. They take priority over the generated brief when they conflict. |
| Product fields | Your choice of extra product information that may be used in customer conversations. |
| Search index | Meaning-based search: finding products from a customer’s description rather than only matching exact words. Availability depends on your plan. |
| Live product details | A fresh Shopify check of the shortlisted products, including price and availability, when Shopify can respond. |
A good brief does not mean the search index is built. Likewise, a built index does not make an incorrect product description correct. Fix product facts in Shopify; use the notes and explanations for context.
Shopify calls extra information attached to a product or variant metafields. A variant is one combination of buying choices, such as a blue shirt in medium. See Shopify’s guides to metafields and variants.
Semantic search means meaning-based search. For example, a shopper might describe a use or need instead of knowing your product name. It depends on the product information available, not just the brief.
Where to find it
Section titled “Where to find it”Open Handbook → What [assistant name] knows → Integrations for Catalog brief and Operator notes. The heading uses your bot’s name. Product fields, Search index and Pricing market are in Settings → Integrations → Shopify → Technical setup. A link in the Handbook catalog editor opens that setup screen. Open What [assistant name] does when… for browsing, selling and best-seller instructions; connection management is separate.
If an integration manager cannot edit the brief in the Handbook, the same brief and notes remain editable on Technical setup. A reader without Handbook access can see them read-only there; Handbook readers do not get a duplicate read-only copy on Technical setup.
Set it up
Section titled “Set it up”Start with connecting Shopify. For discounts, refunds and other order actions, use Shopify actions and approvals. Those permissions are separate from catalog setup.
Changing the brief or notes in the Handbook requires both Handbook editing and integration-management permission. Editing on Technical setup still requires integration-management permission. Editing the behavior rules requires Handbook editing and bot-settings permission. If controls are unavailable, ask your workspace owner to check your permissions.
Review the brief
Section titled “Review the brief”- Open Catalog brief in the location above.
- Read the generated overview.
- Choose Generate from catalog if no brief exists or you want a fresh one.
- Add lasting corrections under Operator notes.
- Wait for saving to finish in the top bar.
Choose product fields
Section titled “Choose product fields”- Open Product fields.
- Find a field by its name and example.
- Turn on Use this field in its Use column if it is safe to share with customers.
- Enter a short Explanation of what the field means and how its values should be understood.
- Wait for saving to finish in the top bar.
Review every visible switch: automatic setup may already have selected some fields.
Check the search index
Section titled “Check the search index”- Open Search index.
- Wait if Preparing your first index build… or Building index… is displayed.
- Choose Build semantic index if no build is running and the index is not ready.
- Wait for Semantic search active and Active.
After a later change, use Refresh index if you need a full refresh now.
Reveal capability controls
Section titled “Reveal capability controls”- Open the Handbook’s When section in the location above.
- Find Browse catalog, Present & sell products or Best sellers. Use Show beside Unchanged rules if needed.
- Open the rule by clicking its When or Then cell.
- Review Instructions, then Who is this for and its Required verification. These edit the skill’s existing requirement, not a second independent setting.
- For Goal-driven posture or Visual product cards, expand Present & sell products specifically.
- Test your setup in a rehearsal.
Settings
Section titled “Settings”Catalog brief and operator notes
Section titled “Catalog brief and operator notes”| Control | What it does | Starting state or behavior |
|---|---|---|
| Generate from catalog | Generates and replaces the current brief from the store’s catalog. | A brief is normally generated after connection. The button shows Generating… while running. |
| Copy | Copies the generated brief. | Appears beside an existing brief. |
| Operator notes | Adds your authoritative catalog knowledge without editing the generated brief. | Blank initially; saves automatically as you type. |
| Clear brief | Removes only the generated brief after confirmation. | Your notes are kept. You can generate another brief later. |
The generated brief is read-only. For example, use Operator notes to explain a category name or a business-specific distinction that the overview missed. Do not use notes to invent a price, stock level or product property that is absent from the store.
Pricing market
Section titled “Pricing market”| Option | Meaning |
|---|---|
| Use default | The initial choice. Follows the workspace language: Hebrew defaults to Israel; otherwise there is no country-specific default and store-base pricing is used. |
| Israel | Sets Israel as the workspace’s fallback pricing market. |
This is a fallback, not a rule forcing every shopper into one market. A customer-specific market used for the product lookup takes priority.
Prices come from Shopify’s market pricing. omotto does not perform its own currency conversion. The final amount is the amount shown at checkout. Configure the actual prices in Shopify; see Shopify’s international pricing guide.
Product fields and explanations
Section titled “Product fields and explanations”The table shows Name, Slug (the field’s identifier), Example, Use and Explanation. Read the example before enabling a field.
| Group | What it contains | Can it be switched off? |
|---|---|---|
| Standard fields | Optional vendor and search-engine title/description information. | Yes. |
| Product metafields | Extra facts attached to the whole product, such as ingredients or care instructions. | Yes. |
| Variant metafields | Extra facts attached to individual buying combinations. Treat different values as choices, not one property that every version shares. | Yes. |
| Variant options | Structural buying choices, such as size or colour. | No. Marked always on. You can explain their meaning. |
Optional fields start off when discovered, but automatic setup may select some for you. Automatically selected rows carry an AI-picked badge. The visible switches are the current selection; review them all.
Explanation is editable only for enabled optional fields. For Variant options, it is always available to a manager. Explanations may be marked auto-drafted or edited by you. Your edited explanations are not replaced by automatic suggestions.
For example, explain whether a “servings” value is a suggested serving count or a package count. An explanation supplies meaning; it does not change the product’s stored value.
Only enable information you are willing to share with customers. Do not enable internal costs, margins, supplier notes or other private operational information. Buying options themselves are always shared; this table is not a way to hide size or colour choices. Nor does turning off an extra field remove information already written into a product’s public description.
Search index controls and status
Section titled “Search index controls and status”| Control or status | Meaning |
|---|---|
| Build semantic index | Starts the first build, or a new build after clearing or failure. Requires a connected store and a plan that includes semantic search. |
| Refresh index | Runs the build again for an already-ready index, pulling current catalog data. |
| Building index… | Work is in progress. Build and clear controls are unavailable during it. |
| Clear index | After confirmation, removes meaning-based search data. Synced product information and Shopify products are kept. Rebuild to restore semantic search. |
| products indexed | Products held in the synced catalog. |
| embedded | Products prepared for meaning-based search. This can differ from the synced count. |
| changed since the last full build | Changes since the full-build baseline; not proof that every change is still awaiting processing. |
| Last full build | Time of the last completed full build, not the time of every individual product update. |
Semantic search and catalog capacity depend on your plan and usage allowance. Without semantic search, product lookups use Shopify’s live word-based search. Upgrading alone is not a substitute for checking that the index was built.
Browsing, selling, cards and best sellers
Section titled “Browsing, selling, cards and best sellers”Expand the relevant capability as described in setup. These controls do not replace catalog setup.
| Setting | Purpose and default |
|---|---|
| Browse catalog | Product search, availability and pricing questions. Enabled by default. |
| Present & sell products | Product presentation and checkout links. Enabled by default. |
| Visual product cards | Inside the expanded Present & sell products capability. On by default. Allows product image cards with price and a link. Off uses text and product links instead; it does not disable checkout links. |
| Best sellers | Off by default. Enables read-only ranking of popular products, separately from ordinary search. |
| Instructions | Inside each expanded capability. Changes its conversational guidance. An empty custom value uses its built-in guidance. |
The built-in browsing guidance favours a short category overview for broad questions and specific products when relevant. Selling guidance favours brief presentation and checkout when a customer is ready, rather than a checkout link on every mention. Instructions are guidance, not a guarantee that every conversation will follow an identical script.
Present & sell products also has Goal-driven posture. Its default is Inherit — follows your Motivation setting. Reactive means waiting for a request; Opportunistic uses natural openings; Proactive steers toward the goal; Persistent pursues it throughout the conversation and can feel pushy. It takes effect only when a Motivation is set. See personality and motivation settings for the wider setting.
Customer verification
Section titled “Customer verification”Browse catalog, Present & sell products and Best sellers each have a separate Verification section in their expanded controls. This concerns proof from the customer, not your staff’s workspace permissions.
| Setting | Options and behavior | Default for these three capabilities |
|---|---|---|
| Required verification | Default uses the capability’s built-in requirement. No verification asks for no customer proof. Resource verified requires proof tied to the specific order or record being accessed. Identity verified requires proof of the customer’s identity rather than only one record. | Default (No verification). Browsing, selling and best-seller ranking require no customer verification unless you change this. |
| Proof recency | Default uses the built-in recency. Any time accepts older proof. This conversation requires proof in the current chat. Within a set time requires proof within the number of minutes you enter; enter at least 1 minute. Recency matters when verification is required. | Default (Any time). |
| When verification applies | Automatic uses the capability’s built-in timing. At the action lets the bot explain the capability, but checks proof when it performs a lookup, presents products or prepares checkout. From the start also withholds the capability’s instructions until the customer meets the requirement. | Automatic (At the action). |
| Who may approve | Select an offered staff audience: a role, custom role, person, group, people with a particular permission, or Entire organization. This limits who may sign off where approval is needed; it does not itself make browsing or ranking require staff approval. See Shopify actions and approvals. | No restriction (channel-native): no additional audience restriction. |
The selections save automatically. With Within a set time, enter the minutes and leave the field to save. Once proof is older than that window, a protected action can require a fresh verification code, including for WhatsApp customers who were otherwise verified automatically.
Choose the requirement for each capability deliberately. Turning a capability on does not bypass verification. A requirement tied to a particular record is not interchangeable with general identity proof and can be unsuitable for public catalog browsing.
What happens when…
Section titled “What happens when…”You connect for the first time
Section titled “You connect for the first time”Connecting Shopify starts catalog-brief generation. Setup can also draft field explanations and preselect customer-facing extra fields. On an eligible plan, the first search-index build is then started automatically. A second manual build is not needed while Preparing your first index build… is displayed.
The summary shows Finish catalog setup while setup is incomplete. Once complete, it shows catalog status, a product count and Last synced. That time reflects the full index build, not every individual product update. The individual sections remain available for later changes.
You change catalog content or settings
Section titled “You change catalog content or settings”| Change | What happens |
|---|---|
| Ordinary Shopify product creation, update or deletion | Product changes update the local catalog automatically. Existing indexes also have an overnight reconciliation to catch missed changes. |
| Changes to collection membership, extra field values or buying options | Do not assume every detail arrives with an ordinary product update. A full Refresh index or overnight reconciliation retrieves these details. |
| Turning an optional field on or off | A built, eligible index applies the changed field selection automatically after a few minutes. Refresh index offers a manual shortcut. |
| Editing an Explanation or Operator notes | Saves the guidance without starting an index rebuild. |
| Changing Pricing market | Saves automatically and schedules a refresh for a connected, already-built index. It does not create a first index by itself. |
| Editing only translations or the set of published languages | May need the next full refresh or overnight reconciliation. Do not assume every translation-only edit is immediately visible. |
| Choosing Generate from catalog | Refreshes the brief, not the search index. |
A pending custom-fields message means the field selection and the last built index differ. Wait for the automatic update or refresh manually. If no index has ever been built, field switches do not build one on their own.
A new field defined in Shopify is discovered when the connected catalog settings are loaded again. Seeing no custom fields is not an error if the store has none; standard fields can still appear.
You regenerate or clear the brief or index
Section titled “You regenerate or clear the brief or index”Notes survive regeneration and clearing of the brief. You can still edit them while reconnecting the store. Save status appears in the top bar; a failed save needs attention before you leave.
Catalog changes can make the brief stale. A warning offers regeneration now; changed catalogs are also checked for automatic brief refresh overnight. Manually generating a new brief does not rebuild the product-search index.
Clear brief and Clear index are independent. Neither deletes products from Shopify. Clearing the index does not erase the brief or notes, and regenerating the brief does not restore a cleared index.
A customer uses another language
Section titled “A customer uses another language”Where access is available, omotto also reads existing Shopify translations: product names, descriptions, enabled text fields, and option names and values. Search can consider these translations. Presentation uses an available translation matching the customer’s language, with the original wording as fallback for missing content.
Create and maintain those translations in Shopify, for example with Translate & Adapt. Catalog sync does not create missing merchant translations for you. Tags are not translated by this feature.
If the connection screen asks you to reconnect for catalog translations, complete the Shopify reconnection. The original-language catalog remains usable while translation access is missing.
A product comes up again
Section titled “A product comes up again”A product already shown as a card in the current ticket normally does not receive another card. A ticket is the current customer request being handled. Repeat recommendations may use text and product links instead, even with both selling and visual cards enabled. If the customer explicitly asks to see the product again, another card is allowed. The same product is still not repeated twice as cards in one reply.
A customer is ready to buy
Section titled “A customer is ready to buy”Product cards are a presentation choice, not proof that a product has been purchased. Checkout links carry the selected items and quantities; customers complete the purchase in Shopify. A new checkout link replaces the previous selection rather than adding to an earlier link. The selling flow calls for confirmation of quantity and, for products with multiple variants, the exact buying option before preparing checkout. See actions and approvals for financial permissions.
A customer wants to replace an item in an existing order
Section titled “A customer wants to replace an item in an existing order”Catalog search can help find the exact product and buying option. A product card or checkout link does not change an existing order. That requires the Change an order action, off initially with its own switch, plus the ownership proof required for that kind of change. Item changes default to proof of the customer’s own store account. There is no separate Order changes switch. Review the change preview, money limits and approvals rather than using a new checkout link as an order-edit confirmation.
You enable best sellers
Section titled “You enable best sellers”Best sellers supports all-time ranking or a chosen period. It returns ranked products, not sales or revenue totals. If Best sellers: reporting permission required appears, the store owner should choose Grant reporting permission and complete the Shopify approval. Enabling the capability alone does not grant store-report access. If ranking is unavailable, ordinary product search is not evidence of which products sold best.
Troubleshooting
Section titled “Troubleshooting”- No catalog or disconnected store: check the Shopify connection first.
- A broad description finds poor matches: check that semantic search is active, product descriptions are useful, and relevant customer-safe fields are enabled. Refresh the index after correcting store data.
- A new custom field is absent: reload the connected catalog settings to discover it. Then review its switch and explanation.
- The brief is out of date: choose Generate from catalog. Refreshing the index is a different action.
- Some products are synced but not prepared for search: check the displayed counts and your plan’s catalog allowance. Retry a failed build; contact support if it keeps failing.
- A build or generation fails: try again after checking the connection and plan. If usage is exhausted, wait for the allowance to renew. If the problem repeats, contact omotto support with the visible status.
- A price or availability answer looks old: search uses synced candidates, then normally checks the chosen products live. If Shopify cannot be reached, stored values can be returned instead. Check the product in Shopify; checkout remains the final price authority.
- You cannot find instructions, verification or visual cards: expand the capability using its row’s arrow. Visual cards and goal-driven posture are inside Present & sell products.
- An enabled capability still asks for verification or cannot act: check that capability’s Required verification, Proof recency and When verification applies. The enabled switch does not remove the customer-proof requirement.
- Cards are missing but links work: check Present & sell products and its expanded Visual product cards setting. A product already carded in the current ticket normally uses text or links unless the customer asks to see it again; this is expected, not necessarily a configuration problem. Cards and checkout are separate from browsing.
- A translation is missing: check that it exists in Shopify, its language is published, access is approved, and a full refresh has run since the change.
For support, include the product name, what you expected, the question you tested, and the catalog status. Never send passwords or store connection secrets.