Embed SDK

Drop a chat widget on any site, or mount it programmatically with publishable keys.

Overview

The embed SDK is a lightweight browser widget that talks to TuringArte public APIs. It is served as static files from your app origin:

/sdk/v1/loader.js — reads data-* attributes and loads the widget
/sdk/v1/widget.js — Web Component <turingarte-chat> + window.TuringArte.mount

Setup checklist

Active AI Employee with chat embed channel enabled
Provider (BYOK) key configured for the org
Publishable key from Dashboard → SDK Keys or the employee Embed tab (pk_live_…)
Optional but recommended: allowlist your site origins on the key
Feature flag FEATURE_EMBED enabled (default on)

Option A — script tag (recommended)

loader.jshtml

<script src="https://YOUR_APP_ORIGIN/sdk/v1/loader.js"
        data-employee="EMPLOYEE_UUID"
        data-key="pk_live_xxxxxxxx"
        async></script>

Attributes:

data-employee — employee UUID (required)
data-key — publishable key (required)
data-api-base — optional API origin if it differs from the script host

Option B — programmatic mount

widget.js + TuringArte.mounthtml

<script src="https://YOUR_APP_ORIGIN/sdk/v1/widget.js" async></script>
<script>
  // after widget.js loads:
  window.TuringArte.mount({
    employeeId: "EMPLOYEE_UUID",
    publishableKey: "pk_live_xxxxxxxx",
    apiBase: "https://YOUR_APP_ORIGIN", // optional
    // target: document.body // optional mount parent
  });
</script>

Option C — Web Component

Custom elementhtml

<script src="https://YOUR_APP_ORIGIN/sdk/v1/widget.js"></script>
<turingarte-chat
  employee-id="EMPLOYEE_UUID"
  publishable-key="pk_live_xxxxxxxx"
  api-base="https://YOUR_APP_ORIGIN"
></turingarte-chat>

Runtime behavior

Shadow DOM UI (launcher + panel) fixed bottom-right
Visitor id stored in localStorage (ta_visitor_id)
Conversation id persisted (ta_conversation_id) and resumed via session API
Loads public config for greeting/name, then posts messages to /api/public/chat

Publishable keys

Keys are shown in full only at creation. Store them like other public client credentials — they are not as sensitive as LLM secrets, but they can incur usage on your org if abused. Mitigations:

Scope a key to a single employee when possible
Allowlist exact origins (scheme + host)
Revoke from the dashboard if leaked
Rate limits apply per key/IP on public endpoints

CORS & origins

Requests from browsers send an Origin header. If the key has an allowlist, mismatched origins receive 403 forbidden_origin. Empty allowlist means all origins (convenient for demos — tighten for production).

Test without your site

Use /embed-demo with an employee id and publishable key.

Upcoming SDK work

Theming / branding controls beyond default violet
npm package for SPA frameworks (React/Vue helpers)
Streaming token responses for lower latency UX
Authenticated server SDK for backend agent calls
Mobile-friendly position and open-by-query options

Common errors

unauthorized — missing/invalid publishable key
forbidden_origin — origin not on allowlist
feature_disabled — embed kill switch off
inactive / not available — employee not active
rate_limited — slow down; honor Retry-After

Full HTTP reference: Public API