SDK dokumentáció

Fejlessz az EchoAI-jal

Ágyazz be intelligens chat asszisztenst a weboldaladba néhány sor kóddal.

Kezdés Kódpéldák
Kinek szól ez az oldal?
Ez a fejlesztői referencia — JavaScript SDK, minden opció, data-attribútum, programozott vezérlés és esemény egy helyen. Ha kódolás nélkül szeretnéd kitenni az asszisztenst (lebegő gomb, WordPress, Framer), kezdd a Beágyazás a weboldalra oldalon.

Ezen az oldalon

Gyors kezdés

Referencia

Példák

Gyors kezdés

Két perc alatt üzembe helyezed az asszisztensed ezzel a két lépéssel.

1
SDK script hozzáadása

Illeszd be az EchoAI SDK scriptet a HTML fájlodba, közvetlenül a záró </body> tag elé.

HTML 
<script src="https://cdn.echoaichat.com/sdk/echo-sdk.js"></script>
2
Widget inicializálása

Hozz létre egy új EchoSDK példányt az asszisztens-azonosítóddal.

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762'
});
Kész is!
Az asszisztensed üzemkész. A widget a #echo-chat azonosítójú elemben jelenik meg. Az asszisztens-azonosítót az asszisztens Beágyazás oldalán találod.

Telepítés

Teljes HTML példa a gyors induláshoz.

HTML 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website</title>
</head>
<body>
  <!-- Your website content -->

  <!-- EchoAI Chat Container -->
  <div id="echo-chat" style="height: 500px;"></div>

  <!-- EchoAI SDK -->
  <script src="https://cdn.echoaichat.com/sdk/echo-sdk.js"></script>
  <script>
    const echoWidget = new EchoSDK({
      container: '#echo-chat',
      assistantIdentifier: 'dovjmm372762',
      height: '100%'
    });
  </script>
</body>
</html>
JavaScript nélkül is megy
Ha nem akarsz JavaScriptet írni, a widget teljesen HTML data-attribútumokkal is beállítható — az SDK automatikusan elindul.

Élő előnézet

Állítsd be a widget opcióit alább, és valós időben látod a változásokat. A generált kód automatikusan frissül.

Megjelenő szövegek
EchoAI widget betöltése…
JavaScript
Élő demó
Ez a widget egy valódi EchoAI asszisztenshez csatlakozik. Változtasd meg az opciókat, és az előnézet automatikusan frissül.

Alapbeállítások

A konstruktor (new EchoSDK({ ... })) összes legfelső szintű opciója.

Opció Típus Alapérték Leírás
assistantIdentifier Required string — Az asszisztens egyedi azonosítója a vezérlőpultról. Beágyazni csak publikus asszisztenst lehet.
container string | HTMLElement — CSS-szelektor vagy DOM-elem, ahova a chat kerül. Beágyazott módhoz kötelező; lebegő gomb módban nem kell (a chat a <body>-ra kerül).
mode 'full' | 'preview' full Asztali nézetben a preview üdvözlő képernyőt + indító kérdéseket + „Chat indítása” gombot mutat. Mobilon mindig preview. Lásd Preview mód.
theme string pink Színtéma: pink, purple, blue, green, amber. Érvénytelen / hiányzó érték → pink.
height string | number 480px / 80vh A widget magassága (pl. „500px", „100%", 500). Megadás nélkül asztalon 480px, mobilon 80vh. A % / auto 80vh-ra esik vissza, hogy a lista görgessen ne nőjön.
autoFocus boolean true Betöltéskor a beviteli mezőre fókuszál. Alapértelmezett: true.
userContext string — További kontextus a felhasználóról (max. 1000 karakter, efölött hibát dob). Lásd Felhasználói kontextus.
urlContextOptions object — Az aktuális oldal URL-jének átadása az AI-nak. Lásd URL kontextus.
starterQuestions NEW Array — Az alapértelmezett indító kérdések felülírása (max. 5). Lásd Indító kérdések.
textConfig object — A felület szövegeinek testreszabása. Lásd Szövegek testreszabása.
floatingButton object — Lebegő gomb mód bekapcsolása és beállítása. Lásd Lebegő gomb.
header object — { enabled: boolean } — a chat fejlécének láthatósága. Beágyazott módban alapból rejtett; lebegő módban mindig látszik.
onError function — Hiba esetén lefutó callback: (error: Error) => void.
Fejléc példa
A fejléc alapból csak lebegő gomb módban látszik. Beágyazott módban így kapcsolod be:
JavaScript
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  header: {
    enabled: true
  }
});

Szövegek testreszabása

A felület szövegeit a textConfig opcióval szabhatod testre.

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  textConfig: {
    inputPlaceholder: 'Ask me anything...',
    sourcesLabel: 'Knowledge Sources',
    searchingText: 'Searching...',
    toolsText: 'Processing...',
    loadingText: 'Thinking...',
    startButtonLabel: 'Start chat'
  }
});
Tulajdonság Típus Leírás
inputPlaceholder string A beviteli mező helykitöltő szövege
sourcesLabel string A Tudásforrások szekció címkéje
searchingText string Keresés közben megjelenő szöveg
toolsText string Eszközök feldolgozása közben megjelenő szöveg
loadingText string A válasz betöltése közben megjelenő szöveg
startButtonLabel string A preview mód „Chat indítása” gombjának felirata (alapértelmezett: „Start chat”)

Lebegő gomb

Jelenítsd meg a chatet lebegő gombként, amely egy felugró ablakot nyit. Ha bekapcsolod, a container nem kell — a chat a <body>-ra kerül.

JavaScript 
const echoWidget = new EchoSDK({
  assistantIdentifier: 'dovjmm372762',
  floatingButton: {
    enabled: true,
    position: 'bottom_right',
    tooltip: 'Chat with us!',
    width: '400px',
    height: '600px'
  }
});
Tulajdonság Típus Leírás
enabled boolean A lebegő gomb mód bekapcsolása
position string bottom_right (alapértelmezett) | bottom_left | top_right | top_left
icon string Egyéni ikon URL-je. Ha üresen hagyod, a gomb az asszisztens feltöltött profilképét használja.
tooltip string A gombra mutatáskor megjelenő tooltip szövege
badgeCount number A gombon megjelenő piros számjelvény (pl. olvasatlan üzenetek). Az első chatnyitás után elrejtjük.
width / height string | number A felugró ablak méretei (alapértelmezett: 400 × 630)

URL kontextus

Tudasd az asszisztenssel, hogy a látogató éppen melyik oldalon van. Így az AI az oldalhoz illő válaszokat adhat — az árazás oldalon például proaktívan reagál az árazási kérdésekre.

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  urlContextOptions: {
    autoDetect: true,           // alapból false (lásd a megjegyzést)
    customUrl: 'https://pelda.hu/arazas'
  }
});
Tulajdonság Típus Alapérték Leírás
autoDetect boolean false Automatikusan a window.location URL-jét használja (lekérdezés és horgony nélkül). Jelenleg alapból kikapcsolva.
customUrl string — Konkrét URL átadása az automatikus felismerés helyett. Megadás esetén ezt használja, az autoDetect beállítástól függetlenül.
Az autoDetect jelenleg false
Egy átmeneti frontend-hiba miatt az autoDetect jelenleg alapból false, akkor is, ha nem adsz meg urlContextOptions-t. Ha URL-kontextust szeretnél, állítsd kifejezetten true-ra, vagy adj meg customUrl-t. (A hiba javítása után az alapérték visszaáll true-ra.)

Felhasználói kontextus

Adj át adatokat az aktuális felhasználóról vagy munkamenetről az asszisztensnek. Az AI háttérinformációként megkapja ezt a kontextust, így személyre szabott válaszokat adhat anélkül, hogy a felhasználónak újra meg kellene adnia ezeket az adatokat.

Hogyan működik
Az AI ismert adatként kapja meg a kontextust, és közvetlenül ebből válaszol — anélkül, hogy a tudásbázisban keresgélne. Ha például átadod a felhasználó csomagját, az AI azonnal megválaszolja a „Milyen csomagom van?" kérdést a kontextusból.

Egyszerű szöveg

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: 'Company size: 50-100 employees, Industry: Healthcare, Plan: Pro'
});

JSON formátum (ajánlott)

Strukturált adatokhoz használd a JSON.stringify()-t. Így egyértelműen címkézett mezőket kap az AI.

JavaScript 
// Structured context with JSON (recommended)
const user = await fetchCurrentUser();

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: JSON.stringify({
    userId: user.id,
    membershipTier: 'gold',
    companySize: '50-100 employees',
    accountAge: '2 years',
    cartItems: 3,
    rewardPoints: 1250
  })
});

Dinamikus kontextus

Építsd fel a kontextust az alkalmazásod állapotából, az inicializáláskor.

JavaScript 
// Dynamic context based on application state
function buildContext() {
  const user = getCurrentUser();
  const cart = getCartState();

  return JSON.stringify({
    name: user.firstName,
    plan: user.subscription.plan,
    cartTotal: cart.total,
    itemCount: cart.items.length,
    preferredLanguage: user.locale
  });
}

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: buildContext()
});

Korlátok és szabályok

Szempont Részlet
Maximális hossz 1000 karakter — efölött hibát dob
Típus Csak string (egyszerű szöveg vagy JSON)
Hatókör Beszélgetésenként — a beszélgetés létrehozásakor állítódik be. Futás közbeni módosításhoz használd a setUserContext() + resetThread() párost (lásd Programozott vezérlés).
Thread-kulcs Eltérő kontextus eltérő beszélgetést kap — a böngésző a echo:threadId:<asszisztens>:<kontextus-hash> kulcson tárolja.
Validáció Kliens- (SDK) és szerveroldalon (API) is ellenőrizzük

Bevált gyakorlatok

Ezt tedd
  • Teljes nevek helyett használj azonosítókat (userId: "user_123")
  • Adj át nem érzékeny metaadatokat: csomag, cégméret, preferenciák
  • Strukturált adatokhoz használj JSON formátumot
  • Csak olyan adatot adj át, amely javítja az AI válaszait
Ezt ne
  • Jelszó, TAJ-szám vagy bankkártyaadat átadása
  • Különösen érzékeny személyes adatok tárolása
  • Olyan adat átadása, amelyet a felhasználó nem szeretne megosztani az AI-val
  • API-kulcsok vagy hozzáférési adatok átadása

Data-attribútumok (JavaScript nélkül)

Az SDK teljesen HTML data-echo-* attribútumokkal is beállítható, egyetlen sor JavaScript írása nélkül. Az SDK automatikusan elindul, amint talál egy data-echo-container attribútumú elemet, és a példányt a window.echoInstance-en érheted el.

HTML 
<div
  data-echo-container
  data-echo-assistant-identifier="dovjmm372762"
  data-echo-height="500"
  data-echo-theme="pink"
></div>
<script src="https://cdn.echoaichat.com/sdk/echo-sdk.js"></script>
Attribútum Megfelelő opció Megjegyzés
data-echo-container Required — Jelenlétével indítja el az auto-init folyamatot. Ez az elem lesz a chat konténere (lebegő mód kivételével).
data-echo-assistant-identifier Required assistantIdentifier Az asszisztens egyedi azonosítója.
data-echo-title title Cím metaadat.
data-echo-description description Leírás metaadat.
data-echo-auto-focus autoFocus Csak akkor fókuszál, ha az értéke pontosan "true". Hiányában false (eltér a JS opció true alapértékétől).
data-echo-height height A widget magassága (pl. "500", "100%").
data-echo-theme theme pink | purple | blue | green | amber.
data-echo-text-input-placeholder textConfig.inputPlaceholder Beviteli mező helykitöltője.
data-echo-text-sources-label textConfig.sourcesLabel Tudásforrások címke.
data-echo-text-searching textConfig.searchingText Keresés szövege.
data-echo-text-tools textConfig.toolsText Eszközök szövege.
data-echo-text-loading textConfig.loadingText Betöltés szövege.
data-echo-floating-enabled floatingButton.enabled Lebegő gomb mód ("true" esetén).
data-echo-floating-position floatingButton.position A gomb pozíciója.
data-echo-floating-icon floatingButton.icon Egyéni gombikon URL-je.
data-echo-floating-tooltip floatingButton.tooltip Tooltip szövege.
data-echo-floating-badge floatingButton.badgeCount Számjelvény a gombon (egész szám).
data-echo-floating-width floatingButton.width A felugró ablak szélessége.
data-echo-floating-height floatingButton.height A felugró ablak magassága.
data-echo-header-enabled header.enabled Fejléc láthatósága. Csak akkor rejti el, ha az értéke "false".
data-echo-user-context userContext Felhasználói kontextus (max. 1000 karakter).
data-echo-url-context-auto-detect urlContextOptions.autoDetect Az URL automatikus felismerése ("false" kapcsolja ki).
data-echo-url-context-custom-url urlContextOptions.customUrl Konkrét URL átadása.
data-echo-starter-questions starterQuestions JSON-tömb, pl. '[{"question":"..."}]'. Érvénytelen JSON esetén figyelmen kívül hagyjuk.
Mikor melyiket
A data-attribútumos módszer no-code beágyazáshoz ideális (lásd a Beágyazás a weboldalra oldalt). Ha futás közben vezérelnéd a chatet (kontextus-frissítés, thread-reset), használd a programozott API-t.

Programozott vezérlés

Az auto-init példány a window.echoInstance objektumon érhető el. Saját kezűleg létrehozott példányokon (new EchoSDK(...)) ugyanezek a metódusok hívhatók.

JavaScript 
// Az auto-init példány a window.echoInstance objektumon érhető el
const echo = window.echoInstance;

// Beszélgetés visszaállítása (új thread indul)
await echo.resetThread();

// Visszaállítás frissített kontextussal
await echo.resetThread({ userContext: 'Pro user, magyar nyelv' });

// Kontextus frissítése reset nélkül
echo.setUserContext('Új kosártartalom: 5 termék');
const ctx = echo.getUserContext();

// Opciók frissítése futás közben (újrarendereli a chatet)
echo.update({ theme: 'blue', autoFocus: true });
Metódus Visszatérés Leírás
resetThread(options?) Promise<boolean> A beszélgetés visszaállítása — új thread indul. Opcionális { userContext } az új beszélgetés kontextusához.
setUserContext(context) void A felhasználói kontextus frissítése (max. 1000 karakter, efölött hibát dob). A következő thread veszi át; gyakran resetThread() előtt hívják.
getUserContext() string | undefined Az aktuális felhasználói kontextus lekérése.
update(options) void Opciók frissítése futás közben (pl. theme, autoFocus, textConfig) — újrarendereli a chatet.
mount(container) boolean A chat (újra)csatolása egy CSS-szelektorhoz vagy DOM-elemhez.
unmount() void A chat teljes eltávolítása — a lebegő gomb és a felugró panel is megszűnik.
Kontextus-csere helyes sorrendje
Ha a beszélgetés közben változik a felhasználó adata, előbb hívd a setUserContext()-et, majd a resetThread()-et — így az új thread már az új kontextussal indul. Vagy egy lépésben: resetThread({ userContext: '...' }).

Saját példány kezelése

JavaScript 
// Saját kezűleg létrehozott példány
const echo = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762'
});

// Áthelyezés másik konténerbe
echo.mount('#another-container');

// Teljes eltávolítás (lebegő gomb + chat is eltűnik)
echo.unmount();

Események

Az SDK window-szintű egyéni eseményeket (echo:*) bocsát ki, amelyekre window.addEventListener-rel iratkozhatsz fel.

JavaScript 
// Hibaesemény figyelése
window.addEventListener('echo:error', (e) => {
  console.error('Echo hiba:', e.detail.error);
});

// Új thread létrejöttekor (resetThread után) lefutó esemény
window.addEventListener('echo:thread-reset', (e) => {
  console.log('Új beszélgetés azonosító:', e.detail.threadId);
});
Esemény Mikor detail
echo:error Hiba történik az auto-init példányban (a onError callback mellett is kibocsátja) { error: Error }
echo:thread-reset Új beszélgetés jött létre (sikeres resetThread() után) { threadId: string }
Belső események
Az SDK néhány további eseményt belső koordinációra használ (mobil kibontás/összecsukás, billentyűzet-állapot, viewport-átméretezés, thread-reset kérés) — ezek a kliens belső működéséhez tartoznak, és integrációban nem szükséges rájuk építened.

Hibaelhárítás

Tünet Ok / megoldás
Nem jelenik meg a chat Ellenőrizd, hogy jó-e az assistantIdentifier, hogy az asszisztens publikus típusú-e, és hogy a container elem létezik-e a DOM-ban a script lefutásakor.
A widget egyre nő (nem görget) Adj meg fix height-et (pl. "500px"). A % / auto érték 80vh-ra esik vissza, ha a szülő magassága nem meghatározott — így a lista görget, nem nő végtelenül.
„Eltörnek a stílusok” A chat Shadow DOM-ban fut, teljesen elszigetelt stílussal: az oldalad megjelenése nem hat rá, és a chat sem változtatja meg az oldalad kinézetét. Itt nincs teendőd.
Nem tölt be a betűtípus A chat magával hozza a saját betűtípusát (Inter, a Google Fontsról a Shadow DOM-ba töltve). Ha a hálózat ezt nem engedi betölteni, automatikusan a rendszer betűtípusára vált — ez nem hiba.
Nem marad meg a beszélgetés az oldalak között A beszélgetést a látogató böngészője localStorage-ban jegyzi meg, az asszisztenshez (és a kontextushoz) kötve: echo:threadId:<asszisztens>[:<kontextus-hash>]. Használj ugyanazt az assistantIdentifier-t (és ha van, ugyanazt a userContext-et) minden oldalon. Eltérő kontextus külön beszélgetést kap.
Az URL kontextus nem érvényesül Az autoDetect jelenleg alapból false — állítsd kifejezetten true-ra, vagy adj meg customUrl-t (lásd URL kontextus).
A felhasználói kontextus hibát dob A userContext max. 1000 karakter lehet. Hosszabb érték esetén az SDK hibát dob — rövidítsd, vagy adj át kevesebb mezőt.

Indító kérdések

Írd felül az alapértelmezett indító kérdéseket, és szabd testre a chat kezdeti élményét.

Mik azok az indító kérdések?
Az indító kérdések a chat megnyitásakor jelennek meg, gyors beszélgetésindítóként. Az SDK-ból felülírhatod őket, így minden oldalhoz külön kérdéseket adhatsz.

Alaphasználat

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  starterQuestions: [
    { question: 'What are your pricing plans?' },
    { question: 'How do I get started?' },
    { question: 'Can I see a demo?' }
  ]
});

Hogyan működik

  • Legfeljebb 5 kérdés — a többit figyelmen kívül hagyjuk
  • Kérdésenként max. 200 karakter — a hosszabb szöveget levágjuk
  • Üres tömb [] — minden indító kérdést elrejt
  • undefined — a vezérlőpulton beállított kérdéseket használja

Oldalspecifikus példa

JavaScript 
// Dynamic questions based on current page
function getStarterQuestions() {
  const path = window.location.pathname;

  if (path.includes('/pricing')) {
    return [
      { question: 'Compare pricing plans' },
      { question: 'Do you offer discounts?' },
      { question: "What's included in each plan?" }
    ];
  }

  if (path.includes('/docs')) {
    return [
      { question: 'How do I install the SDK?' },
      { question: 'Show me code examples' }
    ];
  }

  // Use dashboard defaults
  return undefined;
}

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  starterQuestions: getStarterQuestions()
});
Jó tudni
Az SDK-ban megadott kérdések felülírják a vezérlőpult beállításait. A vezérlőpulton végzett módosítások nem érintik a felülírt oldalakat.

Kódpéldák

Gyakori integrációs minták különböző felhasználási esetekhez.

Beágyazott widget

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  height: '600px',
  autoFocus: true,
  textConfig: {
    inputPlaceholder: 'Ask me anything...',
    sourcesLabel: 'References'
  }
});

Felhasználói kontextussal

JavaScript 
// Personalize based on logged-in user
const user = getCurrentUser();

const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  userContext: `Name: ${user.name}, Plan: ${user.plan}`,
  starterQuestions: [
    { question: 'How do I upgrade my plan?' },
    { question: "What's new in my account?" }
  ]
});

Teljes konfiguráció

JavaScript 
const echoWidget = new EchoSDK({
  container: '#echo-chat',
  assistantIdentifier: 'dovjmm372762',
  height: '100%',
  autoFocus: true,
  theme: 'pink',
  mode: 'preview',

  textConfig: {
    inputPlaceholder: 'How can I help you today?',
    sourcesLabel: 'Knowledge Sources',
    searchingText: 'Searching...',
    toolsText: 'Processing...',
    loadingText: 'Generating response...',
    startButtonLabel: 'Start chat'
  },

  header: {
    enabled: true
  },

  userContext: 'Pro user, prefers detailed answers',

  urlContextOptions: {
    autoDetect: true
  },

  starterQuestions: [
    { question: "What's new this week?" },
    { question: 'Show me advanced features' },
    { question: 'API integration guide' }
  ],

  onError: (error) => {
    console.error('Echo SDK error:', error);
  }
});
Kapcsolódó