# JavaScript API: open the Nodale agent from your code

<https://nodale.ai/docs/api>

The nodale() commands a page can call: open the agent from your own button or form, pass an email and context, report visitor consent.

Once the [tag is installed](https://nodale.ai/docs), your page can send it commands through one function, `nodale()`. There are two commands: `open` and `consent`. The tag exposes no other method and sends no event to your page.

## The command queue

The tag defines `window.nodale` when it runs. To call a command before the tag has loaded, paste this stub above it. Commands wait in a queue until the tag is ready:

```html
<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>
```

Keep the `||`. A script that later assigns `window.nodale` without it removes the tag's command, and later calls go nowhere.

## `nodale('open')`

Opens the agent from your own code, for instance from your own button or once your own form is sent.

```js
nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contacts per month': '1500' }
})
```

The call starts a written conversation in the agent's dialog. The microphone is not requested: it waits for the visitor.

### Options

| Option | Type | What it does |
|---|---|---|
| `email` | string | The visitor's email, when your page already knows it. It is identified before the agent's greeting. |
| `context` | object | What the visitor already told you, as label and answer pairs. The agent receives it when the conversation starts. It is recorded on the conversation and never shown to the visitor. |

Both are optional. The tag checks the argument before anything leaves the page:

- **The argument** is nothing, or a plain object with no key other than `email` and `context`. Anything else and nothing opens.
- **`email`** is a string of 1 to 254 characters once trimmed. Otherwise it is dropped, and the agent still opens. The tag does not judge the address: the server decides whether to accept it.
- **`context`** holds 20 answers at most. A label is 1 to 60 characters, an answer is a string of 300 characters at most, and a label is used once. Labels and answers are trimmed, and an empty answer is skipped. If one rule is broken the whole context is dropped, never cut, and the agent still opens without it.

`nodale('open')` never throws and returns `undefined`.

### Where it works

- **On the bar and on the `hidden` display only.** With the button display, with an inline `<div data-nodale-agent>`, and on a page where the agent is not shown (a page rule, or a share of visitors), the call does nothing. If you use `open`, keep the share of visitors off, or the call does nothing for some visitors.
- **Before the tag has loaded**, through the stub above. Only the last queued `open` is replayed, once.
- **One conversation.** The widget starts one conversation at most and keeps the first email and context it received. An `open` during a conversation, or after one ended, only shows the dialog.
- **When the agent asks for the email first**, the call shows that step, and your email and context are sent when the visitor submits it.

### From a button

```html
<button type="button" onclick="nodale('open')">Ask a question</button>
```

### After your own form

```js
form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Company size': form.elements.size.value,
      'What they want to do': form.elements.message.value
    }
  })
})
```

## The hidden display

`hidden` is a display of the workspace, next to the bar and the button. With it, nothing shows until your page calls `nodale('open')`.

- **The page stays fully usable.** The agent's frame is mounted but invisible, and it takes no click.
- **Once opened, it is the bar.** Closing the dialog returns to the bar and keeps the conversation. The bar then stays for the rest of the tab.
- **The tab remembers it.** A later page of your site in the same tab shows the bar at once, so the visitor finds the conversation again. The tag keeps this in `sessionStorage`, in a key that holds no identifier. A new tab starts hidden.
- **Tested in Chromium browsers only.** Safari and Firefox are not covered by our browser tests yet: a browser that slows down invisible frames may answer `open` later.

## `nodale('consent')`

Tells the tag whether the visitor agreed to visit tracking. Use it when your site has no cookie banner the tag can read, or when you manage consent yourself.

```js
nodale('consent', 'granted')
nodale('consent', 'revoked')
```

- **It matters only when visit tracking is on** in your workspace. Tracking is off by default, and the agent is mounted either way.
- **Tracking starts denied.** Nothing is requested and no cookie is written before a grant. On `revoked`, the tag stops and drops its cookie.
- **It outranks every banner.** Once your page has called it, the tag follows your call and ignores what a banner says.
- **Global Privacy Control wins over everything.** A browser that sends it stays denied for the whole visit, whatever your page calls.

Without the call, the tag reads the answer from the consent tool of the page: Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, the HubSpot banner, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP and Google Consent Mode v2. Some of them need Nodale declared as a vendor or a service: the visit tracking guide in the app gives the setup for each.

## Debugging

The tag never throws into your page. It explains itself on `console.debug`, in lines starting with `nodale tag:`. Turn on the verbose level of your browser console to see them.

| Line | What happened |
|---|---|
| `open refused` | The argument is not a plain object, or it holds another key than `email` and `context`. |
| `open email dropped` | `email` is not a string of 1 to 254 characters. |
| `open context dropped` | `context` breaks one of its rules. |
| `open needs the floating or hidden display` | The workspace uses the button display, or the page mounts the agent inline. |
| `open: agent not on this page` | A page rule or the share of visitors keeps the agent off this page. |
| `open not acknowledged` | The widget did not answer within 30 seconds. |

## Docs

- [Install the Nodale agent on your website](https://nodale.ai/docs): One script tag puts the Nodale agent on your site. Where to paste it, what your site must allow, and how to check that it runs. (Markdown: https://nodale.ai/docs.md)
- [MCP server: manage your Nodale workspace from Claude Code](https://nodale.ai/docs/mcp): Connect Claude Code to the Nodale MCP server, then read and change your workspace: knowledge, demo assets, agent settings, sites, deployment. (Markdown: https://nodale.ai/docs/mcp.md)
