JavaScript API

Control the chat panel from your own page — open it, send messages, pass page context, and generate structured content.

Install the chat widget before using window.GreatStore.

Methods

Method	What it does
GreatStore.open()	Open the chat panel.
GreatStore.close()	Close the chat panel.
GreatStore.toggle()	Open if closed, close if open.
GreatStore.sendMessage(text)	Open the panel if needed and send a message as if the shopper typed it.
GreatStore.updateModelContext(text)	Give the assistant the shopper's current page state — product, cart, account — as hidden context for the next message. Replaces any context set before.
GreatStore.on(event, handler)	Listen for panel events. Returns a function that removes the listener.
GreatStore.generateStructuredContent(schema, prompt)	Ask the assistant for JSON matching a schema you provide. Returns a Promise.
GreatStore.enableNotifications()	Ask the shopper for browser-notification permission and register their device for notify-me alerts. Returns a Promise. On an embed this also needs gs.js — see #browser-push-notifications.
GreatStore.ready	A Promise that resolves once the panel has loaded and is ready to open.

Common patterns

Open from a button

<button onclick="GreatStore.open()">Chat with us</button>

Ask on the shopper's behalf

<button onclick="GreatStore.sendMessage('What is your return policy?')">
  Returns &amp; exchanges
</button>

Open with a product question

GreatStore.sendMessage('Tell me more about the Aurora Jacket');

Reveal a button once ready

const chatButton = document.querySelector('#chat-button');
chatButton.hidden = true;

window.GreatStore.ready.then(() => {
  chatButton.hidden = false;
});

Passing page context

updateModelContext is how the assistant knows what the shopper is looking at without them having to say it. Call it on navigation, and on any change worth knowing about — variant selection, cart updates.

GreatStore.updateModelContext(
  'Viewing: Aurora Jacket, size M, $189, in stock. Cart: 1 item, $95.'
);

Context is replaced, not appended. Send the full current state each time rather than a diff.

Generating structured content

Need AI-generated data for your own page — a product blurb, an FAQ block, a comparison table? Pass a JSON Schema and a prompt, and get back JSON matching that shape, generated with knowledge of your store.

const data = await GreatStore.generateStructuredContent(
  {
    type: "object",
    properties: {
      headline: { type: "string" },
      bullets: { type: "array", items: { type: "string" } },
    },
    required: ["headline", "bullets"],
  },
  "Write a short promo blurb for our best-selling sneakers.",
);

renderPromo(data.headline, data.bullets);

This runs entirely in the background — no chat panel, no shopper conversation. Schema objects exposing a toJSONSchema() method are converted automatically.

The promise rejects if content can't be generated. Wrap the call in try/catch and keep a static fallback so the page still renders.

Opening the chat from a link

Add ?gs_chat=open to any inbound link and the panel opens as soon as the page loads — useful in emails, ads, and "ask us" links.

<a href="https://your-store.com/products/aurora-jacket?gs_chat=open">
  Ask about this product
</a>

The parameter is stripped from the URL once the panel opens, so a manual reload won't re-open it.

Browser push notifications

The assistant can offer a shopper a notify-me — "tell me when this is back in stock," "let me know if the price drops." On your first-party storefront this works with no setup. In an embed — the widget running on your own domain — browsers only allow push notifications through a small helper file served from your site, so there's one extra step.

Host gs.js

Download gs.js from your store's origin (https://{your-slug}.greatstore.ai/gs.js) and serve it from the root of your site, at https://your-store.com/gs.js. Then load the widget from that file instead of embed.js:

<script src="https://your-store.com/gs.js"></script>

That single file both boots the widget and enables push — you don't need a separate embed.js tag alongside it.

If your platform can't serve a file from the site root (Shopify, for example), host gs.js wherever you can and point the loader at it with data-push-sw-path:

<script
  src="https://your-store.com/cdn/gs.js"
  data-push-sw-path="/cdn/gs.js"
></script>

Prompt for permission

The in-chat notify-me button prompts the shopper on its own. To trigger the prompt from your own UI instead, call:

await GreatStore.enableNotifications();

It asks the shopper for notification permission and registers their device. There are no keys or other configuration to manage — that's handled for you.

Without gs.js hosted, push stays off: the notify-me opt-in can't complete, and there's no fallback prompt. Hosting the file is what turns it on.

Google Analytics events

If your site already has Google Analytics, the chat widget reports shopper activity to it automatically. There's nothing to switch on and no setting to configure — and if your site doesn't use Google Analytics, nothing is sent anywhere.

Five events show up in your reports:

Event	Sent when
greatstore_open	A shopper opens the chat panel for the first time on a page.
greatstore_close	They close it again.
greatstore_send_message	A shopper sends a message. Sent for every message they send.
greatstore_start_voice	A voice conversation begins.
greatstore_end_voice	That voice conversation ends.

Each one carries two parameters — store_slug (your store) and session_id (the shopper's chat session) — so you can group one visitor's activity together in Google Analytics. Nothing a shopper typed or said is included, and neither is anything that identifies them personally.

What's next?

MCP access for agentsSecurity