Augeo AI Docs
SDKs

Configuration

Configuration

Pass AugeoAssistantOptions to new AugeoAssistant(config). Only container and auth.getToken are required by the constructor. Pass apiBaseUrl for the environment you selected. Every other root field is optional.

Prerequisites

ItemValue
Personaloyalty-concierge
Bundle globalwindow.AugeoChatSdkLoyaltyConcierge
Mount nodeA DOM element matches your container selector
TokenA cached THEO bearer exists before construction
Evidenced revisionb7909e4564933080f7dbc92e6c4915147906ab60

Load the revision-pinned self-hosted loyalty script first. CDN 0.10.0 and latest were not verified for this lifecycle.

packages/chat-sdk/dist/iife/loyalty-concierge/index.js

Root fields

FieldRequiredDefaultEffect
containeryesnoneCSS selector string for the existing mount node
auth.getTokenyesnoneSynchronous read of the current THEO bearer
auth.onFailurenononeAwaited recovery for a known recoverable failure
apiBaseUrlselected environmentbaked build originAPI origin for that environment
onErrornoshared loggerReceives mount and runtime errors
brandingnoTHEO, product themeSets agent name and partner colors
surfacenoinlineSelects the presentation shell
capabilitiesnoproduct defaultsEnables feature groups

Read Privacy to configure program policy links through capabilities.privacy.

Container

container is a CSS selector string. Construction queries it with document.querySelector. It is not an element or a shadow root.

new AugeoAssistant({
  container: '#chat-host',
  apiBaseUrl: 'https://api.augeoai.net',
  auth: { getToken: () => cachedTheoBearer },
});

That selector must match an element that already exists. A missing node throws, skips the mount, and calls onError.

Script loading

Load the verified IIFE as a classic script. Then read AugeoAssistant from window.AugeoChatSdkLoyaltyConcierge.

<script src="/vendor/chat-sdk/loyalty-concierge/index.js"></script>

The executed fixture served that path from the revision above. Its emitted version was b7909e45. Do not infer a CDN release from a package manifest.

Host exchange

The host backend exchanges the verified member for an opaque THEO bearer. The browser receives only the validated THEO response. It never receives the mint secret or the Kigo member token. subject_token is the verified Kigo account_id. Do not send a profile id, email, or Kigo JWT. The host endpoint rejects browser account, program, and provider overrides. capabilities.events.programId is a hint, not authorization. THEO finds or creates the identity in the credential's program. An existing identity in another program or tenant is rejected. The host credential and principal must allow each requested scope. member alone permits member routes; Offers Chat also needs agent:offers-concierge. Refresh or validate the Kigo session before reminting after upstream rejection. There is no refresh token. Use expires_in to time the cached renewal. Do not hardcode a lifetime. Return cache-control: no-store.

POST /api/token
Authorization: Basic base64(<credential_id>:<mint_secret>)
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<verified Kigo account_id>
subject_token_type=urn:augeo-ai:params:oauth:token-type:external-account-id
scope=agent%3Aoffers-concierge+member
session_handle=<current account-space token, no Bearer prefix>

The browser response fields are access_token, token_type, issued_token_type, expires_in, and scope. Do not add a refresh token or a provider diagnostic field.

Auth token

Acquire the THEO bearer before mount. auth.getToken must return a string synchronously. The widget calls it when it builds the Authorization header. Read the latest cache. Do not mint inside the getter.

import type {
  AugeoAssistantOptions as ConfigAssistantOptions,
  AuthFailure as ConfigAuthFailure,
} from './vendor/chat-sdk/index';

declare function configReadBearer(): string;

const configAuth: ConfigAssistantOptions['auth'] = {
  getToken: () => configReadBearer(),
};

const configOptions: ConfigAssistantOptions = {
  container: '#chat-host',
  apiBaseUrl: 'https://api.augeoai.net',
  auth: configAuth,
};

void configOptions;
void (null as ConfigAuthFailure | null);

A returned Promise stringifies in the Authorization header.

Auth failure

auth.onFailure is optional. Chat awaits it for a known recoverable failure. It does not replay the failed turn. The next intentional action reads the replacement through getToken.

Known codes are SESSION_EXPIRED, SESSION_REVOKED, and SESSION_INVALID. recoverable must be true. Chat accepts the HTTP 401 envelope and one transient stream event. Bind the callback to the bearer captured for that request. Deduplicate HTTP, stream, and concurrent reports for that bearer. Ignore a late report from an old bearer or a disposed session. Do not render, persist, replay, or resend the stream event. Malformed data, generic 401 bodies, 403, 404, and outages do not remint. One failed bearer gets one renewal in that cycle. A failed, unchanged, or rejected replacement ends the cycle. Only a later user action or a new session starts another cycle. Show one sign-in action. Use Please sign in again. Do not show bearer values or provider diagnostics.

{"error":{"code":"SESSION_INVALID","message":"Please sign in again.","recoverable":true}}
{"type":"data-auth-failure","data":{"error":{"code":"SESSION_INVALID","message":"Please sign in again.","recoverable":true}},"transient":true}
import type {
  AugeoAssistantOptions as ConfigAssistantOptions,
  AuthFailure as ConfigAuthFailure,
} from './vendor/chat-sdk/index';

declare function configReadBearer(): string;

const configRecoverable = ['SESSION_EXPIRED', 'SESSION_REVOKED', 'SESSION_INVALID'] as const;

type ConfigRecoverableCode = (typeof configRecoverable)[number];

declare function configRenew(failure: ConfigAuthFailure): Promise<void>;

const configRecoveryAuth: ConfigAssistantOptions['auth'] = {
  getToken: () => configReadBearer(),
  onFailure: async (failure) => {
    if (!failure.recoverable) return;
    if (!configRecoverable.includes(failure.code as ConfigRecoverableCode)) return;
    await configRenew(failure);
  },
};

void configRecoveryAuth;

Callback differences

CallbackChatSearch
getTokenSynchronous stringString or Promise
onFailureOptional awaited recovery. No automatic replayOptional. Awaited before one retry
onAuthErrorNot a Chat callbackFinal notification. Code only
Omitted recovery hookNo Chat recovery callbackExisting getter-and-401 retry remains

Search mounts with createAugeoSearch and an existing element. Chat does not accept that element as container.

API origin

Pass apiBaseUrl for the selected environment. Omitting it uses the origin baked into that build. That baked origin is not a hardcoded production limit.

EnvironmentapiBaseUrl
productionhttps://api.augeoai.net
named non-productionThat environment's API origin
apiBaseUrl: 'https://api.augeoai.net'

A blank override is ignored. The baked origin of the selected build is used instead.

Script and connect policy

Script hostscript-srcconnect-src
Self-hosted verified build'self''self' and the selected API origin
Verified CDN artifact onlyhttps://sdks.augeoai.net'self' and https://api.augeoai.net

Use 'self' for the authenticated host token endpoint. Do not combine CDN and self-hosted script origins. Inline Shadow DOM styles need a separate style-src 'unsafe-inline'. That style rule is not part of the script or connect policy.

Errors

onError receives mount and runtime errors. Omit it to use the shared logger.

onError: (error) => {
  window.hostTelemetry?.captureError?.(error);
}

A missing container is reported here. Keep the callback cheap and side-effect safe. Do not log bearers or provider bodies from auth callbacks.

Branding pointer

branding.agentName defaults to THEO. branding.theme recolors partner-branded surfaces.

See Branding for palette, ramp, and override rules.

Surface pointer

surface.type is the only discriminant. Allowed values are inline, modal, and sidebar. Omitted surface resolves to inline.

See Surfaces for every shell field and default.

Events application identity

capabilities.events.applicationName names the implementing application. The field is optional. Set it when you construct the assistant. The slug is not read from the page URL. Existing events configuration keeps working when the field is omitted.

FieldRequiredDefaultEffect
capabilities.events.applicationNamenononeStable application slug on requests and telemetry
capabilities.events.environmentnononeIntegrator environment name, kept nested
capabilities.events.programIdnononeNon-authoritative hint. Not an authorization claim

Pass a non-PII slug. Do not include a user, session, token, or URL.

capabilities: {
  events: {
    applicationName: 'theo',
    environment: 'sandbox',
  },
}

A Theo-owned page passes theo. A partner embed passes its own slug. events: true, omitted events, and events: false send no slug.

environment stays under data.context.host. It is not a CloudEvents attribute. Omit it when you have no integrator environment name. dev, stage, and prod name deployment streams, not this field. An environment without a kept slug is dropped.

Requests send the slug on X-Attribution-Application-Name. Telemetry copies it to data.context.host.applicationName. The page location stays {href, title, referrer}.

Capabilities pointer

capabilities groups optional features such as history, chat, events, and analytics. Each group is a boolean or an options object.

See Capabilities for the feature map.

Minimal construct

const { AugeoAssistant } = window.AugeoChatSdkLoyaltyConcierge;

const assistant = new AugeoAssistant({
  container: '#chat-host',
  apiBaseUrl: 'https://api.augeoai.net',
  auth: { getToken: () => cachedTheoBearer },
});

That construct fills #chat-host inline. The agent name is THEO. Partner colors stay at product defaults.

Optional construct

const assistant = new AugeoAssistant({
  container: '#chat-host',
  apiBaseUrl: 'https://api.augeoai.net',
  auth: {
    getToken: () => cachedTheoBearer,
    onFailure: (failure) => renewTheoBearer(failure),
  },
  onError: (error) => console.error(error),
  branding: {
    agentName: 'Ava',
    theme: { palette: { primary: '#6119ea' } },
  },
  surface: { type: 'modal', openOnMount: false },
  capabilities: {
    events: {
      applicationName: 'theo',
      environment: 'sandbox',
      programId: 'prog_1',
    },
  },
});

openOnMount: false keeps the modal closed until Ask AI or the FAB. capabilities.events.applicationName is the application slug, not the agent name. programId does not authorize the exchange. agentName: 'Ava' replaces the default THEO in the header. Hex palette.primary derives partner tokens and a brand ramp.

Session lifetime

Call destroy() on logout, account change, or program change. Clear the cached bearer first. A late response must not restore it. Same-member renewal keeps the mounted assistant. Token-scoped requests then read the replacement.

import type { AugeoAssistantAuth } from './vendor/chat-sdk/index';

declare function configAcquire(): Promise<void>;
declare function configClearBearer(): void;
declare const configRecoveryAuth: AugeoAssistantAuth;

async function configMountForSession(): Promise<void> {
  await configAcquire();
  const assistant = new window.AugeoChatSdkLoyaltyConcierge.AugeoAssistant({
    container: '#chat-host',
    apiBaseUrl: 'https://api.augeoai.net',
    auth: configRecoveryAuth,
  });
  configClearBearer();
  assistant.destroy();
}

void configMountForSession;

Tear down

Call assistant.destroy() when the host route or session ends. The instance is inert after destroy.

TopicPage
Product scopeOverview
Minimal embedQuick start
Shell fieldsSurfaces
Agent name and themeBranding
Feature groupsCapabilities
Member intentsEvents
Destination writersAnalytics
Public typesAPI
Mount failuresCommon issues