Open science, in the open

Initialise the widget. Normally called once by the install snippet, but you can call it again at runtime to re-bind to a different widget key or user. Resolves nothing — fires the 'boot' event on success.

organisation_uidrequired

string — the Frontiers organisation that owns this widget (e.g. org-frontiers).

widget_keyrequired

string — public widget key (pk_live_...) that scopes the agent, corpus, tools, and quotas.

user_id

string? — Phase 2 identity: durable visitor id known to the host app. Paired with user_hash; ignored on its own.

user_hash

string? — Phase 2 identity: HMAC-SHA256 of user_id keyed by the widget's signing_secret. Mint server-side; same shape as Intercom Identity Verification.

user

object? — descriptive profile fields shown in the assistant UI (name, email, …). Never used for authorisation — only the (user_id, user_hash) pair is trusted.

custom_attributes

object? — arbitrary structured properties attached to the visitor for the agent's context (plan tier, signup date, cart total…). Plain JSON only.

capture_page_context

boolean? — when true, forwards a snapshot of the page (URL, title, visible text capped at 6 KB) to the iframe whenever the panel opens. Off by default — opt in only where the host page's content isn't sensitive.

api_base

string? — override the server origin the iframe and JSAPI talk to. Defaults to the origin loader.js was served from. Useful for self-hosted mirrors.

alignment

'right' | 'left'? — which corner to dock the launcher in. Defaults to right.

horizontal_padding

number? — pixel offset from the docked corner along the X axis. Default 20.

vertical_padding

number? — pixel offset from the docked corner along the Y axis. Default 20.

open

boolean? — auto-open the panel right after boot. Intercom-compat. Off by default.

Giving the agent context — three patterns, pick by recency. The widget deliberately separates static, snapshot, and dynamic context so the agent sees fresh data without the host having to re-boot the widget on every page change.

custom_attributes — static, mutable. Set on boot, patch via update. Use for plan tier, signup date, role tags — things that change rarely.

capture_page_context — snapshot, opt-in. When true, the loader forwards the page's URL + title + visible text (6 KB cap) once per panel open. Use for "summarise this article" / "what does this say about X" flows on content-heavy pages.

request_host_event — dynamic, per-turn. Documented under on / off below. The agent calls a named host event from a tool call; your on('event', (name, data, reply) => reply(...)) handler returns a structured value the LLM consumes in the next turn. Use for cart contents, current role, form state — anything that changes during the conversation and the agent needs right now.

// Normally fired by the install snippet, but you can re-boot at
// runtime to re-bind to a different widget key or user.
AssistantGPTWidget('boot', {
  organisation_uid: 'org-frontiers',
  widget_key: 'pk_live_...',
  user_id: 'usr_123',          // optional, paired with user_hash
  user_hash: '<hmac-sha256>',  // mint server-side
  custom_attributes: { plan: 'premium' },
  capture_page_context: true,
})

Patch the current settings without re-booting. Typical use: SPA navigation flips context.page on every route change so the agent always knows where the visitor is.

Accepts a partial of the boot payload. Fields you omit are left untouched.

// Patch settings without re-booting (e.g. on SPA route change).
AssistantGPTWidget('update', {
  custom_attributes: { plan: 'premium', last_route: location.pathname },
})

Open or close the chat panel programmatically. Use show on a custom "Ask the assistant" CTA to skip the launcher FAB; hide if you're driving the widget from a wizard step. Fires the 'show' / 'hide' events.

No parameters.

AssistantGPTWidget('show')
AssistantGPTWidget('hide')

Show a proactive speech bubble next to the launcher. Click the bubble → the chat opens with the optional prefill pre-typed in the composer. Pass null to dismiss any current nudge programmatically.

messagerequired

string — bubble text.

delay_ms

number? — delay in milliseconds before the bubble appears. Default 0.

prefill

string? — text to drop into the composer when the bubble is clicked. The panel opens either way; prefill makes "click bubble → ask the obvious question" a one-tap interaction.

force

boolean? — re-show even if the visitor dismissed a previous nudge this session. Defaults to false (dismissals persist via sessionStorage). Usually only set for testing.

AssistantGPTWidget('nudge', {
  message: 'Need help choosing a journal?',
  delay_ms: 3000,
  prefill: 'Which Frontiers journal fits a neuroscience paper?',
  force: false,
})

AssistantGPTWidget('nudge', null) // dismiss the current nudge

Forward a host-side analytics event into the widget's telemetry pipeline (and back out as a 'track' event for adopters who pipe to their own analytics). Useful for correlating widget conversations with funnel steps the assistant doesn't observe directly.

namerequired

string — event name (e.g. submission_started).

metadata

object? — arbitrary structured properties to attach.

AssistantGPTWidget('trackEvent', 'submission_started', { journal: 'FNINS' })

Tear down the widget: remove the launcher, close the panel, drop all event listeners. The visitor loses access until you call boot again. Use at logout — especially when a different user is about to sign in on the same page so their thread history doesn't carry over.

No parameters. Fires 'shutdown'.

// Tear down at logout (drop launcher, panel, listeners).
AssistantGPTWidget('shutdown')

Subscribe to events the widget fires back to the host page. Pure synchronous registration — no promise. off removes a previously-registered handler.

'event'

LLM-driven host event. Handler receives (name, data, reply?). When reply is present, the agent called request_host_event and is awaiting a structured response — call reply(payload) (within 10s) to feed the data back into the next turn. Fire-and-forget when reply is omitted.

'boot'

Fires once when the loader has finished setting up. Handler receives { loader_id, version }.

'show' / 'hide'

Fired when the chat panel opens or closes — whether triggered by the launcher, the JSAPI, or a nudge click. Use to mirror open/close state in your own UI.

'track'

Echo of a trackEvent call from the same page. Handler receives (name, metadata). Lets adopters fan analytics calls out to their own observability stack without intercepting trackEvent directly.

'shutdown'

Fired after shutdown finishes tearing down. Use to clear any UI mirroring the widget's state on the host page.

// LLM-driven host events use the (name, data, reply) shape.
const handler = (name, data, reply) => {
  if (name === 'get_user_role') reply?.(currentUser?.role ?? null)
}
AssistantGPTWidget('on', 'event', handler)

// Lifecycle events deliver their own args.
AssistantGPTWidget('on', 'show', () => console.log('panel opened'))
AssistantGPTWidget('on', 'track', (name, metadata) => forward(name, metadata))
AssistantGPTWidget('on', 'shutdown', () => clearWidgetUi())

AssistantGPTWidget('off', 'event', handler) // unsubscribe