> For the complete documentation index, see [llms.txt](https://docs.maker.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maker.co/maker-greatstore/developer-reference/javascript-api.md).

# JavaScript API

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

[Install GreatStore](/maker-greatstore/get-started/installation.md) before using `window.GreatStore`.

## On this page

* [Methods](#methods)
* [Common patterns](#common-patterns)
* [Passing page context](#passing-page-context)
* [Generating structured content](#generating-structured-content)
* [Opening the chat from a link](#opening-the-chat-from-a-link)
* [Browser push notifications](#browser-push-notifications)
  * [Host `gs.js`](#host-gs.js)
  * [Prompt for permission](#prompt-for-permission)
* [Google Analytics events](#google-analytics-events)

## 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](#browser-push-notifications). |
| `GreatStore.ready`                                     | A Promise that resolves once the panel has loaded and is ready to open.                                                                                                                                                     |

## Common patterns

{% tabs %}
{% tab title="Open from a button" %}

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

{% endtab %}

{% tab title="Ask on the shopper's behalf" %}

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

{% endtab %}

{% tab title="Open with a product question" %}

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

{% endtab %}

{% tab title="Reveal a button once ready" %}

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

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

{% endtab %}
{% endtabs %}

## 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.

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

{% hint style="info" %}
Context is **replaced**, not appended. Send the full current state each time rather than a diff.
{% endhint %}

## Generating structured content

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

```javascript
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.

{% hint style="warning" %}
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.

If the assistant declines the request itself, the error carries a `reason`: `off_topic` (unrelated to your store), `harmful`, `deceptive` (fake reviews, invented discounts, false claims), `system_probe` (asking about the assistant's own instructions), or `no_data` (nothing in your store could supply what was asked for). A declined request is declined every time, so change the prompt rather than retrying.
{% endhint %}

## Opening the chat from a link

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

```html
<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-address}.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`:

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

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

{% hint style="info" %}
If your platform can't serve a file from the site root (Shopify, for example), host `gs.js` wherever it can be served from on your own domain, keep your regular `embed.js` tag, and tell it where the file is with `data-push-sw-path`:

```html
<script
  src="https://{your-address}.greatstore.ai/embed.js"
  data-push-sw-path="/cdn/shop/files/gs.js"
></script>
```

Value of `data-push-sw-path` only allows relative paths, not full URLs, and it has to match where you actually put the file.
{% endhint %}

### 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:

```javascript
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.

{% hint style="warning" %}
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.
{% endhint %}

## 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's address) 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?

{% content-ref url="/pages/RTlzI1gcpj96yLG3FUes" %}
[MCP access for agents](/maker-greatstore/developer-reference/mcp-access.md)
{% endcontent-ref %}

{% content-ref url="/pages/qSEQriDDbvfZp4sinBqD" %}
[Security](/maker-greatstore/configure/security.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maker.co/maker-greatstore/developer-reference/javascript-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.