Augeo AI Docs
SDKs

Surfaces

Surfaces

surface.type selects the presentation shell. Allowed values are inline, modal, and sidebar. No other field can change which shell renders.

Omitted surface resolves to { type: 'inline' }. When you pass surface, type is required.

Prerequisites

ItemValue
Personaloyalty-concierge
Root optionscontainer and auth.getToken already work

Read Configuration first.

Choose a type

TypeWhat it isWhen to use
inlineFills the host mount nodeUse a host-owned panel or page region
modalOverlay panel with an optional FABKeep host layout and launch from a button
sidebarDocked column beside host contentReflow the page or fill a host sidebar slot

Inline

Inline fills container and stays in normal document flow. Use it when the host already owns the chat panel.

Inline fields

FieldRequiredDefaultEffect
typeyesinline when omittedSelects the inline shell
onDismissnononeHost close handler; valid only on inline

onDismiss is a compile-time error on modal or sidebar.

Default inline

new AugeoAssistant({
  container: '#chat-host',
  auth: { getToken: () => token },
});

Omitted surface mounts inline in #chat-host. The widget fills that node and does not overlay the page.

Explicit inline type

surface: { type: 'inline' }

The same inline shell renders. Use the explicit object when you also pass onDismiss.

Inline onDismiss

surface: {
  type: 'inline',
  onDismiss: () => hostCloseChat(),
}

The SDK calls hostCloseChat when the member closes the inline widget. The host then hides or removes its panel. Without onDismiss, close stays host-owned with no SDK callback.

Modal is an overlay panel. Use it when the chat should float over host content.

FieldRequiredDefaultEffect
typeyesnoneSelects the modal shell
openOnMountnofalsetrue auto-opens the overlay on mount
askAinononeInjects Ask AI into host search
fabnoinjection-failed fallbackControls the floating launcher button

Default modal

surface: { type: 'modal' }

The overlay stays closed after mount. With no askAi, the FAB reveals after the first-paint frame.

surface: { type: 'modal', openOnMount: true }

The overlay opens as soon as the widget mounts. openOnMount: false or omitted waits for Ask AI, the FAB, or a later open.

surface: { type: 'modal', fab: true }

The FAB reveals after the first-paint frame. Use this to opt back in while askAi is also configured.

surface: { type: 'modal', fab: false }

The FAB never reveals. The member needs askAi, openOnMount: true, or a host-owned trigger.

Omitted fab uses the injection-failed fallback. While askAi is pending or mounted, the FAB stays hidden. An invalid askAi.button or a timeout emits injection-failed and then reveals the FAB.

Sidebar docks a column beside host content. Use it when the chat should share the page with host UI.

FieldRequiredDefaultEffect
typeyesnoneSelects the sidebar shell
openOnMountnofalsetrue auto-opens the dock on mount
askAinononeInjects Ask AI into host search
fabnoinjection-failed fallbackControls the floating launcher button
containernopage reflowHost mount node; omit to wrap the page
width.basenoclamp(320px, 30vw, 480px)Docked width
width.minnononeMinimum docked width
width.maxnononeMaximum docked width
width.atnononeWidth overrides at viewport min-widths
sidenorightDocks on left or right
mobileBreakpointno767At or below this width, the shell uses modal overlay

Default sidebar

surface: { type: 'sidebar' }

The dock stays closed after mount. With no askAi, the FAB reveals after the first-paint frame. Width is clamp(320px, 30vw, 480px) on the right. At 767px or below, the shell falls back to a modal overlay. With no container, the SDK reflows the page to make room.

surface: { type: 'sidebar', openOnMount: true }

The dock opens as soon as the widget mounts. Omitted or false waits for Ask AI, the FAB, or a later open.

surface: { type: 'sidebar', fab: true }

The FAB reveals after the first-paint frame. It stays visible when injection fails or askAi is omitted. The same value applies in the small-screen overlay.

surface: { type: 'sidebar', fab: false }

The FAB never reveals. That includes omitted askAi and an injection failure. The small-screen overlay honors fab: false too. Use open after initialization when the host owns the entry point.

Omitted fab uses the injection-failed fallback. With no askAi, the FAB reveals after the first-paint frame. While askAi is pending or mounted, the FAB stays hidden. Injection-failed then reveals the FAB.

surface: {
  type: 'sidebar',
  container: '#rewards-sidebar',
}

The sidebar renders into #rewards-sidebar instead of wrapping the page. Omit container when the SDK should reflow host content.

surface: {
  type: 'sidebar',
  width: { base: '380px' },
}

The dock is 380px wide instead of the default clamp. width is an object with base, min, max, and at.

surface: {
  type: 'sidebar',
  width: {
    base: '30vw',
    min: '320px',
    max: '480px',
  },
}

The dock can shrink to 320px and grow to 480px. Those bounds apply with the 30vw base width.

surface: {
  type: 'sidebar',
  width: {
    base: '360px',
    at: {
      1024: { base: '420px' },
    },
  },
}

Viewports at least 1024px wide use 420px. Smaller viewports keep the 360px base.

surface: { type: 'sidebar', side: 'left' }

The dock sits on the left. Omitted side docks on the right.

surface: { type: 'sidebar', mobileBreakpoint: 640 }

At 640px or below, the sidebar uses a modal overlay. The fab override still applies in that overlay. The default breakpoint is 767.

Ask AI

askAi is valid on modal and sidebar only. It injects an Ask AI button into host search. When personalization is available, one teaser anchors below that button.

FieldRequiredDefaultEffect
buttonyesnoneCSS selector for the host search island
seedFromyesnoneCSS selector whose text seeds the first turn
timeoutMsno1500Wait bound for the island to mount

Both button and seedFrom must be strings. Otherwise askAi is dropped.

surface: {
  type: 'sidebar',
  askAi: {
    button: '#rewards-search-bar',
    seedFrom: '#rewards-search-input',
  },
}

The SDK injects Ask AI into #rewards-search-bar. It reads the member query from #rewards-search-input. timeoutMs stays 1500 because it is omitted.

askAi: {
  button: '#rewards-search-bar',
  seedFrom: '#rewards-search-input',
  timeoutMs: 2500,
}

The island may take up to 2500ms to mount. The timer is a wait bound, not the FAB reveal trigger.

If button never resolves, injection-failed fires. Modal and sidebar then reveal the FAB unless fab is false. An explicit fab wins on both launchable surfaces. That override also applies in the small-screen overlay. A late host node is still picked up, and the island can re-attach.

Host-owned Ask AI

A host that renders its own Ask AI control calls open instead of configuring askAi. open uses the same launch path and seeds the composer without sending. Set fab: false when the host owns the entry point. open({ seed }) still opens and seeds the sidebar when fab is false and askAi is omitted. Call open({ seed }) only after successful initialization. A call before initialization completes does nothing.

const search = window.AugeoSearchSdk.createAugeoSearch({
  target: document.querySelector('#rewards-search'),
  auth: { getToken: () => memberToken },
  onAskAi: (query) => assistant.open({ seed: query }),
});

The search widget reports its own launcher activation. The assistant still reports that the shell opened.

TopicPage
Root optionsConfiguration
Partner colorsBranding
Feature groupsCapabilities
Member intentsEvents
Public typesAPI
Minimal embedQuick start
Mount failuresCommon issues