Augeo AI Docs
SDKs

API

API

This page lists the current host types on the loyalty concierge bundle. It covers the constructor, constants, and compact event helpers. The contextual-turn section is the new contract. Those examples are not previously published fields.

Prerequisites

ItemRequirement
BundleProduction loyalty-concierge IIFE loaded on the host page
Globalwindow.AugeoChatSdkLoyaltyConcierge is defined
Mount nodeA DOM element matches your container selector
Tokenauth.getToken can return a current member bearer token

Load a pinned production loyalty bundle first. See Quick start for the embed pattern.

Constants

ExportValueRole
Bundle globalwindow.AugeoChatSdkLoyaltyConciergeNamed exports for the loyalty persona
Persona pathloyalty-conciergeCDN path segment under /chat-sdk/
Custom elementchat-sdk-loyalty-conciergeElement the constructor mounts
PKG_VERSIONBuild version stringIdentify the loaded artifact
AUGEO_EVENTaugeo.eventUpward CustomEvent from widget to host
AUGEO_ACK_EVENTaugeo.ackDownward CustomEvent from host to widget

Read exports from the loyalty global after the script loads.

const sdk = window.AugeoChatSdkLoyaltyConcierge;
const { AugeoAssistant, PKG_VERSION, AUGEO_EVENT, AUGEO_ACK_EVENT } = sdk;

Hosts do not construct the custom element directly. Use AugeoAssistant.

Import types

Import types from @kigo-digital/chat-sdk.

import type {
  AugeoAssistantOptions,
  AugeoEvent,
  AugeoAck,
} from '@kigo-digital/chat-sdk';

IIFE hosts can use the published types/index.d.ts file. That file types the bundle globals on window.

Constructor

SymbolKindSignature
AugeoAssistantclassnew AugeoAssistant(config: AugeoAssistantOptions)
default exportsame classSame constructor as AugeoAssistant

Construction mounts immediately. A missing container calls onError and does not mount.

Pass AugeoAssistantOptions. Required fields are container and auth.getToken.

FieldRequiredDefaultRole
containeryesnoneCSS selector for the existing mount node
auth.getTokenyesnoneReturns the current member bearer token
auth.onFailurenononeRecoverable 401 handler
apiBaseUrlnobundle defaultAPI origin override
onErrornoshared loggerMount and runtime error sink
brandingnoproduct defaultsAgent name and theme
surfacenoinlinePresentation discriminant
capabilitiesnoproduct defaultsFeature groups

auth.getToken must return a string synchronously. A Promise stringifies in the Authorization header.

const { AugeoAssistant } = window.AugeoChatSdkLoyaltyConcierge;

const assistant = new AugeoAssistant({
  container: '#chat-host',
  auth: { getToken: () => window.__HOST_MEMBER_TOKEN__ },
});

capabilities.events.applicationName is the implementing application. Set it at initialization. Do not derive it from the page URL. capabilities.events.environment stays nested. It is not a CloudEvents attribute. Both fields are optional.

Root field detail lives on Configuration.

Instance

MethodSignatureDescription
open(options?: AugeoAssistantOpenOptions) => voidOpens modal or sidebar. See below
subscribeContextualTurns(listener) => () => voidNew contract. Logical turn observations
connectInteractionSource(registration) => observationInputConnects search-results or PDP observations to this assistant
destroy() => voidUnmounts the widget and restores page reflow

Generic seeded opening stays backward compatible. That behavior is the existing contract.

assistant.open({ seed: 'gift ideas for mom' });
assistant.open({ seed: 'gift ideas for mom', autoSubmit: false });
assistant.destroy();

A nonblank seed is submitted by default. The submitted text is the exact seed. Pass autoSubmit: false to prefill only. That opt-out keeps the trimmed composer text. A blank or omitted seed opens without submitting. An inline surface is always open and ignores open. open({ seed }) still opens a sidebar when fab is false and askAi is omitted. Call open({ seed }) only after successful initialization. A call before initialization completes does nothing. open returning is not proof the turn was admitted. It is not a completed handoff.

open({ opening: 'for_you_refresh' }) opens the new-chat welcome on the For You message instead of a seed. open({ opening: 'preferences' }) opens Shopping preferences. open({ opening: 'quiz' }) opens the new chat on the interest quiz. Nothing is sent until the member picks a chip or types. On its own, opening cannot be combined with autoSubmit or context. An options object that carries both seed and opening keeps the seed path, so forwarding the whole refinement input still auto-sends the seed.

After destroy(), the instance is inert. Construct a new AugeoAssistant to mount again.

PDP observation input

connectInteractionSource(registration: PdpGuidanceSource): PdpGuidanceObservationInput connects kind: 'pdp-guidance' metadata to the existing loyalty assistant. The input exposes presentationId: string | null, observe(event: unknown): void, and dispose(): void. It accepts registered host view and press observations. It does not render UI, observe DOM visibility, or execute a contextual turn. Use the existing open({ context, onHandoff }) method for execution. See Product-page handoff for registration, privacy, event fields, and lifetime rules. Search-results registrations retain their existing observe, bindTurn, and dispose behavior.

Surfaces

surface is a discriminated union on required type. No other field can change which shell renders. Omitted surface resolves to inline.

MembertypeExtra fields
Inline'inline'onDismiss?
Modal'modal'openOnMount?, askAi?, fab?
Sidebar'sidebar'openOnMount?, askAi?, fab?, container?, width?, side?, mobileBreakpoint?

onDismiss is valid only when type is 'inline'. Optional fab on modal and sidebar overrides launcher visibility. Omitted fab keeps the injection-failed fallback.

See Surfaces for every shell field and default. See Surface v1 for the JSON schema.

Branding

FieldTypeDefaultRole
agentNamestring'THEO'Name used in UI copy
themeAugeoAssistantThemeproduct defaultsPartial theme and optional palette

Pass partner color on branding.theme.palette.primary. See Branding for palette, ramp, and override rules.

Capabilities

Each key except history and productGuidance accepts false, true, or an options object. false disables the group.

KeyDefaultPage
historyonHistory
privacyoffPrivacy
messageActionsonMessage actions
chatonChat
suggestionsonSuggestions
wishlistonWishlist
eventsonEvent options
analyticsoffAnalytics
supportoffSupport
recoveryoffRecovery
devtoolsoffDevtools
productGuidanceoffContextual turn

history is boolean only. productGuidance is the new contextual-turn contract. Omit it, or pass false, to disable contextual launch. It does not accept true. Hash routing lives on chat.hashRouting. See Capabilities for the shared contract. See Analytics for destination writers.

Analytics types

Hosts pass adapter objects on capabilities.analytics. The IIFE bundle does not export a gtag helper.

TypeRole
AnalyticsAdapterWriter with id, optional ready, and send
AnalyticsDispatchevent, cloudEvent, and mapped for send
AugeoCloudEventCloudEvents 1.0 form of the compact envelope
MappedDestinationDestination name, params, optional items, and kind
MappingProfileOverlay for destination names and params
DestinationIdentity{ userId: () => string } for destination params
ConsentSourceOptional grant, deny, callback, cookie, or localStorage
DestinationDeclineReasonWhy a destination write was skipped

send receives AnalyticsDispatch. identity.userId never lands on augeo.event.

Host events

The widget emits compact facts on augeo.event. Hosts answer effects with augeo.ack.

ExportSignatureRole
subscribeAugeoEvents(target, handler) => () => voidListen for AugeoEvent
subscribeAugeoAcks(target, handler) => () => voidListen for AugeoAck
dispatchAugeoAck(target, ack: AugeoAck) => voidSend a host ack

Prefer document so composed events reach you. Each subscribe helper returns an unsubscribe function.

const { AUGEO_EVENT, subscribeAugeoEvents, dispatchAugeoAck } =
  window.AugeoChatSdkLoyaltyConcierge;

const unsubscribe = subscribeAugeoEvents(document, (event) => {
  handleFact(event);
});

subscribeAugeoEvents drops details that fail the compact envelope predicate.

Join acks with ack.eventId === event.id. Hosts send fulfilled or rejected only.

See Events for handling rules. See Event envelope for field order. See Acknowledgements for ack shapes.

AugeoEvent

FieldRequiredMeaning
specyesConstant augeo.event
specversionyesConstant 1.0
idyesUnique emission id
typeyesDictionary event name
typeversionyesPayload version for this type
timeyesEmission time in epoch milliseconds
classyesobserved or measured
sourceyes{ surface, instanceId }
correlationyesOptional join keys. Object may be empty
datayes{ occurrence, context }

Deduplicate deliveries on event.id. Switch on type before you read data.occurrence.

AugeoAck

FieldRequiredMeaning
specyesConstant augeo.ack
specversionyesConstant 1.0
eventIdyesMatching upward event.id
timeyesAck time in epoch milliseconds
outcomeyesfulfilled or rejected from hosts
effectIdnoEffect id from the upward event
contextnoOptional context bags
dispatchAugeoAck(document, {
  spec: 'augeo.ack',
  specversion: '1.0',
  eventId: event.id,
  time: Date.now(),
  outcome: { status: 'fulfilled' },
});

Do not send outcome.status of unacknowledged. The waiting layer mints that after timeout.

Contextual turn

This section is the new contextual-turn contract. These fields were not previously published. Search results use this same open call. Use the assistant instance you already created. Do not mount a second assistant. Older bundles keep generic open only. Feature-detect subscribeContextualTurns before you call it.

Subscribe before open. The unsubscribe function is idempotent. No new wire field is added. open returning is not admitted.

// New contextual-turn contract. Not a previously published field.
const context = {
  version: 1,
  source: 'pdp',
  product: { productId: 7789, selection: 'selected' },
  prompt: {
    id: 'affordability',
    text: 'Do I have enough points for this?',
    kind: 'affordability',
  },
};

const unsubscribe = assistant.subscribeContextualTurns((event) => {
  if (event.type === 'accepted-new') return;
});

assistant.open({
  context,
  onHandoff(observation) {
    if (observation.status === 'admitted') return;
  },
});

productId must be a finite positive safe integer. Do not coerce blank strings, NaN, fractions, or records. Pass the selected sibling catalog ProductId. Do not add a face value or price field. Omitted selection means page. selected means a deliberate denomination was captured. A family page without a selection keeps the page ProductId. Exact-cost answers then ask for a selection. Do not choose minPrice or maxPrice. Prompt kind is generated, affordability, or comparison. Comparison uses the current product as the anchor. It does not select multiple products.

Put checkEligibility on capabilities.productGuidance. The check must return literal true. Any other result blocks the launch. The host rechecks it when a queued selection is about to send. Server session and catalog access stay authoritative. Host program ids, names, prices, and balances are not authority. Do not send tokens, raw profiles, or full product payloads. Attribution programId and placementId are not authentication.

StatusMeaning
requestedSelection accepted. Identity is known. Not completion
openedThe shell panel is actually visible
submittedThe chat request was dispatched
admittedDurable proof matches this identity
rejectedThe turn was not admitted
failedKnown identity failed after a decision
uncertainProof was not observed. Keep the same identity

Every accepted caller receives requested before open returns. That observation carries the shared clientTurnId. A coalesced call does not emit another accepted-new event. It also does not emit another logical requested event. One pending activation produces one user turn. A later deliberate repeat may mint a new identity. Cancelling one caller is not a shared failure while another remains. After dispatch, reconciliation continues if every caller leaves.

Reconcile or retry with the same clientTurnId. Do not mint a new identity for a possibly accepted turn. Moving to another product invalidates stale question generation. It does not retarget a selection already captured. Changing member or program invalidates pending work. Contextual submit does not replace an unsent composer draft. A failed handoff must leave page navigation, cart, and wishlist usable.

This request example is the new contextual-turn contract. It extends the existing chat request. It is not a separate launch endpoint. A generic request without context stays valid.

{
  "threadId": "22222222-2222-4222-8222-222222222222",
  "clientTurnId": "11111111-1111-4111-8111-111111111111",
  "messages": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "role": "user",
      "parts": [{ "type": "text", "text": "Do I have enough points for this?" }]
    }
  ],
  "context": {
    "version": 1,
    "source": "pdp",
    "product": { "productId": 7789, "selection": "selected" },
    "prompt": {
      "id": "affordability",
      "text": "Do I have enough points for this?",
      "kind": "affordability"
    }
  }
}

This admission example is the new contextual-turn contract. It is proof of a durable user turn. It is not a finished answer.

{
  "type": "data-contextual-turn",
  "transient": true,
  "data": {
    "version": 1,
    "status": "admitted",
    "clientTurnId": "11111111-1111-4111-8111-111111111111",
    "threadId": "22222222-2222-4222-8222-222222222222",
    "userMessageId": "11111111-1111-4111-8111-111111111111",
    "disposition": "created"
  }
}

This rejection example is the new contextual-turn contract. Unknown acknowledgement fields yield uncertain, not success.

{
  "error": "Contextual turn rejected",
  "message": "We couldn't access this product. You can keep browsing and try again.",
  "contextualTurn": {
    "version": 1,
    "status": "rejected",
    "clientTurnId": "11111111-1111-4111-8111-111111111111",
    "code": "product_unavailable"
  }
}

Do not send prompt text to analytics. Do not treat an issued open as a completed handoff. Map only shared logical outcomes that a registered event already defines. This SDK does not add a handoff-completed event name. A controlled product-page harness uses the existing assistant. Passing that harness is not deployed backend acceptance. It is not a published SDK release. It is not authenticated host-production acceptance.

Search results context

This variant uses the same open({ context }) call. It is not a new launch method. Product-page context and generic seed stay valid. Pass the complete submitted search once per deliberate selection. Search does not call productGuidance.

const searchContext = {
  version: 1,
  source: 'search_results',
  search: {
    query: 'coffee',
    criteria: { category_id: 'kitchen', product_type: 'merchandise' },
    presentation: { page: 2, limit: 15, sort: 'relevance' },
  },
  prompt: {
    id: 'search-assistance',
    kind: 'search_assistance',
    text: 'Help me choose from these search results.',
  },
};

assistant.open({ context: searchContext });

The SDK copies query, criteria, and presentation before async work. Later host edits do not change that copy. Each open mints a new clientTurnId, even when the scope matches. Do not send clientTurnId on context. Do not coalesce equal scopes the way a product page does. Retry keeps that original id and the captured scope.

FieldRule
versionLiteral 1
sourceLiteral search_results
search.querySubmitted text, at most 200 units. Blank only with a category
search.criteriaOnly category_id and product_type. Unknown keys reject
criteria.product_typemerchandise or gift_card
search.presentationOptional page, limit from 1 to 25, and sort. Display only
prompt.kindLiteral search_assistance
Host result countHost display only. Not a request field and not eligibility

Supply every eligibility constraint. An unsupported filter rejects with unsupported_context. Do not drop that filter and send the query alone. Do not call open({ seed }) for a constrained search. Malformed scope is invalid_context. Neither code dispatches a turn.

category_id is one nonblank string. An array of categories is unsupported. Empty criteria are valid when the query is nonblank. A blank query needs a category. kitchen above is an example, not a fixed category.

Banner eligibility stays with the host entry. This contract does not decide whether the entry is shown. The host supplies placement, the submitted query, complete criteria, and count. Count must describe that same submitted generation. It never becomes a wire field.

Recommendations and refinement chips settle independently. A chip failure does not hold the recommendation response. The server owns chip generation and its wire outcome. The SDK renders that outcome. It does not invent chips. Chip text is the next ordinary user message. Free text remains available. Follow-up requests omit the original context.

A controlled fixture does not prove a live producer. Record producer request, history, and chip compatibility as pending until checked. Authenticated host acceptance needs the real host integration. A fixture is not that acceptance. Closing the assistant leaves the host results page unchanged.

TopicPage
Embed stepsQuick start
Product scopeOverview
Root optionsConfiguration
Shell fieldsSurfaces
Partner colorsBranding
Feature groupsCapabilities
Member intentsEvents
Destination writersAnalytics
Compact fieldsEvent envelope
Names this widget emitsEvent catalog
Host ack contractAcknowledgements
Surface schemaSurface v1
Event schemaEvents v1
Live inspectorDebugging with devtools
Integration failuresCommon issues