14. Developers

Klariton can be embedded with the hosted widget or consumed through read APIs for custom frontends. Use the widget for the fastest integration. Use the API when you want to render published touchpoints yourself.

Integration Options

Option	Use it when	Status
`<klariton-widget>`	You want standard rendering in your Klariton branding	LIVE
Public touchpoint delivery	The widget or worker reads published touchpoint content	LIVE
Public read API with API key	Your server or build job renders touchpoints itself	LIVE
Chat Advisor server integration	You need a custom chat integration	Guided
Customer webhooks	You want events pushed to your systems	COMING SOON
React/Next.js SDK	You want framework-specific helpers	COMING SOON

The Studio generates the current snippet. Prefer copying it instead of writing one by hand.

<script
  type="module"
  src="https://worker.klariton.com/v1/klariton-widget.universal.js">
</script>

<klariton-widget
  mode="biq-bundle"
  org-slug="your-org-slug"
  touchpoint-slug="your-touchpoint-slug"
  locale="en"
  data-worker-url="https://worker.klariton.com">
</klariton-widget>

Important attributes:

Attribute	Required	Meaning
`mode`	Yes in current snippets	`biq-bundle` for FAQ-style BIQs, `chat` for Chat Advisor.
`org-slug`	Yes	Organization slug from Klariton.
`touchpoint-slug`	Yes	Touchpoint slug from the Studio.
`locale`	Optional	BCP-47 locale, such as `en` or `de-DE`.
`data-worker-url`	Usually set	Worker origin. Can be a customer worker subdomain.
`embed-variant`	Optional	Layout variant such as inline, floating, or slide-up.
`product-id` / `product-handle`	Optional	Product context for product-specific touchpoints.

Older snippets that use tenant-id or omit mode should not be used as templates for new integrations.

Public Read API

Use API keys when a backend, build job, or server-rendered frontend needs to read published touchpoints.

Authentication:

Authorization: Bearer klrt_...

or:

x-api-key: klrt_...

Current public scope:

read_published

Endpoints:

GET /api/public/v1/touchpoints
GET /api/public/v1/touchpoints/{idOrSlug}

The API key determines the organization. Requests for another organization’s touchpoints should return 404.

Common errors:

Status	Meaning
401	Key missing, invalid, or revoked.
403	Key lacks the required scope.
404	Touchpoint not found, not live, deleted, or outside the key’s organization.

API keys must not be shipped in browser bundles.

API Key Management LIVE

Create keys under Settings -> API keys.

The key is shown only once. Copy it immediately and store it in a server-side secret manager.

The API Keys tab shows:

key name,
prefix,
scope,
last-used date,
created date,
revoked state.

Revoke unused keys. Requests using a revoked key should fail immediately.

Recommended practice:

create separate keys per system,
name keys after the system, not a person,
rotate keys when vendor or employee access changes,
keep keys out of client-side JavaScript,
use least scope when additional scopes become available.

Public Touchpoint Delivery

The widget can read live touchpoints without an API key through organization and touchpoint slugs:

GET /api/v1/orgs/{slug}/touchpoints/{idOrSlug}

Properties:

only live touchpoints are served,
response shape depends on touchpoint type,
FAQ and legacy wizard delivery are live,
Chat Advisor and Infobox public read delivery can require guided setup,
public delivery can use edge caching,
CORS is intended for safe read delivery.

Preview Tokens

Preview tokens are used by the Studio and widget preview flows where a non-public or draft preview is required.

Assumption: preview token routes are an internal integration surface unless explicitly documented in your workspace. Do not build customer-facing production integrations on preview tokens without a guided integration review.

Rules:

preview tokens are not API keys,
preview tokens should be short-lived,
preview tokens must not be treated as a public authentication layer,
production integrations should use the widget or public read API.

Chat Advisor Integration

The standard chat path is the Klariton widget plus Worker. Direct browser calls to the chat question endpoint are not the supported integration path.

For custom chat frontends:

keep worker and chat secrets server-side,
preserve session handling,
preserve origin checks,
preserve Trust Center activation state,
preserve lead escalation and consent behavior,
test with Test Center before go-live.

See Chat Advisor, Trust Center, and Test Center.

Webhooks

Customer-facing outgoing webhooks are planned but not part of the public product surface yet. Internal webhook mechanisms may exist for cache purge or platform synchronization, but they should not be treated as customer integration APIs.

Until customer webhooks are available, use the public read API or a guided integration.

Developer Checklist

Copy the embed snippet from the Studio.
Use org-slug, touchpoint-slug, mode, and data-worker-url.
Add production and staging domains in Settings.
Keep API keys and worker secrets out of browser code.
Store API keys in server-side secret management.
Treat confidence and source fields as optional unless the endpoint contract explicitly includes them.
Re-test after slug, domain, or worker URL changes.
Revoke keys that are no longer used.