JavaScript SDK — AtlasLaunch AI

Install

HTML, before </body>

<script src="https://assistant.atlasvoice.cloud/sdk/v1.js"
        data-key="alapk_your_public_site_key"
        data-search-url="https://example.com/?s={q}"
        async></script>

The widget lives in a Shadow DOM: your CSS cannot break it, and it cannot break your page.
Styles come from a constructed stylesheet, so your Content-Security-Policy needs no 'unsafe-inline'. Allow https://assistant.atlasvoice.cloud in script-src and connect-src.
/sdk/v1.js always serves the latest v1 (cached for 5 minutes). Version 1 only gains options and events; a breaking change would be /sdk/v2.js.

Options

The data-* attributes call init for you. For full control, leave them out and call it yourself:

JavaScript

AtlasLaunchAI.init({
  key: 'alapk_your_public_site_key',
  searchUrl: 'https://example.com/?s={q}',
  lang: 'en',
  site: 'Example Shop',
  page: { id: '42', type: 'product' },
  voice: true,
  position: 'right',
});

Option	Attribute	Meaning
`key`	`data-key`	Your public site key `alapk_…` (required unless `endpoint`).
`endpoint`	`data-endpoint`	Proxy mode: your own server’s ask URL, which calls the API with your secret key (the WordPress plugin does this).
`searchUrl`	`data-search-url`	Your site search, `{q}` = the question. Offered when nothing was found or the service can’t answer.
`lang`	`data-lang`	Answer and speech language (default: the page’s `lang`, then the browser’s).
`download`	`data-download="false"`	The Download conversation button (on by default).
`voice`	`data-voice="false"`	Microphone and read-aloud (on by default, hidden where the browser has no speech).
`page`	`data-page-id`, `data-page-type`	The current page; without it the page is found by its URL.
`site`, `title`, `greeting`, `placeholder`, `footer`	`data-site`, `data-title`, `data-greeting`	Texts in the panel.
`position`, `theme`	`data-position`, `data-theme`	`left` or `right`; `light`, `dark` or `auto`.
`labels`		Translate any button or message of the panel.

Colours

Set CSS variables on any parent, for example :root: --ala-accent, --ala-accent-text, --ala-bg, --ala-text, --ala-muted, --ala-line, --ala-bubble, --ala-radius, --ala-font, --ala-z.

Your own actions

Anything your page can do, the assistant can do when a visitor asks for it. Describe when the action applies; the AI reads the description.

JavaScript

AtlasLaunchAI.registerAction('open_projects', {
  description: 'Open the dashboard Projects page (add a website or copy a key)',
  args: { tab: 'string' },             // optional: up to 4, string | number | integer | boolean
  run(args, ctx) {
    ctx.say('Opening your projects.');
    ctx.go('/app/projects' + (args.tab ? '#' + args.tab : ''));
  },
});

Names are 2–40 lowercase letters, digits or _; up to 12 actions of your own.
Built in on every site: go, list, read_page, summary. Registering one of them replaces the SDK’s behaviour (the service still checks its arguments).
Shop actions are offered only when registered (the WooCommerce adapter does): add_to_cart, show_cart, remove_from_cart, fill_checkout. Short form: registerAction('show_cart', (args, ctx) => …).

The action context

`ctx`	Meaning
`say(text)`	Adds an assistant message (spoken in a voice chat). Shop actions report their real result this way.
`ask(question)`	Promise of the visitor’s next message, for a form filled step by step. That reply stays in the browser: it is never sent to us.
`go(url)`	Opens a page; the conversation follows.
`fallback()`	Runs the SDK’s own behaviour for this action.
`answer`, `page`	The answer that carried the action (with its sources), and the current page.

Events

JavaScript

const off = AtlasLaunchAI.on('answer', ({ q, response }) => console.log(response.sources));
AtlasLaunchAI.on('error', ({ code }) => console.warn(code));   // also window event "atlaslaunchai:error"

Event	Detail
`ready`, `open`, `close`	`{ version }`, `{}`
`question`	`{ q }`
`answer`	`{ q, response }`
`action`	`{ type, args, response }`, before the action runs
`error`	`{ code, status }`: `quota_exceeded`, `server_busy`, `rate_limited`, `origin_not_allowed`, `network_error`, `action_failed`…

Download the conversation

The Download conversation button in the chat header saves the conversation from the browser’s own copy, for support and debugging; nothing is sent to us. The file is chat-{site}-{date}.txt (hold Shift for .json): the site, page, time, SDK version and language, then every turn with its time, text, sources, listed items, action (as JSON) and, on a failure, the error code and the search link offered.

JavaScript

const convo = AtlasLaunchAI.exportConversation();   // { site, page, saved, sdk, lang, mode, turns: [...] }
AtlasLaunchAI.downloadConversation('json');           // or 'txt'

Other methods

ask(q) (resolves with the answer), open(), close(), toggle(), clear(), say(text), exportConversation(), downloadConversation(format), setPage({ id, type, url, title }), unregisterAction(name), destroy(), version, ready.

Calling before the file has loaded

JavaScript

window.AtlasLaunchAIQueue = window.AtlasLaunchAIQueue || [];
AtlasLaunchAIQueue.push(function (ai) {
  ai.setPage({ id: '42', type: 'product' });
});

What the browser keeps

sessionStorage: the last 30 messages, so the conversation follows the visitor from page to page in that tab; forgotten after 30 minutes without use, or with Clear.
localStorage: a random visitor id, used only to limit how many questions one visitor can send.
No cookies. Speech is the browser’s own; nothing is recorded by us.