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
| Item | Requirement |
|---|---|
| Bundle | Production loyalty-concierge IIFE loaded on the host page |
| Global | window.AugeoChatSdkLoyaltyConcierge is defined |
| Mount node | A DOM element matches your container selector |
| Token | auth.getToken can return a current member bearer token |
Load a pinned production loyalty bundle first. See Quick start for the embed pattern.
Constants
| Export | Value | Role |
|---|---|---|
| Bundle global | window.AugeoChatSdkLoyaltyConcierge | Named exports for the loyalty persona |
| Persona path | loyalty-concierge | CDN path segment under /chat-sdk/ |
| Custom element | chat-sdk-loyalty-concierge | Element the constructor mounts |
PKG_VERSION | Build version string | Identify the loaded artifact |
AUGEO_EVENT | augeo.event | Upward CustomEvent from widget to host |
AUGEO_ACK_EVENT | augeo.ack | Downward 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
| Symbol | Kind | Signature |
|---|---|---|
AugeoAssistant | class | new AugeoAssistant(config: AugeoAssistantOptions) |
| default export | same class | Same constructor as AugeoAssistant |
Construction mounts immediately.
A missing container calls onError and does not mount.
Pass AugeoAssistantOptions.
Required fields are container and auth.getToken.
| Field | Required | Default | Role |
|---|---|---|---|
container | yes | none | CSS selector for the existing mount node |
auth.getToken | yes | none | Returns the current member bearer token |
auth.onFailure | no | none | Recoverable 401 handler |
apiBaseUrl | no | bundle default | API origin override |
onError | no | shared logger | Mount and runtime error sink |
branding | no | product defaults | Agent name and theme |
surface | no | inline | Presentation discriminant |
capabilities | no | product defaults | Feature 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
| Method | Signature | Description |
|---|---|---|
open | (options?: AugeoAssistantOpenOptions) => void | Opens modal or sidebar. See below |
subscribeContextualTurns | (listener) => () => void | New contract. Logical turn observations |
connectInteractionSource | (registration) => observationInput | Connects search-results or PDP observations to this assistant |
destroy | () => void | Unmounts 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.
| Member | type | Extra 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
| Field | Type | Default | Role |
|---|---|---|---|
agentName | string | 'THEO' | Name used in UI copy |
theme | AugeoAssistantTheme | product defaults | Partial 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.
| Key | Default | Page |
|---|---|---|
history | on | History |
privacy | off | Privacy |
messageActions | on | Message actions |
chat | on | Chat |
suggestions | on | Suggestions |
wishlist | on | Wishlist |
events | on | Event options |
analytics | off | Analytics |
support | off | Support |
recovery | off | Recovery |
devtools | off | Devtools |
productGuidance | off | Contextual 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.
| Type | Role |
|---|---|
AnalyticsAdapter | Writer with id, optional ready, and send |
AnalyticsDispatch | event, cloudEvent, and mapped for send |
AugeoCloudEvent | CloudEvents 1.0 form of the compact envelope |
MappedDestination | Destination name, params, optional items, and kind |
MappingProfile | Overlay for destination names and params |
DestinationIdentity | { userId: () => string } for destination params |
ConsentSource | Optional grant, deny, callback, cookie, or localStorage |
DestinationDeclineReason | Why 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.
| Export | Signature | Role |
|---|---|---|
subscribeAugeoEvents | (target, handler) => () => void | Listen for AugeoEvent |
subscribeAugeoAcks | (target, handler) => () => void | Listen for AugeoAck |
dispatchAugeoAck | (target, ack: AugeoAck) => void | Send 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
| Field | Required | Meaning |
|---|---|---|
spec | yes | Constant augeo.event |
specversion | yes | Constant 1.0 |
id | yes | Unique emission id |
type | yes | Dictionary event name |
typeversion | yes | Payload version for this type |
time | yes | Emission time in epoch milliseconds |
class | yes | observed or measured |
source | yes | { surface, instanceId } |
correlation | yes | Optional join keys. Object may be empty |
data | yes | { occurrence, context } |
Deduplicate deliveries on event.id.
Switch on type before you read data.occurrence.
AugeoAck
| Field | Required | Meaning |
|---|---|---|
spec | yes | Constant augeo.ack |
specversion | yes | Constant 1.0 |
eventId | yes | Matching upward event.id |
time | yes | Ack time in epoch milliseconds |
outcome | yes | fulfilled or rejected from hosts |
effectId | no | Effect id from the upward event |
context | no | Optional 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.
| Status | Meaning |
|---|---|
requested | Selection accepted. Identity is known. Not completion |
opened | The shell panel is actually visible |
submitted | The chat request was dispatched |
admitted | Durable proof matches this identity |
rejected | The turn was not admitted |
failed | Known identity failed after a decision |
uncertain | Proof 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.
| Field | Rule |
|---|---|
version | Literal 1 |
source | Literal search_results |
search.query | Submitted text, at most 200 units. Blank only with a category |
search.criteria | Only category_id and product_type. Unknown keys reject |
criteria.product_type | merchandise or gift_card |
search.presentation | Optional page, limit from 1 to 25, and sort. Display only |
prompt.kind | Literal search_assistance |
| Host result count | Host 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.
Related pages
| Topic | Page |
|---|---|
| Embed steps | Quick start |
| Product scope | Overview |
| Root options | Configuration |
| Shell fields | Surfaces |
| Partner colors | Branding |
| Feature groups | Capabilities |
| Member intents | Events |
| Destination writers | Analytics |
| Compact fields | Event envelope |
| Names this widget emits | Event catalog |
| Host ack contract | Acknowledgements |
| Surface schema | Surface v1 |
| Event schema | Events v1 |
| Live inspector | Debugging with devtools |
| Integration failures | Common issues |