Hozzáadás a webhelyhez

Hogyan kell hozzáadni

Adja hozzá ügynökét bármely webhelyhez az ügyintéző beállításaiban található Widget konfigurálása párbeszédpanel segítségével.

1. lépés: Nyissa meg az ügynök beállításait az ügynökszerkesztő jobb felső sarkában található fogaskerék ikonra kattintva.

2. lépés: Görgessen a Hozzáadás a webhelyhez szakaszhoz, és kattintson a A Widget konfigurálása lehetőségre.

3. lépés: Engedélyezze a beágyazást, adja hozzá webhelye domainjét az Engedélyezett tartományokhoz, válasszon egy Modultípust (Hang vagy Csevegés) és egy beágyazási módot (Lebegő widget, Inline Component vagy Fej nélküli (hozzon saját felhasználói felületet)), és ha szükséges, állítsa testre a gombot (pozíció, konfiguráció és kattintás**).

4. lépés: Másolja ki a generált beágyazási kódot, és illessze be weboldalára az ügynök teszteléséhez.

Widget típusok

Minden beágyazási widget hangmodul vagy csevegési widget – válassza ki a típust a Widget konfigurálása párbeszédpanelen. Mindkét típus támogatja mindhárom beágyazási módot.

Típus	Hogyan lépnek kapcsolatba a látogatók
Hang	A látogatók élő hanghíváson keresztül beszélnek az ügynökével (WebRTC, mikrofon szükséges).
Csevegés	A látogatók üzeneteket írnak be a csevegőpanelen, és az ügynök szövegként válaszol. Nincs mikrofon.

Hogyan viselkednek a csevegőbeszélgetések:

• A beszélgetés akkor kezdődik, amikor a látogató megnyitja a csevegést (kattint a csevegés gombra) – az ügynök köszönti először. Az oldalbetöltés önmagában soha nem indít el beszélgetést.
• Egy csevegés legfeljebb 1 óráig tart. Amikor lejár, a látogató felkínálja az Új csevegés indítása gombot, amely új beszélgetést indít el.
• Az oldal újratöltése új beszélgetést indít a következő megnyitáskor – a csevegési előzmények nem kerülnek át az oldalbetöltések során.
• Minden beszélgetés egyszer számít bele a beágyazási token használati korlátjába, ugyanúgy, mint egy hanghívás.
• A csevegési beszélgetések teljes átirattal jelennek meg az ügyintéző híváselőzményében.

Beágyazási módok

mód	Mit jelenít meg	Mikor kell használni
Lebegő widget	Egy pirula alakú CTA gomb az oldal sarkához rögzítve. A csevegési widgetek esetében a csevegőpanelt váltja.	Kulcsrakész élményt szeretne, amely nem zavarja a meglévő elrendezést.
Inline komponens	Az oldalon elhelyezett <div id="IntraCord-inline-container">-ben renderelt panel.	Azt szeretné, hogy az ügynök egy adott szakaszba legyen beágyazva (céloldal hős, támogatási lap stb.).
Fej nélküli	Nincs felhasználói felület. Csak az audio/csevegési folyamat, valamint egy JavaScript API a window.IntraCordWidget-n.	Teljes irányítást szeretne a felhasználói felület felett – saját gombjai, tervezési rendszere, keretállapota, animációi.

Előfeltételek

Ezek mindhárom módra érvényesek:

• Hangmodulok: HTTPS-en vagy http://localhost-n keresztül szolgálják ki az oldalt. A böngészők megtagadják a mikrofonhoz való hozzáférést sima HTTP-eredetű vagy file:// esetén. A csevegőmoduloknak nincs mikrofonkövetelményük, bár a HTTPS továbbra is ajánlott.
• Ha a Dashboardon az Engedélyezett tartományok értéket állítja be, adja meg a teszt eredetét (pl. localhost) – ellenkező esetben a modul elutasítja a kérelmeket. Hagyja üresen a listát az összes domain engedélyezéséhez.
• A Dashboardról másolt beágyazási kódrészlet egyetlen <script> címke, amely aszinkron módon tölti be a IntraCord-widget.js-t. A widget a betöltés után automatikusan inicializálódik, és felteszi a window.IntraCordWidget elemet. A visszahívásokat regisztráló kódnak meg kell várnia, amíg a widget elérhetővé válik.

Adja át a kontextust az ügynöknek

Az Ön oldala általában tud valamit a látogatóról – a nevét, tervét, kosárértékét, az olvasott cikket. Adja tovább, és ügynöke az első szótól kezdve használhatja.

!

Kontextus A kulcsnevek nem tartalmazhatnak pontokat, szóközöket, csöveket vagy kapcsos zárójeleket, mert ezek a karakterek strukturális jelentéssel bírnak a sablonkifejezésekben. Az érvénytelen bejegyzések leesett anélkül, hogy megakadályozta volna a beszélgetés megkezdését.

A Dashboardról másolt kódrészlet egy data-IntraCord-context attribútumot tartalmaz – a látogató részleteit tartalmazó JSON-objektumot. A kódrészlet egy kis rendszerindító funkció: a js a widget <script> eleme, amelyet létrehoz, és a kontextus hozzá van kapcsolva az elemhez, mielőtt hozzáadná az oldalhoz. A generált kódrészlet releváns része így néz ki (tartsa meg a generált js.src értéket, amely tartalmazza a beágyazási tokent):

<script>
  (function(d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
    js = d.createElement(s);
    js.id = id;
    js.src = '<dashboard-generated widget URL>';
    js.setAttribute('data-IntraCord-context', JSON.stringify({
      page_url: window.location.href,
      today: new Date().toISOString().slice(0, 10)
    }));
    js.async = true;
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'IntraCord-widget'));
</script>

Mivel az oldal betöltésekor JavaScriptbe van beépítve, bármit elhelyezhet benne, amit az oldal tud – a bejelentkezett ügyfél nevét, tervét, kosár tartalmát. Cserélje ki a JSON.stringify(...) belsejében lévő objektumot a generált kódrészletben, például:

{
  customer_name: currentUser.firstName,
  plan: currentUser.plan,
  cart: { items: cart.length, total: cart.total }
}

Ezután minden kulcs {{initial_context.<name>}} néven elérhető bármely Node-promptban:

Greet {{initial_context.customer_name | there}} and mention their {{initial_context.plan}} plan.

Az értékek lehetnek Stringok, számok, logikai értékek vagy beágyazott objektumok. Ez hang- és csevegőmoduloknál egyaránt működik, és az értékeket a rendszer rögzíti a beszélgetésben, így láthatja, mit kapott az ügynök.

Frissítse a környezetet az oldal betöltése után

Az attribútum az oldal betöltésekor rögzítésre kerül, ami nem fér bele egy egyoldalas alkalmazásba – a látogató bejelentkezik, útvonalat változtat vagy megtölt egy kosarat jóval a kódrészlet lefutása után. Ehhez hívja a setContext() számot:

window.IntraCordWidget.setContext({
  customer_name: user.firstName,
  plan: user.plan
});

Minden hívás beleolvad a már összegyűjtött kontextusba, így a beérkezésükkor részleteket adhat hozzá, és újra elküldheti a nevet a javításhoz. A getContext() az aktuális készletet adja vissza.

A kontextust a rendszer olvassa be, amikor egy beszélgetés kezdődik, így a setContext() a következő beszélgetésre vonatkozik – hívás közbeni vagy csevegés közbeni hívása nem változtatja meg a folyamatban lévőt (a widget konzolfigyelmeztetést naplóz, ha ezt teszi). A csevegőmodulok esetében a „következő” az Új csevegés indítása által elindított új beszélgetést tartalmazza a munkamenet lejárta után.

i

A modul szkriptje aszinkron módon töltődik be, ezért előfordulhat, hogy a window.IntraCordWidget még nem létezik, amikor az alkalmazás kódja először fut. Hívja a setContext()-t egy olyan eseményből, amely betöltés után aktiválódik – egy window.load figyelőből, vagy egy felhasználói műveletből, például a saját „Csevegés velünk” gombra kattintással. Ugyanerről az időzítési szabályról lásd az Életciklus-visszahívások részt.

Használja azt, amelyik illik: data-IntraCord-context ahhoz, amit az oldal tud a megjelenítéskor, setContext() pedig ahhoz, amit később megtanul. Egyesülnek, és a setContext() ismétlődő néven nyer.

!

A kontextus az oldalról származik, így a látogató elolvashatja és módosíthatja is, mielőtt elérné az ügynököt. Soha ne adja át a titkokat, és ne engedje, hogy az ügynök mit tegyen vagy nyilvánosságra hozzon – a plan: "pro"-t a megfogalmazásra utaló tippként kezelje, ne a jogosultság igazolásaként. Azokhoz az adatokhoz, amelyekben az ügynöknek meg kell bíznia, adjon át egy átlátszatlan azonosítót (például customer_id), és hagyja, hogy az IntraCord lekérje a valódi részleteket az API-ból a Pre-Call Data Fetch funkcióval.

Beszélgetésenként alkalmazható korlátok: legfeljebb 50 változó, névenként 64 karakter, értékenként 2000 karakter és összesen 8 KB. Bármi, ami egy határon túl van, elejtik, és a beszélgetés továbbra is elindul. A provider és runtime_configuration nevek fenntartva és figyelmen kívül hagyva.

Lebegő widget

Pilla alakú gombot jelenít meg az oldal egyik sarkához rögzítve.

• Hang: a gombra kattintva (mikrofon ikon + szöveg) hívás indul; ismételt kattintással véget ér. A gomb automatikusan frissíti címkéjét és színét a hívás életciklusa során: konfigurált szöveg → „Csatlakozás…” → „Hívás befejezése” → „Újrapróbálkozás” hiba esetén.
• Csevegés: a gombra kattintva (csevegés ikon + szöveg) megnyílik egy csevegőpanel, amely ugyanahhoz a sarokhoz van rögzítve; az ügynök üdvözli a látogatót, és a beszélgetés a panelben történik. A gombra (vagy a panel × gombjára) kattintva a panel bezárul a beszélgetés befejezése nélkül – az újranyitás ugyanazt az átiratot mutatja.

Állítsa be a Gomb szövege, Gombszín és Pozíció (felső/lent + bal/jobb) beállításokat a Dashboardon.

A gazdagép oldal nem ír JavaScriptet – a beágyazási kódrészlet beillesztése a teljes integráció. Ha szeretne előfizetni a hívás életciklus-eseményekre (pl. az analitika), lásd az alábbi Lifecycle callbacks részt.

Beépített komponens

Panelt jelenít meg az oldalon elhelyezett <div>-ben.

• Hang: állapotpanel (állapotikon + állapotszöveg + CTA gomb). Az állapotváltozások frissítik a panelt a helyén.
• Csevegés: először egy cselekvésre ösztönző képernyő; a gombra kattintva azt egy csevegőpanel váltja fel, amely kitölti a tárolót. Nincs szükség extra JavaScriptre.

Konfigurálja a gomb szövegét, gombszínét és a cselekvésre ösztönző szövegét a Dashboardon.

Sima HTML

Helyezzen egy <div> tárolót oda, ahol a widgetet meg szeretné jeleníteni. A widget automatikusan csatlakozik hozzá.

<!-- Paste the IntraCord embed snippet from the dashboard somewhere on the page -->
<div id="IntraCord-inline-container"></div>

Reagálj

Mivel a React beillesztése a widget szkriptje után előfordulhat, hogy már betöltődött, integrálja a initInline-t az első csatlakoztatáskor és a refresh-t újracsatlakozáskor. A window.IntraCordWidget lekérdezése az aszinkron szkript betöltésének kezelésére.

import { useEffect } from 'react';

declare global {
  interface Window {
    IntraCordWidget?: {
      initInline: (options: { container: HTMLElement }) => void;
      refresh: () => void;
      getState: () => { isInitialized: boolean };
    };
  }
}

export function Assistant() {
  useEffect(() => {
    let retries = 0;
    const tryInit = () => {
      const container = document.getElementById('IntraCord-inline-container');
      if (window.IntraCordWidget && container) {
        const { isInitialized } = window.IntraCordWidget.getState();
        if (isInitialized) window.IntraCordWidget.refresh();
        else window.IntraCordWidget.initInline({ container });
      } else if (retries++ < 50) {
        setTimeout(tryInit, 100);
      }
    };
    tryInit();
  }, []);

  return <div id="IntraCord-inline-container" />;
}

Fej nélküli mód

Fej nélküli módban a widget nem szúr be saját felhasználói felületet. Tetszőleges gombokat, szalaghirdetéseket vagy csevegési felületeket jelenít meg, és az ügynököt a JavaScript API-n keresztül irányítja.

JavaScript API (hangmodulok)

Módszer / Visszahívás	Leírás
window.IntraCordWidget.start()	Hanghívás indítása. Egy felhasználói gesztuskezelőn belülről kell meghívni (pl. click), hogy a böngésző engedélyezze a mikrofon hozzáférést.
window.IntraCordWidget.end()	Az aktív hívás befejezése.
window.IntraCordWidget.onCallStart(cb)	A start() meghívásakor aktiválódik (connecting állapot). Nincs payload.
window.IntraCordWidget.onCallConnected(cb)	Akkor aktiválódik, amikor a WebRTC kapcsolat létrejön. Teherbírás: { agentId, workflowRunId, token }.
window.IntraCordWidget.onCallDisconnected(cb)	Csak akkor tüzel, ha a hívás csatlakozott, amikor a bontás fut. Teherbírás: { agentId, workflowRunId, token, durationSeconds }.
window.IntraCordWidget.onCallEnd(cb)	Kikapcsol, amikor a hívási munkamenet megszakad (beleértve a sikertelen csatlakozási kísérleteket is). Nincs payload.
window.IntraCordWidget.onStatusChange(cb)	Minden állapotváltáskor tüzel. A visszahívás a következőt kapja: (status, text, subtext). Állapotértékek: idle, connecting, connected, failed.
window.IntraCordWidget.onError(cb)	Hibák esetén aktiválódik (mikrofonengedély megtagadva, szerverhiba stb.). A visszahívás egy Error objektumot kap.
window.IntraCordWidget.setContext(vars)	A látogatói kontextus egyesítése a következő híváshoz – lásd: Kontextus átadása az ügynöknek. Minden beágyazási módban működik, nem csak fej nélkül.

Minden on* setter egyetlen listenert kezel: ugyanazon setter ismételt hívása lecseréli az előző handlert.

JavaScript API (csevegési widgetek)

Method / Callback	Leírás
window.IntraCordWidget.startChat()	Indítson el egy beszélgetést. Az ügynök üdvözlete a onMessage-n keresztül érkezik.
window.IntraCordWidget.sendMessage(text)	Látogatói üzenetet küld. Egy Promise-t ad vissza, amely a frissített átirattal (Turnök tömbje) teljesül, vagy null, ha az üzenetet nem sikerült kézbesíteni.
window.IntraCordWidget.getMessages()	Az aktuális átirat Turnök tömbjeként: { id, status, user_message, assistant_message }, minden üzenet { text, created_at }.
window.IntraCordWidget.onMessage(cb)	Új ügynöki válaszonként egyszer aktiválódik. A visszahívás a következőt kapja: (text, turn).
window.IntraCordWidget.onChatStateChange(cb)	Minden csevegési állapotváltozáskor aktiválódik. Állapotok: idle, starting, ready, waiting (az ügynök válaszol), ended, expired, error.
window.IntraCordWidget.onError(cb)	Hibák miatt tüzel. A visszahívás egy Error objektumot kap.
window.IntraCordWidget.setContext(vars)	Egyesítse a látogatói kontextust a következő beszélgetéshez – lásd: Kontextus átadása az ügynöknek. Minden beágyazási módban működik, nem csak fej nélkül.

Csevegési módban a startChat() és a end() álnevek no-op lebontás (a csevegéshez nincs szükség), így az általános kódrészletek továbbra is működnek. A küldések soros formában vannak – sendMessage, amíg a válasz függőben van (waiting), a megoldás a null.

<button id="open-chat">Chat with us</button>
<div id="transcript"></div>
<input id="chat-input" /><button id="send-btn">Send</button>

<script>
  window.addEventListener('load', () => {
    window.IntraCordWidget.onMessage((text) => {
      const p = document.createElement('p');
      p.textContent = 'Agent: ' + text;
      document.getElementById('transcript').appendChild(p);
    });

    document.getElementById('open-chat').addEventListener('click', () => {
      window.IntraCordWidget.startChat();
    });

    document.getElementById('send-btn').addEventListener('click', async () => {
      const input = document.getElementById('chat-input');
      const p = document.createElement('p');
      p.textContent = 'You: ' + input.value;
      document.getElementById('transcript').appendChild(p);
      await window.IntraCordWidget.sendMessage(input.value);
      input.value = '';
    });
  });
</script>

i

Az időzítésről. A widget szkript aszinkron módon töltődik be, így előfordulhat, hogy a window.IntraCordWidget nem létezik abban a pillanatban, amikor a beépített <script> először fut. Az alábbi példák azt feltételezik, hogy a window.IntraCordWidget már elérhető, amikor a regisztráció fut. Ennek garantálása érdekében:

• Vanilla JS: csomagolja be regisztrációs kódját window.addEventListener('load', () => { /* register here */ })-be.
• Reagálás: a useEffect belsejében azonnal regisztráljon, ha document.readyState === 'complete', ellenkező esetben adjon hozzá egy egyszeri window.load figyelőt, amely tűzben regisztrál.
• A start() / end()-t hívó kattintáskezelőknek nincs szükségük védőre – mire a felhasználó rákattint, a widget már rég betöltődött.

Vanília JS

<button id="talk-btn">Talk to AI</button>

<script>
  let callStatus = 'idle';
  const btn = document.getElementById('talk-btn');

  function render() {
    btn.textContent =
      callStatus === 'connected' ? 'End Call'
      : callStatus === 'connecting' ? 'Connecting…'
      : callStatus === 'failed' ? 'Retry'
      : 'Talk to AI';
  }

  window.IntraCordWidget.onStatusChange((status) => {
    callStatus = status;
    render();
  });

  window.IntraCordWidget.onError((err) => {
    console.error('IntraCord error:', err.message);
  });

  btn.addEventListener('click', () => {
    if (callStatus === 'connected' || callStatus === 'connecting') {
      window.IntraCordWidget.end();
    } else {
      window.IntraCordWidget.start();
    }
  });
</script>

React + TypeScript

import { useEffect, useState } from 'react';

type CallStatus = 'idle' | 'connecting' | 'connected' | 'failed';

declare global {
  interface Window {
    IntraCordWidget: {
      start: () => void;
      end: () => void;
      onStatusChange: (cb: (status: CallStatus, text?: string, subtext?: string) => void) => void;
      onError: (cb: (err: Error) => void) => void;
    };
  }
}

export function TalkButton() {
  const [status, setStatus] = useState<CallStatus>('idle');

  useEffect(() => {
    window.IntraCordWidget.onStatusChange((s) => setStatus(s));
    window.IntraCordWidget.onError((err) => console.error('IntraCord error:', err.message));
  }, []);

  const isLive = status === 'connected' || status === 'connecting';
  const label = { idle: 'Talk to AI', connecting: 'Connecting…', connected: 'End Call', failed: 'Retry' }[status];

  return (
    <button onClick={() => (isLive ? window.IntraCordWidget.end() : window.IntraCordWidget.start())}>
      {label}
    </button>
  );
}

i

A start()-nek valódi felhasználói gesztuskezelőben kell futnia (click, touchend stb.). A böngészők megtagadják a mikrofonhoz való hozzáférést azon parancsfájlok számára, amelyek ezt egy másikon kívül kérik – a start() hívása setTimeout-ről vagy az oldalbetöltéskor engedélyhiba miatt meghiúsul.

Életciklus-visszahívások (minden mód)

A Headless JavaScript API on* visszahívásai mindhárom beágyazási módban működnek, nem csak Headless módban. Használja őket elemzésekhez vagy felhasználói felület aktiválásához a gazdagép oldalon, még akkor is, ha a widget saját felhasználói felületet jelenít meg (lebegő vagy beágyazott). A visszahívások (onCall*) hangmodulok esetén aktiválódnak; chat widgetekhez ugyanúgy használja a onMessage és a onChatStateChange parancsot.

window.IntraCordWidget.onCallConnected(({ agentId, workflowRunId }) => {
  analytics.track('voice_call_started', { agentId, workflowRunId });
});

window.IntraCordWidget.onCallDisconnected(({ workflowRunId, durationSeconds }) => {
  analytics.track('voice_call_ended', { workflowRunId, durationSeconds });
});

A onCallConnected és a onCallDisconnected csak akkor aktiválódik, ha a hívás valóban médiakapcsolatot hoz létre – a sikertelen csatlakozási kísérletek (pl. mikrofon megtagadása, hálózati hiba) nem váltják ki őket, így az elemzés tiszta marad.