De MagicAI Chat-widget met JavaScript aansturen – Magicline GmbH

In dit artikel leer je hoe je de MagicAI Chat-widget op je website met JavaScript aanstuurt, welke opties beschikbaar zijn, hoe ze samenwerken met de chatconfiguratie en welke limieten gelden.

Inhoud

Snelgids
Vereisten
Voorbeeld om mee te beginnen
Configuratieopties
Hoe je instellingen samenwerken met de chatconfiguratie
Limieten om rekening mee te houden
Praktijkvoorbeelden
Gerelateerde artikelen

Snelgids

Sluit de chatwidget op je website in met de code van de kaart Codefragment.
Roep in je eigen script window.SpaChatWidget?.configure({ ... }) aan met alleen de opties die je wilt wijzigen.
Controleer de retourwaarde: true betekent dat de waarden zijn geaccepteerd, false betekent dat er niets is toegepast.
Gebruik window.SpaChatWidget?.open() en window.SpaChatWidget?.close() om de chat te openen of te sluiten.

Vereisten

Gepubliceerde chatconfiguratie: een configuratie in conceptmodus levert geen insluitcode.
Widget ingesloten: de code van de kaart Codefragment staat op je website. Ze laadt het widgetscript met de identificatie van je chatconfiguratie. Hoe je haar insluit en welke technische vereisten gelden, lees je in MagicAI Chat instellen.
Je script draait na de widget: de onderstaande methoden zijn pas beschikbaar zodra het widgetscript is geladen. Draait je code eerder, dan wordt de aanroep overgeslagen en verandert er niets.

Voorbeeld om mee te beginnen

Zodra het widgetscript is geladen, kan je pagina het object window.SpaChatWidget gebruiken. Het biedt drie methoden: configure(), open() en close().

window.SpaChatWidget?.configure({
  teaserMessage: 'Hoe kunnen we je helpen?',
  teaserVisible: true,
  suggestions: [
    { buttonText: 'Lidmaatschappen bekijken', message: 'Welke lidmaatschappen zijn er?' }
  ]
});

window.SpaChatWidget?.open();  // Chat openen
window.SpaChatWidget?.close(); // Chat sluiten

De operator ?. maakt de aanroep veilig: als de widget nog niet is geladen, wordt de aanroep overgeslagen in plaats van een scriptfout te veroorzaken.

configure() geeft true terug wanneer de waarden worden geaccepteerd en false wanneer ze ongeldig zijn. Met de retourwaarde kun je je aanroep controleren:

const accepted = window.SpaChatWidget?.configure({ teaserVisible: false });

if (accepted === false) {
  console.warn('De chatwidget heeft de instellingen geweigerd.');
}

Als de widget nog niet is geladen, wordt de aanroep overgeslagen en is de retourwaarde undefined in plaats van true of false.

Configuratieopties

Alle opties zijn optioneel. Geef alleen de opties mee die je wilt wijzigen.

Optie	Type	Effect
`visible`	Boolean	Toont of verbergt de chatknop (launcher) zolang de chat gesloten is.
`teaserMessage`	String	Stelt de teasertekst naast de chatknop in en vervangt de teasertekst uit de chatconfiguratie. Spaties aan het begin en einde worden verwijderd. Max. 500 tekens.
`teaserVisible`	Boolean	Toont of verbergt de teasertekst.
`suggestions`	Array	Stelt de suggestieknoppen in en vervangt de suggesties uit de chatconfiguratie. Max. 3 items. Elk item heeft `buttonText` (verplicht, mag niet leeg zijn, max. 40 tekens) en optioneel `message` (max. 500 tekens). Dezelfde suggesties worden gebruikt naast de chatknop en op het startscherm van de geopende chat.
`suggestionsVisible`	Boolean	Toont of verbergt de suggestieknoppen naast de chatknop.
`startscreenSuggestionsVisible`	Boolean	Toont of verbergt de suggesties op het startscherm van de geopende chat, onafhankelijk van `suggestionsVisible`. Laat je de optie weg, dan geldt de instelling Suggesties weergeven op het startscherm uit de chatconfiguratie.
`isOpen`	Boolean	Opent (`true`) of sluit (`false`) de chat, net als `open()` en `close()`.

Wanneer een bezoeker op een suggestie klikt, start de chat met de tekst van message als eerste bericht van de bezoeker. Heeft een item geen message, dan wordt in plaats daarvan de buttonText verstuurd.

Hoe je instellingen samenwerken met de chatconfiguratie

Zonder instellingen vanaf je website gebruikt de widget de teaser en de suggesties uit de chatconfiguratie. Die beheer je zonder code in de chatconfiguratie onder Instellingen / MagicAI / Chatbot, kaart Basisinformatie.

Inhoud wordt vervangen: teaserMessage vervangt de ingestelde teasertekst, suggestions vervangt de volledige ingestelde lijst met suggesties.
Zichtbaarheid wordt apart geregeld: visible, teaserVisible, suggestionsVisible en startscreenSuggestionsVisible werken onafhankelijk van de inhoud. Geef je geen zichtbaarheidsoptie mee, dan toont de widget wat de chatconfiguratie levert.
Zichtbaar heeft inhoud nodig: een zichtbaarheidsoptie op true zetten maakt geen teasertekst of suggesties aan. Leveren noch je website noch de chatconfiguratie die, dan wordt er niets getoond.
Aanroepen worden samengevoegd: een latere aanroep behoudt de opties van eerdere aanroepen en wijzigt alleen de opties die erin staan. Een aanroep met alleen teaserVisible: false laat bijvoorbeeld een eerder ingestelde teaserMessage ongemoeid.
Vertraging: teasertekst en suggesties verschijnen ongeveer drie seconden nadat de widget is geladen naast de chatknop.
Gesloten teaser: sluit een bezoeker de teaser, dan blijven teaser en suggesties voor de rest van die browsersessie verborgen. Een aanroep met visible: true, teaserVisible: true of suggestionsVisible: true heft dit op en toont ze opnieuw. Daarmee overschrijft hij dus ook de keuze van de bezoeker.

Limieten om rekening mee te houden

Teasertekst: max. 500 tekens.
Suggesties: max. 3, elke tekst op de knop max. 40 tekens en niet leeg, elk bericht max. 500 tekens.
Ongeldige aanroep: configure() geeft false terug als een waarde het verkeerde type heeft, een limiet wordt overschreden of het argument geen gewoon object is. In dat geval wordt geen van de waarden uit de aanroep toegepast.
Geaccepteerd is niet geladen: een retourwaarde true bevestigt alleen dat de waarden geldig zijn. Het betekent niet dat de chat klaar is met laden of dat een gesprek is gestart.
Verbergen sluit niet: visible: false verbergt de chatknop, maar sluit een chat die al open is niet. Gebruik close() of isOpen: false om hem te sluiten.

Praktijkvoorbeelden

De volgende fragmenten zijn voorbeelden. Pas teksten en element-ID's aan je website aan en voer de code uit nadat het widgetscript is geladen.

Voorbeeld: de chat openen met je eigen knop

<button type="button" id="open-chat">Chat met ons</button>

<script>
  document.getElementById('open-chat').addEventListener('click', function () {
    window.SpaChatWidget?.open();
  });
</script>

Voorbeeld: een paginaspecifieke teaser tonen

Op een pagina over cursussen kun je bijvoorbeeld de ingestelde teasertekst vervangen door een passende tekst:

window.SpaChatWidget?.configure({
  teaserMessage: 'Vragen over onze cursussen? Vraag het ons gewoon.',
  teaserVisible: true
});

Voorbeeld: de chatknop op een pagina verbergen

Op een pagina waar de chatknop niet mag verschijnen, bijvoorbeeld een afrekenpagina:

window.SpaChatWidget?.configure({ visible: false });

Voer de aanroep uit op elke pagina waarvoor de instelling moet gelden.