Docs

Embeds

How to put each tool on your own website, and every option it takes. One script tag each; no build step, no plugin, nothing to host.

Before you start

Every embed loads from guitarz.ai/api/v1/ and talks to the platform through that same path, so nothing on your page points anywhere but your brand's domain.
Your widget key (pk_…) identifies your shop for the concierge; your shop id is the short name in your storefront address. Both are in the email we send when we set your shop up, and we'll resend them any time.
Tags can go anywhere in the page; the strip and the grid render where their tag sits, everything else floats.
Each embed renders inside its own Shadow DOM, so your theme's CSS can't break it and it can't break your theme.

All of it from one tag
The concierge: BrennerVinnie
C.H.A.D., photo to listing
Brady, the picture strip
The storefront grid
Values: categories, conditions, sorts
WordPress, Squarespace, Shopify, Wix
The WordPress plugin
Older tags that still work
Troubleshooting

1. All of it from one tag

The loader puts everything in with a single script tag. It loads the floating pieces on its own and mounts the inline pieces wherever you leave a placeholder.

<script src="https://guitarz.ai/api/v1/guitarzvinylz.js"
        data-key="pk_yourshop" data-shop="yourshop" data-accent="#f5a623" async></script>

<!-- optional: the picture strip and the grid render where you put these -->
<div data-brady data-limit="9"></div>
<div data-brady-bunch></div>

What it loads: the concierge (when data-key is set), C.H.A.D.'s corner mascot (unless you turn it off), and Brady and the grid for each placeholder it finds. A placeholder's own data-* attributes go straight to that embed, so anything in the Brady and grid sections below works on the placeholder too.

Attribute	What it does
`data-key`	Your widget key. Without it the concierge is not loaded.
`data-shop`	Your shop id, used by any strip or grid placeholder that doesn't name its own.
`data-accent`, `data-accent-text`	Colour pair passed to every embed. `#rrggbb`.
`data-title`, `data-concierge`, `data-launcher-img`, `data-icon`, `data-intro`, `data-side`, `data-voice`, `data-walk`	Passed to the concierge; see its section.
`data-chad`	Off unless asked for — C.H.A.D. is a staff tool and never loads by default. `"on"` adds the mascot (for a staff-facing page), `"trial"` mounts the free trial.
`data-chad-attach`	With `data-chad="trial"`: a CSS selector for your own button; the trial opens when it's clicked and no mascot is drawn.
`data-chad-label`, `data-chad-img`	The mascot's hover label and image; see the C.H.A.D. section.
`data-debug`	`"true"` opens every embed's Shadow DOM for devtools.

Prefer separate tags if you want different accents per embed, or a strip on one page and the concierge on all. The loader is a convenience, not a requirement; every embed below also stands alone.

2. The concierge: BrennerVinnie

A chat bubble that answers from your live inventory and nothing else. One tag on every page you want it on. The key can ride in the URL or in an attribute.

<script src="https://guitarz.ai/api/v1/brennervinnie.js?key=pk_yourshop" async></script>

<!-- or, with every option -->
<script src="https://guitarz.ai/api/v1/brennervinnie.js" data-key="pk_yourshop"
        data-title="Ask BrennerVinnie" data-accent="#f5a623" data-accent-text="#0c0e14"
        data-launcher-img="/images/brennervinnie.png" data-side="right" async></script>

Attribute	What it does
`data-key` or `?key=`	Your widget key. Required.
`data-title`	The panel's header text. Display only; the concierge's name and voice come from your shop settings.
`data-accent`	Button and header colour, `#rrggbb`. Defaults to your shop's theme accent.
`data-accent-text`	Text colour on the accent.
`data-icon`	A small image shown inside the round bubble instead of the speech-balloon icon.
`data-launcher-img`	A full image that replaces the bubble: the mascot treatment. Tall, no circle, the panel opens above it. Wins over `data-icon`. `"off"` keeps the plain speech-bubble launcher and skips the default mascot entirely.
`data-intro`	With a mascot: the speech bubble typed out over its head on a visitor's first view. Your own copy, or `"off"` for no bubble.
`data-walk`	With Brenner as the mascot: on a visitor's first view (once every 20 minutes) he hustles across the page to his corner, and whenever they click on empty page he walks along the bottom to where they clicked and stands there (the chat opens above him wherever he is), then walks back to his corner when the chat closes. `"off"` keeps him in his corner on this page; the portal's Setup › Brenner on your site switch turns it off for the whole shop.
`data-side`	`"left"` parks the bubble, panel and intro bottom-left instead of bottom-right, so two concierges can share a page.
`data-concierge` or `?persona=`	`"vinnie"` asks for the record concierge on a shop that sells both gear and records. vinnie.js already does this.
`data-voice`	`"off"` hides the microphone. By default, where the browser can do speech recognition (Chrome, Edge, Safari), a mic sits next to Send: tap it and talk, the question sends when you pause, the reply is read aloud, and the mic reopens for the next one. Typed questions are never spoken back.
`data-server`	Only if you serve the script from somewhere unusual: the API base to call instead of the one worked out from the script's own address.
`data-debug`	`"true"` opens the Shadow DOM for devtools.

The same tag included twice on a page is ignored; Brenner and Vinnie together on one page are fine. The bubble carries the "AI assistant" notice and the credit line; leave them in place.

3. C.H.A.D., photo to listing

The corner mascot that opens the photo-to-listing tool in a full-screen panel, right on the page. Staff sign in inside it with their staff key.

Staff can attach up to 30 photos to a listing. The first 5 are what C.H.A.D. reads to identify the item; the rest are kept on the listing for your storefront and marketplace, and don’t add to the read.

It identifies amps, pedals, pro audio, accessories, parts, keyboards and drums as well as instruments. The portal guide covers what to photograph for each type and what the tool will and won't claim, and how the listing copy is written, including the maker's own product page C.H.A.D. draws on for current models.

<script src="https://guitarz.ai/api/v1/chad.js" data-accent="#f5a623" async></script>

<!-- the free trial instead, wired to your own button -->
<a id="try-chad" href="https://guitarz.ai/chad-trial">Try C.H.A.D. free</a>
<script src="https://guitarz.ai/api/v1/chad.js" data-mode="trial" data-attach="#try-chad" async></script>

Attribute	What it does
`data-mode`	`"trial"` opens the email-gated free trial (three reads) instead of the staff tool.
`data-attach`	A CSS selector. No mascot is drawn; the panel opens when the matched element is clicked. Keep the element's own `href` as the no-JavaScript fallback.
`data-accent`, `data-accent-text`	The pill and border colour, also passed into the tool.
`data-label`	The hover pill's text. Default "C.H.A.D. →", or "Try C.H.A.D. →" for the trial.
`data-img`	Your own mascot image instead of Chad.
`data-staff-key`	Pre-authorises the tool with a staff key so nobody types it. The key is visible in your page source, so only ever do this with a sandbox shop's key.
`data-debug`	`"true"` opens the Shadow DOM.

The mascot hides on screens narrower than 560px, where the corner belongs to your page. Close the panel with ×, Escape, or a click outside it.

Vinyl Intake has nothing to embed: staff open the hosted tool at https://vinylz.ai/records on a phone and sign in with their staff key. Link the free trial from anywhere with https://vinylz.ai/vinyl-trial.

4. Brady, the picture strip

A photo-forward strip of your in-stock gearrecords that slides on its own, with arrows and swipe. It renders where the tag sits. Items without a photo are skipped, and with nothing to show it renders nothing at all.

<script src="https://guitarz.ai/api/v1/brady.js?shop=yourshop" data-limit="9" async></script>

Attribute	What it does
`?shop=` or `data-shop`	Your shop id. Required.
`data-limit`	How many items rotate. Default 10, max 24.
`data-accent`	Arrow and price colour. Defaults to your shop's theme accent.
`data-category`, `data-make`, `data-condition`	Pin the strip to a slice of inventory. Values below.
`data-orderby`	`newest` (default), `price_asc`, `price_desc`, `make`, `year_desc`.
`data-interval`	Auto-advance in milliseconds. Default 4500, minimum 1500. It pauses on hover and focus, and never runs when the visitor prefers reduced motion.
`data-debug`	`"true"` opens the Shadow DOM.

Each card is a real link to the item's hosted page, opened in a new tab so your page stays put.

5. The storefront grid

The browsable grid from your hosted storefront, inline on any page: cards, an item view, in-place paging, and an optional toolbar with search and filters. It renders where the tag sits and never touches your page's URL.

<script src="https://guitarz.ai/api/v1/brady-bunch.js?shop=yourshop" data-kind="records" async></script>

<!-- a teaser: eight newest, no toolbar, no "view all" -->
<script src="https://guitarz.ai/api/v1/brady-bunch.js?shop=yourshop" data-kind="records"
        data-limit="8" data-search="off" data-view-all="off" async></script>

Attribute	What it does
`?shop=` or `data-shop`	Your shop id. Required.
`data-kind`	`"records"` shows your vinyl instead of your gear: the records grid with genre, format, condition and price filters. Set it on record shops.
`data-limit`	Items per page. Default 25, max 100.
`data-orderby`	The initial sort: `newest` (default), `price_asc`, `price_desc`, `title`, `year_desc`. Visitors can change it when the toolbar is on.
`data-category`, `data-make`, `data-condition`	Pin the grid to one category, brand or condition. The matching dropdown is hidden and searches stay inside the scope. Values below.
`data-genre`, `data-format`	The same, for records.
`data-search`	`"off"` hides the whole toolbar for a pure teaser grid. The toolbar is off for embeds by default anyway; turn it on in your portal under Storefront embed.
`data-view-all`	`"off"` hides the "View all N items" link to your hosted storefront.
`data-accent`, `data-accent-text`	Override your shop's accent pair to match the page.
`data-debug`	`"true"` opens the Shadow DOM.

Your hosted storefront at https://guitarz.ai/store/yourshop is the same grid in page mode, with shareable URLs for every item and record.

Add to cart, checkout on your WooCommerce site

If your stock comes from WooCommerce (version 10 or newer), turn on Add to cart in your portal under Storefront embed. Gear cards and item views get an Add to cart button, a cart bar appears above the grid, and Check out sends the shopper to your own WooCommerce checkout with everything in the cart. Payment, shipping, tax, stock and the order itself all stay in WooCommerce, just as if they'd shopped there.

The cart is kept in the shopper's browser for two weeks and is shared by every grid on the same site. Your hosted storefront page keeps its own.
Right before checkout the cart is checked against your live WooCommerce stock, so anything that sold in the shop since it was added comes out first.
Items with no price ("Call for price") and items that didn't come from WooCommerce keep the contact button.
Orders arrive with source guitarz.ai and medium brady in WooCommerce's order attribution.
Checkout starts a fresh WooCommerce cart from the Brady cart, so put the grid on a site other than the WooCommerce store itself.
To show a cart count in your own header, listen for the bogz:cart event: window.addEventListener("bogz:cart", function (e) { … e.detail.count … }).

6. Values: categories, conditions, sorts

Scoping attributes take the same values your inventory uses.

Category (gear): electric-guitar, acoustic-guitar, bass, mandolin, banjo, ukulele, resonator, lap-steel, amplifier, electronics (effects & pedals — effects and pedals are accepted too), pro-audio, strings, accessories, parts, keyboards, drums, band-orchestra (brass, woodwinds, orchestral strings and harmonicas), other. guitars covers every guitar type at once: electric, acoustic, bass, resonator and lap steel. Your portal's inventory export shows the exact category on each item.
Make: The brand as it appears on your items, for example Fender.
Condition: new, used, or an exact grade name such as Excellent. For records, a Goldmine grade such as VG+.
Genre and format (records): As they appear on your records, for example Jazz and LP.
Sort: newest, price_asc, price_desc, title (grid) or make (strip), year_desc.
Colours: Six-digit hex, #f5a623. Anything else falls back to your shop's theme.

7. WordPress, Squarespace, Shopify, Wix

WordPress. Easiest: our plugin, a settings screen and two shortcodes. Or paste the tag in a Custom HTML block, or site-wide through your theme's footer scripts or a header-and-footer plugin.
Squarespace. Settings → Advanced → Code Injection → Footer for the concierge; a Code block for the strip or the grid.
Shopify. Online Store → Themes → Edit code → theme.liquid before </body> for the concierge; a Custom Liquid section for the strip or the grid.
Wix. Settings → Custom Code for the concierge; an Embed HTML element for the strip or the grid.
Anything else. It's a plain script tag. If the page can hold one, it works.

8. The WordPress plugin

The same one-tag loader, from a settings screen instead of a code editor, plus two shortcodes for the inline pieces. It's the thinnest possible wrapper: it prints exactly the tag from section 1 with your settings as its attributes, and nothing in it talks to the platform on its own.

Download the plugin (zip)

Install

In WordPress, go to Plugins → Add New → Upload Plugin, choose the zip, and click Install Now, then Activate. (Or unzip it into wp-content/plugins/.)
Go to Settings → Shop Concierge. Pick your lineup, paste your widget key and shop id, and Save. The concierge and the C.H.A.D. mascot appear on every page.
Put [brady] or [brady_bunch] in any page or post where you want the picture strip or the grid.

Settings

Setting	What it does
Lineup	Keep it on Gear (guitarz.ai: Brenner, C.H.A.D., Brady), the brand the embeds load from.Gear (guitarz.ai: Brenner, C.H.A.D., Brady) or Records (vinylz.ai: Vinnie, the records grid). Picks which brand the embeds load from.
Widget key	Your `pk_` key. Blank means no concierge.
Shop id	Used by the strip and grid shortcodes.
Concierge title	The chat panel's header.
Accent colour, text on it	Six-digit hex, applied to every embed. Blank uses your shop's theme colours.
C.H.A.D. mascot	On (the corner mascot opens the staff tool), Free trial (opened from a button of yours: give its CSS selector), or Off.
Voice, Side	The concierge's microphone, and which corner it sits in.
Advanced: loader base	Only if support asks, for example to point a staging site at a test host.

The settings screen shows the exact tag it will print. If you installed the first version of the plugin (concierge only), your key carries over; just open the settings once and Save.

Shortcodes

[brady limit="9"]
[brady limit="6" category="acoustic-guitar" orderby="price_desc"]
[brady_bunch limit="8" search="off" view_all="off"]
[brady_bunch kind="records" genre="Jazz"]

Any option from the Brady and grid sections works as an attribute; write underscores where the option has a dash (view_all for data-view-all). The shop id comes from the settings unless the shortcode names its own with shop="…".

Requires WordPress 6.0 or newer and PHP 7.4 or newer. The plugin is ours, not on wordpress.org, so WordPress won't offer updates for it: when we ship a new version we'll tell you, and installing the new zip over the old one keeps your settings.

9. Older tags that still work

Tags from before the brand aliases keep working and need no change: https://bogz.io/widget.js?key=… is the concierge, https://bogz.io/store-embed.js?shop=… the grid, and chad.js and brady.js at the same host. New installs should use the addresses on this page.

10. Troubleshooting

Nothing appears: Check the key or shop id, and that the page is one you registered with us. Open the browser console: an unknown key logs a clear message. With data-debug="true" you can inspect the embed in devtools.
The strip is empty: Brady shows only items with photos. Add photos, or widen the scope you pinned it to.
The concierge says it's unavailable: The month's chat allowance is used up; it comes back on your billing day, or move up a tier in your portal.
Colours look off: Accents must be six-digit hex. Anything else is ignored in favour of your theme.
It's on the wrong side, or in the way on phones: data-side="left" moves the concierge; the C.H.A.D. mascot hides itself below 560px.
Still stuck?: Email support@guitarz.ai with the page address and we'll look.