Documentation - sommelier.bot

Step 1

Your Catalogue

1

Send Us Your Shop Link

All we need to start is the link to your website or online shop. We take your catalogue from there and index it within 48 hours.

Source	Details	Updates
Shop link	The address of your website or online shop. Nothing else to prepare.	Set up by us
XML Product Feed (optional)	A hosted URL with your active products in XML format (Google Merchant / Shopify / WooCommerce compatible). See the specification below.	Automatic: re-synced every night at 3 AM
CSV / Excel (optional)	A spreadsheet with columns: Product Name, Producer, Price, URL, Image URL, Description, Color, Region, Varietal, Format (L).	One-time import

A product feed is optional. If you have one, your catalogue stays in sync on its own: new products, price changes and sold-out wines are handled every night.

Send your shop link (and your feed URL, if you have one) to support@sommelier.bot.

2

Optional: Create Your XML Product Feed

Your XML Product Feed is a URL hosted on your website, containing all your active products in a structured XML format. The sommelier.bot system calls this URL every night at 3 AM to sync your latest inventory.

✚

New product in feed

Added to your sommelier.bot inventory. Can be tagged and activated from the CMS.

✖

Product removed from feed

Considered out of stock. Deactivated automatically, but stays in your CMS.

↻

Product details updated

Name, price, description, link, and image URL are updated automatically.

Compatible with Google Shopping feeds. If you already have a Google Merchant Center product feed, it works with sommelier.bot, same XML format.

3

XML Feed Fields Reference

Your XML feed must follow this structure, using the <rss> / <channel> / <item> hierarchy. Each "item" is one product.

<product_id> required Your unique product identifier (numbers and/or letters, special characters allowed, no spaces). Example: 45425007NM-75LCT06

<name> required Product name with vintage and appellation. Example: 2017 Domaine de la Romanee-Conti La Tache Grand Cru

<producer> optional Name of the producer. Example: Vallis Mareni

<image_url> required Complete URL to the product image on your website.

<price> required Product price. Format: XXXX.XX: no comma, no space, no currency sign. Example: 12.00

<country> optional Country of production. ISO format recommended but not mandatory (e.g., CH, FR, US).

<varietal> optional Grape varietal(s), comma-separated, no spaces. Example: Pinot Noir,Chardonnay

<region> optional Region of production. Example: Burgundy, Vénétie

<format> optional Bottle format in Liters (not cl). Example: 0.75, 1.50, 3.00

<description> optional Product description text paragraph.

<color> optional Wine color. Example: red, white, rosé, sparkling, orange, fortified

<sorting> optional Important: Priority level from 0 (lowest) to 10 (highest), controls recommendation priority to promote your deals, best-sellers, best margin wines.

4

XML Feed Example

Here is a complete example with two products:

<?xml version="1.0"?> <rss lang="en"> <channel> <item> <product_id>45425007NM-75LCT06</product_id> <name>Monte Corbino Brut</name> <producer>Vallis Mareni</producer> <link><![CDATA[https://www.yourshop.com/monte-corbino-brut?utm_source=sommelier-bot&utm_medium=chat]]></link> <image_url>https://www.yourshop.com/media/monte-corbino.png</image_url> <color>sparkling</color> <varietals>Prosecco (Glera)</varietals> <price>12.00</price> <country>IT</country> <region>Veneto</region> <format>0.75</format> <organic>organic,biodynamic</organic> <sorting>10</sorting> </item> <item> <product_id>45425007NM-75LCT07</product_id> <name>Monte Corbino Brut Magnum</name> <producer>Vallis Mareni</producer> <link><![CDATA[https://www.yourshop.com/monte-corbino-brut-magnum?utm_source=sommelier-bot&utm_medium=chat]]></link> <image_url>https://www.yourshop.com/media/monte-corbino-magnum.png</image_url> <color>sparkling</color> <varietals>Prosecco (Glera)</varietals> <price>24.00</price> <country>IT</country> <region>Veneto</region> <format>1.50</format> <sorting>0</sorting> <sweetness>Sweet</sweetness> </item> </channel> </rss>

Final step: Add your XML Product Feed URL in your sommelier.bot CMS (one URL per language you want to support). Go to your admin interface to paste the URL.

Want more? Upgrade to a paid plan to install the AI sommelier directly on your website, with pop-up chat, contextual banners, and full-page embeds that drive conversions on your own store.

Step 2

Widget Integration

Your custom sommelier.bot is ready. Below is everything you need to install the AI sommelier on your website: pop-up chat, full-page embeds, and on-click triggers. Each requires a single line of JavaScript.

1

A. Access Your sommelier.bot CMS

Your management dashboard is where you configure languages, customize the widget, and grab your embed codes.

Go to https://business.sommelier.bot/
Log in with the credentials provided in your welcome email.
Change your temporary password immediately after first login.

From the CMS, navigate to Playground to configure your widget language and type, and click "Embed code" to copy your script.

Auto language detection: sommelier.bot automatically detects the visitor's browser language or the language of the page, and switches to the most relevant language. The "lang" attribute in the script sets the default/fallback language.

B. Select your sommelier.bot integration

sommelier.bot widget JS is a lightweight script that adds a chat interface to your website. It supports 4 modes:

Popup: bottom right classic popup floating button + fullscreen dialog window
Dialog: no popup, to be used for a button or a link on-page that opens the fullscreen dialog window programmatically
Embed: inline iframe (less recommended)
Banner: nano sommelier.bot agent fully contextualized with page and user data, seamlessly embedded inline on product, category or homepage in a div container. It triggers the full dialog version when the user interacts with the banner.

Check below for each integration code and style.

2

Pop-up Widget (Chat Icon)

The pop-up adds a floating chat icon to the bottom-right of your website. Visitors click it to open the full AI sommelier, with product recommendations, food pairings, maps, and more.

        HTML
        
<script
    src="https://cdn.sommelier.bot/widget.js"
    merchant="MERCHANT_SLUG"
    mode="popup"
></script>
      

Attribute	Description
merchant	Your unique merchant identifier (provided in your welcome email).
lang	Default language: en, de, fr, it, es, cn, pt, ru, etc.

Where to place it:

Site-wide: paste in your website footer/global template to show on all pages.
Single page: paste only on the page where you want the chat icon to appear.

Pop-up widget opened showing full chat interface with product recommendations, map, featured products, and chat input

Pop-up widget: full AI sommelier with recommendations, food pairings, region map, and featured products.

3

Full-page Embed

Embed the complete sommelier.bot experience directly into a page on your website, as a dedicated "AI Sommelier" page. Uses the same script as the pop-up, placed inside a container div.

        HTML
        
<!-- Place inside a container div on your dedicated page -->
<div style="width: 100%; min-height: 600px">
  <script
      src="https://cdn.sommelier.bot/widget.js"
      merchant="MERCHANT_SLUG"
  ></script>
</div>
      

This renders the full chat interface inline, identical to the pop-up experience but integrated directly within your page layout. Ideal for a dedicated "Chat with our AI Sommelier" page in your navigation.

4

On-click Trigger (Dialog)

Don't want any pop-up icon on all pages or banners? Open the sommelier.bot programmatically from any button, link, or element on your site using a single JavaScript call. This headless mode opens the dialog programmatically with no UI chrome.

Step 1: Place the script below (with mode="dialog") to pre-load the widget, only if you don't already have a popup or banner integration on this page.

        HTML: Pre-load
        
<script
    src="https://cdn.sommelier.bot/widget.js"
    merchant="MERCHANT_SLUG"
    mode="dialog"
></script>
      

Step 2: Place the onclick trigger wherever you'd like a button or link to open the sommelier.bot.

        HTML: Trigger
        
<button onclick="sommelierbot.open?.()">
  Ask our AI Sommelier
</button>
      

Use this to add "Ask our Sommelier" CTAs anywhere on your site, product cards, navigation menus, promotional banners, email links, etc.

Example use cases: "Need help choosing?" button on your homepage hero. "Ask about this wine" link on product cards. "Get pairing ideas" CTA in your email campaigns (linking to a page with the widget installed).

5

Cloud-hosted sommelier.bot

Every paid account includes a fully hosted, standalone sommelier.bot at its own URL, no installation required. Share it anywhere: social media, QR codes, email signatures, printed materials.

        URL
https://MERCHANT_SLUG.sommelier.bot/
      

This URL is fully responsive (mobile + desktop) and managed from your same CMS dashboard. Encode it in a QR code for physical touchpoints: in-store displays, wine lists, event materials, business cards.

QR Code tip: Use any free QR code generator to encode your https://MERCHANT_SLUG.sommelier.bot/ URL. Print it on table tents, shelf talkers, or tasting menus to let customers scan and chat instantly with your AI sommelier.

AI Banner Integration

The AI Banner is a compact, context-aware agent that reads the page it's placed on: product data, category context, user history, location, past conversations, and generates a personalized one-liner to engage the visitor with quick action buttons. When a visitor interacts with the banner, it opens the full sommelier.bot dialog. You can create unlimited banners per shop, each with its own custom instructions and visual style.

1

Create & Customize a Banner

Go to https://business.sommelier.bot/banners in your CMS and click "Create new banner". You can create as many banners as you need, one per page type, one per campaign, or one per product category.

Tab 1: Custom Instructions (optional):

Add specific instructions for this banner's behavior. By default, every banner is already context-aware: it automatically reads the page content, user data, past conversations, location, and more. You only need custom instructions if you want to override the default behavior, for example, a specific tone of voice, custom call-to-action buttons, or additional data the page doesn't contain in its content.

Banner creation screen showing custom prompt instructions tab

Create a new banner, add optional custom instructions to control tone, CTAs, or inject extra context.

Already context-aware by default. The banner agent automatically reads page content, user browsing data, past conversations, geolocation, and more. You don't need to add instructions unless you want a specific behavior override.

Tab 2: Customize Theme (optional):

Customize the logo and color scheme for this specific banner to match the page or campaign it belongs to. Each banner can have its own visual identity.

Customize your banner's visual theme, logo, colors, and style per banner.

2

Get Your Banner Embed Code

Once your banner is created, click the "Embed Code" button on the top-right of the banner screen to get your unique embed code. Each banner has its own banner-id, so you can embed different banners on different pages.

Banner embed code screen showing the JavaScript snippet to copy

Click "Embed Code" to get your unique banner script with its banner-id.

Every banner embed code follows this structure, a JavaScript snippet inside a div container:

        HTML
        
<div style="min-height: 140px">
  <script
      src="https://cdn.sommelier.bot/widget.js"
      merchant="MERCHANT_SLUG"
      mode="banner"
      banner-id="BANNER_ID"
  ></script>
</div>
      

Attribute	Description
mode="banner"	Activates banner mode instead of the default pop-up.
banner-id	The unique ID of this banner (assigned when you create it in the CMS). Each banner has its own ID.
min-height: 140px	Reserves space for the banner while it loads, preventing layout shift.

3

Banner Placement Guide

Paste the banner embed code wherever you'd like it to appear on your page, template, or layout. Here are the recommended placements:

Page Type	Recommended Position	What the AI Does
Product page	Below the "Add to Cart" button	Generates a contextual prompt about the specific product, food pairings, similar wines, tasting notes.
Category page	Top of the product grid	Engages visitors to explore by palate, region, or pairing preference.
Homepage	Hero section or mid-page	General engagement prompt driving wine discovery.
Ad landing page	Above the fold	Uses campaign keywords as context to trigger a fully personalized AI conversation.

Banner on product page showing contextual message about Champagne food pairings with quick action buttons

Banner on a product page, automatically generates a contextual prompt about the specific wine with "Food match", "Pair it", and "Similar?" buttons.

Banner on category page showing discovery prompt with Pair it, Bold options, and Explore regions buttons

Banner on a category page, engages visitors to explore by palate, style, or region.

Pro tip for paid ads: Place the banner on your Google Ads or Meta Ads landing pages. sommelier.bot uses the campaign keywords and page context to initiate a fully personalized conversation, turning ad clicks into engaged buyers. Create a dedicated banner with custom instructions matching your campaign messaging.

Quick Reference: All Scripts

Widget Type	Code	Placement
Pop-up	<script src="...widget.js" merchant="SLUG" mode="popup"></script>	Footer (all pages) or single page
Banner	<div><script ... mode="banner" banner-id="ID"></script></div>	Product pages, categories, homepage, ad landing pages
Full-page embed	<div><script src="...widget.js" merchant="SLUG"></script></div>	Dedicated chatbot page
Dialog (on-click)	onclick="sommelierbot.open?.()"	Any button/link (requires widget pre-loaded)
Cloud-hosted	https://MERCHANT_SLUG.sommelier.bot/	Share anywhere: QR codes, emails, social

Replace MERCHANT_SLUG with your unique merchant identifier (with no space) provided in your welcome email (e.g., winecom, citydrinks, weinbestellungch).

Need Help?

We're here for you

If you run into any issues during setup or want to discuss advanced integrations, reach out:

Documentation	sommelier.bot/documentation
Contact	Contact us
CMS Dashboard	business.sommelier.bot

In this guide

Your Catalogue

Send Us Your Shop Link

Optional: Create Your XML Product Feed

XML Feed Fields Reference

XML Feed Example

Widget Integration

A. Access Your sommelier.bot CMS

B. Select your sommelier.bot integration

Pop-up Widget (Chat Icon)

Full-page Embed

On-click Trigger (Dialog)

Cloud-hosted sommelier.bot

AI Banner Integration

Create & Customize a Banner

Get Your Banner Embed Code

Banner Placement Guide

Quick Reference: All Scripts

Need Help?

We're here for you