Embed-Referenz

Alles, was Entwickler brauchen, um zu steuern, wie der Olotalk-Assistant geladen wird und sich verhält.


Basis-Snippet

<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  data-olotalk-assistant-id="YOUR_ASSISTANT_ID"
  async
></script>

Platzieren Sie es direkt vor </body>. async wird empfohlen, damit der Loader nicht blockiert.

Ein asynchrones Script
Liest Ihre Konfiguration
Lädt Bundle + CSS
Mountet den Assistant
Das einzelne Script-Tag ist ein kleiner asynchroner Loader: Er liest Ihre Konfiguration (data-* Attribute, zusammengeführt mit einem eventuellen `window.OlotalkConfig`), lädt Assistant-Bundle und CSS vom CDN und mountet den Assistant automatisch bei `DOMContentLoaded`.

data-olotalk-*-Attribute

Die gesamte Konfiguration wird über data--Attribute auf dem <script>-Tag übergeben.

<script
src=".../@olotalk/assistant-loader@0/dist/loader.iife.js"
1data-olotalk-assistant-id="ast_oltk_..."
2data-olotalk-origin="https://api.example.com"
3data-olotalk-locale="de"
4data-olotalk-cdn-base="..."
async
></script>
  1. 1
    data-olotalk-assistant-idErforderlich: welcher Assistant geladen werden soll.
  2. 2
    data-olotalk-originOptionaler API-Origin-Override für Self-Hosting; in Olotalk Cloud weglassen.
  3. 3
    data-olotalk-localeErzwingt eine Sprache. Sonst automatische Erkennung.
  4. 4
    data-olotalk-cdn-baseWoher das Bundle geladen wird. Standard ist jsDelivr.
Die gesamte Konfiguration läuft über ein einziges Script-Tag mit `data-*`-Attributen. Nur die Assistant-ID ist erforderlich; für alles andere gibt es sinnvolle Standardwerte.

data-olotalk-assistant-id (erforderlich)

Die eindeutige ID Ihres Assistants. Sie finden sie im Dashboard: Öffnen Sie Ihren Assistant über Assistants, die ID steht auf seinem Schritt Installation (und in der Seiten-URL).

data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"

data-olotalk-origin (optional)

Die Basis-URL der Olotalk-API. Lassen Sie sie in Olotalk Cloud weg, der Loader verwendet standardmäßig https://api.olotalk.com. Setzen Sie sie nur in fortgeschrittenen self-managed Deployments, in denen die API auf Ihrer eigenen Origin läuft.

<!-- Self-managed Deployment -->
data-olotalk-origin="https://api.example.com"

data-olotalk-locale

Erzwingt eine bestimmte Locale für die Assistant-UI. Akzeptiert jedes korrekt geformte BCP-47-Sprach-Tag: "en", "fr", "de", "en-CA", "vi", "ja-JP", "sw" usw. UI-Texte für en/fr/de sind direkt gebündelt; andere Locales übersetzt Olotalk bei der ersten Anfrage und cached sie danach.

Wenn das Attribut fehlt, erkennt der Assistant die Sprache automatisch in dieser Reihenfolge: zuvor akzeptierte Wahl des Besuchers (localStorage) → <html lang> der Seite → navigator.language. Die automatisch erkannte Sprache wird nur verwendet, wenn sie im supportedLocales-Set des Assistants enthalten ist.

data-olotalk-locale="de"

Die vollständige Prioritätskette finden Sie im Abschnitt Multilingual im Loader-README.

Dieses Attribut wird einmal gelesen, beim Mount des Assistant. Wenn Ihr eigener Sprachumschalter die Sprache der Seite ändert, ohne sie neu zu laden, rufen Sie Olotalk('locale', 'de') auf: Das tauscht die Texte des Assistant an Ort und Stelle und erhält die offene Konversation. Siehe Die Sprache selbst steuern.

data-olotalk-sandbox-token

Preview-Feature. Ein signiertes, ablaufendes Token aus der Karte Test in your own app im Dashboard. Seine Anwesenheit schaltet den Assistant in die unberechnete Developer-Sandbox, das vollständige Modell steht in Im Sandbox-Modus testen. Ist das Feature für Ihren Arbeitsbereich nicht aktiviert, ignorieren Sie dieses Attribut.

data-olotalk-sandbox-token="<Token aus dem Dashboard>"

data-olotalk-mode

Welche Form gemountet wird. Ohne dieses Attribut bekommen Sie den Corner Bubble.

data-olotalk-mode="drawer"

Mehrere Formen, per Komma getrennt, teilen sich eine Konversation, die erste ist die Residenz:

data-olotalk-mode="bubble,drawer"

Die vollständige Liste, und wofür jede Form da ist, steht in Shapes. Vier davon, drawer, anchored, navfield und askbar, hängen an etwas auf Ihrer Seite und brauchen neben diesem Attribut eine Zeile JavaScript; der Rest funktioniert mit dem Script-Tag allein.

Eine Id, die der Assistant nicht kennt, fällt auf einen funktionierenden Mount zurück und sagt es in der Konsole, ein Tippfehler degradiert zum Bubble, nicht zur leeren Seite.

data-olotalk-reach

Zusätzliche Wege, die gemountete Form herbeizurufen, kommagetrennt. selection öffnet sie neben einer Passage, die der Besucher markiert, mit dieser Passage als Zitat über einem leeren Composer; commandk öffnet sie mit ⌘K.

data-olotalk-mode="bubble"
data-olotalk-reach="selection,commandk"

Wie viele Wege hinein Sie auch hinzufügen: Die Seite hat weiterhin genau ein Panel und eine Konversation, siehe Formen kombinieren. Eine Id, die reach nicht kennt, wird mit einer Konsolenwarnung ignoriert.

data-olotalk-open

Macht aus jedem vorhandenen Element eine Tür, ohne JavaScript.

<button data-olotalk-open>Ask AI</button>
<button data-olotalk-open="drawer">Ask AI</button>
<button data-olotalk-open data-olotalk-prefill="Wie funktioniert die Abrechnung?">Preis-Hilfe</button>

Der Wert benennt, welche gemountete Form geöffnet wird; lassen Sie ihn leer, wenn die Seite ein einziges Panel hat, der Normalfall. data-olotalk-prefill öffnet es mit einer Frage, die die Form je nach eigenem Verhalten sofort sendet oder bearbeitbar lässt (die Corner bubble sendet, Select-to-ask behält sie zum Anpassen). Eine Tür, die eine nicht gemountete Form benennt, warnt in der Konsole und tut nichts, statt still zu scheitern.

Eine schlichte Tür schaltet um: Ein erneuter Druck schließt das offene Panel wieder. Eine Tür mit data-olotalk-prefill öffnet dagegen immer, sie bedeutet „frage das”, und ein zweiter Druck heißt „frage es noch einmal”, nicht „doch nicht”.

Das macht den Drawer zum reinen Einfügen: Er hat bewusst keinen eigenen Launcher, deshalb bringt sein Snippet diesen Button mit. Verschieben Sie ihn in Ihren Header, gestalten Sie ihn um, oder setzen Sie das Attribut einfach auf einen Button, den Sie schon haben.

data-olotalk-door="branded"

Gibt einer Tür das Aussehen des Assistant: im Ruhezustand ein zurückhaltender Chip, beim Hover läuft der Farbverlauf des Launchers als Rahmen darum herum.

<button data-olotalk-open="drawer" data-olotalk-door="branded">Ask AI</button>

Bewusst als Opt-in. Ohne dieses Attribut behält die Tür Ihre Gestaltung und wir fassen nichts an, genau darin liegt der Sinn von data-olotalk-open: Es sitzt auf einem Element, das Sie ohnehin haben. Das erzeugte Snippet bringt das Attribut und die Robotermarke als Inline-SVG mit, denn die Marke blinzelt, und das kann ein Hintergrundbild nicht. Entfernen Sie das Attribut, und Sie haben Ihren eigenen Button zurück.

data-olotalk-selection-answers

Wo eine Markierung das Panel öffnet. beside, der Standard, holt es zu den Wörtern, damit die Antwort dort ankommt, wo die Frage gestellt wurde. in-place öffnet es dort, wo der Assistant lebt: die richtige Wahl, wenn Ihr Assistant ein fester Punkt ist, den Ihre Besucher bereits gefunden haben, und Sie lieber möchten, dass sich nichts bewegt.

data-olotalk-mode="bubble"
data-olotalk-reach="selection"
data-olotalk-selection-answers="in-place"

Betroffen ist nur der Selection-Trigger: Ihre eigenen open({ anchor })-Aufrufe positionieren sich wie eh und je. Jeder andere Wert wird mit einer Konsolenwarnung ignoriert, und Sie erhalten beside.

data-olotalk-mount

CSS-Selektor des Containers, in den der Assistant rendert. Erforderlich für die Formen im Fluss, inline und expand, die in Ihrem Layout leben statt darüber. Alles andere positioniert sich am Viewport und ignoriert ihn.

data-olotalk-mount="#olotalk-assistant"

data-olotalk-cdn-base

Überschreibt die Basis-URL des CDN, von dem Assistant-Bundle und CSS geladen werden. Nützlich für Self-Hosting.

<!-- Self-hosting auf Ihrer eigenen Origin -->
data-olotalk-cdn-base="https://assets.example.com/olotalk"

Wenn Sie das Attribut weglassen, verwendet der Loader standardmäßig jsDelivr mit einem Assistant-Version-Pin passend zum Loader-Build.


JSON-Attribut (alternative Syntax)

Statt einzelner data-olotalk-*-Attribute können Sie auch einen einzigen JSON-Blob übergeben:

<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  data-olotalk='{"assistantId":"ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy","locale":"de"}'
  async
></script>

Das JSON-Attribut wird mit den einzelnen data-olotalk-*-Attributen zusammengeführt; einzelne Attribute haben Vorrang.


Globales Config-Objekt (fortgeschritten)

Für volle programmgesteuerte Kontrolle definieren Sie window.OlotalkConfig vor dem Loader-Script:

<script>
  window.OlotalkConfig = {
    assistantId: 'ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy',
    locale: 'de',
    theme: 'dark',
    mode: 'inline',           // welche Form — `bubble` ist der Standard
    mount: '#chat-container', // CSS-Selektor — erforderlich für `inline` und `expand`
    // origin: 'https://api.example.com', // nur für self-managed Deployments
    // cdnBase: 'https://assets.example.com/olotalk', // nur für self-hosted Assets
    // version: '1.2.3',                 // pinnt die Assistant-Bundle-Version
  };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  async
></script>

window.OlotalkConfig wird mit data--Attributen zusammengeführt. data- gewinnt bei Konflikten.

data-olotalk-* Attribut
am Script-Tag
overrides
window.OlotalkConfig
das globale Konfigurationsobjekt
overrides
eingebauter Standardwert
was ausgeliefert wird

Vollständige Config-Referenz

FeldTypStandardBeschreibung
assistantIdstring—Assistant-ID (erforderlich)
siteIdstring—Legacy-Alias für assistantId
originstringhttps://api.olotalk.com (Cloud-Build)Basis-URL der Olotalk-API
localestringautomatisch erkanntExpliziter Locale-Override (BCP-47-Tag)
theme"light" | "dark" | object"light"UI-Theme
modeShape-Id"bubble"Welche Form gemountet wird, siehe Shapes
placement"floating" | "embedded"—Veraltet, nutzen Sie mode. floating entspricht bubble, embedded entspricht inline. Wird weiterhin aufgelöst, da es in produktiven Snippets vorkommt
mountstringdocument.bodyCSS-Selektor des Containers. Erforderlich für inline und expand
cdnBasestringjsDelivrBasis-URL des Asset-CDN
versionstringpassend zum Loader-BuildVersion-Pin für das Assistant-Bundle
cssUrlstringaus cdnBase abgeleitetOverride für die Assistant-CSS-URL

Conversion-Konfiguration

Die Conversion-Pipeline ermöglicht Intent-basierte CTA-Vorschläge und Lead-Erfassung. Wenn sie aktiv ist, klassifiziert der Assistant jede Besuchernachricht in eine kommerzielle Intent-Kategorie (pricing, demo, integration, support, general) und schlägt bei ausreichend hoher Konfidenz die konfigurierte Aktion neben der Antwort vor.

Die Conversion-Konfiguration ist rein serverseitig. Sie liegt im Assistant-Datensatz und nicht im clientseitigen Embed-Snippet, daher wird sie im Dashboard konfiguriert.

Im Dashboard konfigurieren

Öffnen Sie Ihren Assistant über Assistants und verwenden Sie dann den Builder:

  • CTA actions, confidence und webhook target liegen im Schritt Base unter Advanced configuration → Action policy.
  • Tool connections (Calendly, HubSpot) liegen im Schritt Behavior.

Der empfohlene Produktionsbereich für minIntentConfidence ist 0.7–0.8. Senken Sie den Wert während Tests, wenn CTAs leichter ausgelöst werden sollen.

CTA-Aktionstypen

link
Leitet den Besucher zu einer URL weiter.
lead_form
Erfasst Name, E-Mail, Firma und Use Case.
escalate_to_human
Übergibt die Konversation an eine Person.
trigger_webhook
Löst Ihren Webhook mit dem Lead aus.
book_meeting
Öffnet einen Terminbuchungsablauf.
hubspot_create_contact_deal
Erstellt einen HubSpot-Kontakt und Deal.
AktionAusgelöst durchWas passiert
linkKlick auf den CTA-ButtonÖffnet href in einem neuen Tab
lead_formKlick auf den CTA-ButtonInline-Formular, E-Mail erforderlich, weitere Felder optional
escalate_to_humanKlick auf den CTA-ButtonServerseitige Aktion, benachrichtigt notifyEmail
trigger_webhookKlick auf den CTA-ButtonServerseitige Aktion, POSTet Lead-Daten an webhookUrl
book_meetingKlick auf den CTA-ButtonÖffnet einen Inline-Calendly-Scheduler
hubspot_create_contact_dealKlick auf den CTA-ButtonServerseitige Aktion, erstellt HubSpot-Contact und -Deal

notifyEmail und webhookUrl bleiben serverseitig gespeichert und werden nie an den Browser ausgeliefert.

Page Patterns und Konfidenz-Tuning

Standardmäßig kann ein CTA auf jeder Seite feuern. Mit pagePatterns beschränken Sie ihn auf bestimmte Pfade:

{ "pagePatterns": ["/pricing", "/integrations", "/docs"] }

Das Matching erfolgt per Teilstring. Lassen Sie pagePatterns weg, um alle Seiten zu matchen.

minIntentConfidence (0–1) steuert, wie klar der Besucher seine Absicht ausdrücken muss, bevor ein CTA feuert. Empfohlen für Produktion: 0.7–0.8.

Lead-Scoring und Webhook-Dispatch

Wenn ein Lead über lead_form eingereicht wird, bewertet Olotalk ihn anhand von Intent, E-Mail-Domain, Firmenangabe und Qualität des Use Cases. Leads mit Score ≥ 60 erhalten den Status qualified. Wenn der Assistant eine webhookUrl hat, POSTet Olotalk den Lead-Payload standardmäßig für jeden eingereichten Lead, nicht nur für qualifizierte. Details dazu finden Sie unter Leads & conversions.

Conversion-Events

Sie können Conversion-Outcomes auf der Assistant-Instanz abhören. Diese Events stehen auf der @olotalk/assistant-Instanz zur Verfügung, die createAssistant() zurückgibt; das Standard-Loader-Snippet legt sie nicht offen.

import { createAssistant } from '@olotalk/assistant'

const assistant = createAssistant(mountEl, { assistantId, origin })

assistant.on('cta_click', ({ id, action, intent }) => {
  console.log('CTA geklickt', id, action, intent)
})

assistant.on('lead_submit', ({ leadId, status, score }) => {
  console.log('Lead erfasst', leadId, status, score)
})

Embedded-Modus

Standardmäßig rendert der Assistant als Corner bubble unten rechts. Um ihn inline in einen bestehenden Container einzubetten:

<div id="chat-container" style="height: 600px;"></div>

<script>
  window.OlotalkConfig = {
    assistantId: 'ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy',
    mode: 'inline',
    mount: '#chat-container',
  };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  async
></script>

Der Container braucht eine explizite Höhe.

Damit ein eingebetteter Assistant optisch zur Host-Seite passt, setzen Sie einige CSS-Variablen. Siehe Theming.


Framework-Guides

Sie nutzen einen No-Code-Builder oder ein CMS? WordPress, Shopify, Wix, Squarespace, Webflow, Framer, Ghost, BigCommerce, Google Tag Manager und weitere haben eigene Schritt-für-Schritt-Guides unter Auf Ihrer Plattform installieren.

Die Beispiele unten gehen von Olotalk Cloud aus. data-olotalk-origin fehlt daher, weil der Loader bereits https://api.olotalk.com verwendet.

Jeder Guide unten mountet die Corner bubble. Möchten Sie den Assistant stattdessen inline in Ihrem eigenen Layout? Siehe Oberfläche wählen und dann Inline in einem Framework. Für das visuelle Matching zur Seite siehe Theming.

Ihr Framework steht nicht in der Liste? Die Integration ist nur ein <script>-Tag, daher funktioniert das Snippet unter Plain HTML / static sites in praktisch jedem Framework. Für eine stärker komponenten-native Variante funktioniert das Custom Element in jedem Template.

React

import { useEffect } from 'react'

export function OlotalkAssistant() {
  useEffect(() => {
    if (document.getElementById('olotalk-loader')) return

    window.OlotalkConfig = {
      assistantId: process.env.NEXT_PUBLIC_OLOTALK_ASSISTANT_ID!,
    }

    const script = document.createElement('script')
    script.id = 'olotalk-loader'
    script.src =
      'https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js'
    script.async = true
    document.body.appendChild(script)

    return () => {
      window.Olotalk?.('destroy')
    }
  }, [])

  return null
}

Fügen Sie <OlotalkAssistant /> in Ihr Root-Layout ein.

Next.js (Script-Komponente)

Erfordert Next.js 14+. Das Beispiel unten folgt den Konventionen von Next.js 16.

Verwenden Sie data-*-Attribute direkt auf dem <Script>-Tag. Lesen Sie die Assistant-Config in einer asynchronen Server-Komponente aus normalen, nicht mit NEXT_PUBLIC_ versehenen Env-Variablen, damit sie zur Request-Zeit ausgewertet wird.

// app/layout.tsx
import Script from 'next/script'

export const dynamic = 'force-dynamic'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const loaderSrc = process.env.OLOTALK_LOADER_SRC
  return (
    <html>
      <body>
        {children}
        {loaderSrc && (
          <Script
            id="olotalk-loader"
            src={loaderSrc}
            strategy="afterInteractive"
            data-olotalk-assistant-id={process.env.OLOTALK_ASSISTANT_ID}
          />
        )}
      </body>
    </html>
  )
}

Vue / Nuxt

// plugins/olotalk.client.ts
export default defineNuxtPlugin(() => {
  window.OlotalkConfig = {
    assistantId: useRuntimeConfig().public.olotalkAssistantId,
  }

  const script = document.createElement('script')
  script.src =
    'https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js'
  script.async = true
  document.body.appendChild(script)
})

Astro

Fügen Sie den Loader in Ihr gemeinsames Layout ein. Astro bündelt <script>-Tags standardmäßig; markieren Sie das Tag mit is:inline, damit der externe Loader und seine data--Attribute intakt bleiben.

---
// src/layouts/Layout.astro
const assistantId = import.meta.env.PUBLIC_OLOTALK_ASSISTANT_ID
---
<slot />

<script
  is:inline
  src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
  data-olotalk-assistant-id={assistantId}
  async
></script>

Setzen Sie PUBLIC_OLOTALK_ASSISTANT_ID in Ihrer .env.

Plain HTML / statische Sites

<!DOCTYPE html>
<html>
  <body>
    <!-- Ihr Seiteninhalt -->

    <script
      src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
      data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
      async
    ></script>
  </body>
</html>

Remix

Fügen Sie den Loader in app/root.tsx nach der <Scripts />-Komponente ein. Verwenden Sie defer statt async.

// app/root.tsx
import { Scripts } from '@remix-run/react'

export default function App() {
  return (
    <html>
      <body>
        <Outlet />
        <Scripts />
        <script
          src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
          data-olotalk-assistant-id={process.env.OLOTALK_ASSISTANT_ID}
          defer
        />
      </body>
    </html>
  )
}

Env-Variablen sind in Remix standardmäßig serverseitig. Falls Sie sie im Client benötigen, geben Sie sie über einen loader weiter.

SvelteKit

Option A, src/app.html

<!-- src/app.html -->
<body>
  %sveltekit.body%

  <script
    src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
    data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
    async
  ></script>
</body>

Option B, +layout.svelte mit Env-Injektion

<!-- src/routes/+layout.svelte -->
<script>
  import { onMount } from 'svelte'
  export let data

  onMount(() => {
    if (document.getElementById('olotalk-loader')) return

    window.OlotalkConfig = {
      assistantId: data.olotalkAssistantId,
    }

    const script = document.createElement('script')
    script.id = 'olotalk-loader'
    script.src =
      'https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js'
    script.async = true
    document.body.appendChild(script)
  })
</script>

<slot />
// src/routes/+layout.server.ts
import { env } from '$env/static/private'

export function load() {
  return {
    olotalkAssistantId: env.OLOTALK_ASSISTANT_ID,
  }
}

Angular

Option A, src/index.html

<!-- src/index.html -->
<body>
  <app-root></app-root>

  <script
    src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
    data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
    async
  ></script>
</body>

Option B, AppComponent mit environment.ts

// src/app/app.component.ts
import { Component, OnInit } from '@angular/core'
import { environment } from '../environments/environment'

@Component({ selector: 'app-root', templateUrl: './app.component.html' })
export class AppComponent implements OnInit {
  ngOnInit() {
    if (document.getElementById('olotalk-loader')) return

    ;(window as any).OlotalkConfig = {
      assistantId: environment.olotalkAssistantId,
    }

    const script = document.createElement('script')
    script.id = 'olotalk-loader'
    script.src =
      'https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js'
    script.async = true
    document.body.appendChild(script)
  }
}
// src/environments/environment.ts
export const environment = {
  production: false,
  olotalkAssistantId: 'ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy',
}

Inline in einem Framework

Alle Guides oben mounten die Corner bubble. Wenn Sie den Assistant inline in Ihr eigenes Layout setzen möchten, gibt es zwei framework-unabhängige Wege.

Am einfachsten: das Custom Element. <olotalk-assistant> rendert dort, wo Sie das Tag platzieren. Mit mode="inline" erscheint es inline in jedem HTML- oder Komponenten-Template.

// einmal beim App-Start
import { defineOlotalkAssistantElement } from '@olotalk/assistant'
defineOlotalkAssistantElement()
<div style="height: 600px">
  <olotalk-assistant assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy" mode="inline"></olotalk-assistant>
</div>

Imperativ: in ein Ref mounten. Wenn Sie das Mounting lieber selbst steuern möchten, rufen Sie createAssistant(element, …) mit dem Container auf.

import { useEffect, useRef } from 'react'
import { createAssistant } from '@olotalk/assistant'

export function InlineAssistant() {
  const ref = useRef<HTMLDivElement>(null)
  useEffect(() => {
    if (!ref.current) return
    const assistant = createAssistant(ref.current, {
      assistantId: 'ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy',
      mode: 'inline',
    })
    return () => { void assistant.destroy() }
  }, [])

  return <div ref={ref} style={{ height: 600 }} />
}

Der Container braucht eine explizite Höhe. Beide Varianten sind ausführlich in der Assistant-JS-API dokumentiert.


Self-Hosting

Wenn Sie das Assistant-Bundle auf Ihrer eigenen Infrastruktur hosten möchten:

  1. Installieren Sie die npm-Pakete auf einer Maschine mit Node.js:
    npm install @olotalk/assistant-loader @olotalk/assistant
    
  2. Kopieren Sie die dist-Dateien auf Ihren statischen Asset-Server:
    cp node_modules/@olotalk/assistant/dist/olotalk-assistant.js /your/assets/
    cp node_modules/@olotalk/assistant/dist/olotalk-assistant.iife.js /your/assets/
    cp node_modules/@olotalk/assistant/dist/olotalk-assistant.css /your/assets/
    cp node_modules/@olotalk/assistant-loader/dist/loader.iife.js /your/assets/
    cp node_modules/@olotalk/assistant/dist/version.json /your/assets/
    
  3. Setzen Sie data-olotalk-cdn-base auf die URL, unter der diese Assets ausgeliefert werden:
    <script
      src="https://assets.example.com/olotalk/loader.iife.js"
      data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
      data-olotalk-cdn-base="https://assets.example.com/olotalk"
      async
    ></script>
    

Der Loader lädt auf modernen Browsern {cdnBase}/olotalk-assistant.js, fällt wenn nötig auf {cdnBase}/olotalk-assistant.iife.js zurück und lädt CSS von {cdnBase}/olotalk-assistant.css. Außerdem fordert er {cdnBase}/version.json fürs Cache-Busting an, ohne diese Datei funktioniert alles, aber Sie sehen einen 404 in der Konsole, und Besucher behalten ein gecachtes Bundle womöglich länger.


Ihre Inhalte ingestieren

Olotalk baut die Wissensbasis Ihres Assistants auf, indem es die Seiten crawlt, auf die Sie zeigen, vollständig aus dem Dashboard heraus, ohne zusätzliche API-Calls oder Scripts.

Öffnen Sie Ihren Assistant über Assistants und gehen Sie zum Schritt Source. Zwei Dinge bleiben unabhängig voneinander:

  • Source URLs, welche Inhalte in die Wissensbasis indexiert werden
  • Installationsdomains, auf welchen Domains der Launcher laufen darf (im Schritt Installation)

Fügen Sie die URLs hinzu, die indexiert werden sollen, oder geben Sie Ihre Root-Domain ein und lassen Sie Olotalk Seiten aus sitemap.xml und robots.txt entdecken. Starten Sie dann den Crawl. Das Panel Ingestion status, coverage & languages im selben Schritt zeigt Ihnen den Fortschritt. Wenn Sie Inhalte aktualisieren, starten Sie dort einfach erneut einen Crawl.


Sicherheit

Install-Domain-Allowlist, Olotalk validiert jede Request gegen die am Assistant konfigurierten Install-Domains. Fügen Sie den Hostnamen, auf dem Ihr Snippet läuft, im Builder im Schritt Installation unter Installationsdomains hinzu. Nicht gelistete Domains erhalten 403.

Rate Limiting, der Config-Endpoint ist auf 60 Requests pro IP und Minute begrenzt. Der Ask-Endpoint übernimmt die per-Assistant-Einstellung rateLimitPer5Min (Standard: 20).

Request Tracing, jede Response enthält einen Header x-request-id. Wenn Sie selbst einen Wert mitsenden, gibt Olotalk ihn unverändert zurück, andernfalls wird eine UUID erzeugt.

Content Security Policy, wenn Ihre Site eine strenge CSP nutzt, ergänzen Sie:

script-src 'self' https://cdn.jsdelivr.net;
style-src 'self' https://cdn.jsdelivr.net;
connect-src 'self' https://api.olotalk.com https://cdn.jsdelivr.net;

Passen Sie cdn.jsdelivr.net an, falls Sie self-hosten. Wenn Sie den CTA book_meeting nutzen, erlauben Sie zusätzlich das Scheduler-Iframe mit frame-src https://calendly.com;.