De widget openen vanuit je eigen code

De drie functies

Alle drie de pakketten — @leadbot/components, @leadbot/react en @leadbot/vue — exporteren dezelfde drie functies om de gewone widget aan te sturen: openWidget(), closeWidget() en toggleWidget(). Het zijn gewone functies, geen componenten: je roept ze aan waar je maar wilt, meestal in een klikafhandelaar.

Ze werken op de widget die met de gewone scripttag op dezelfde pagina staat. Staat die er niet, dan gebeurt er simpelweg niets — de aanroep is dan een lege actie en er gaat niets stuk. Het maakt ook niet uit welk script als eerste geladen wordt: de functies zoeken de widget op het moment van de aanroep, niet bij het laden van de pagina.

Een headless flow (LeadBotFlow of mountFlow) staat al open in je pagina en heeft geen widget om te openen. Deze functies gaan dus altijd over de zwevende widget.

import { openWidget, closeWidget, toggleWidget } from "@leadbot/components";

openWidget();
openWidget({ stepUuid: "CHAT-STAP-ID" });
openWidget({ stepUuid: "CHAT-STAP-ID", message: "Wat kost LeadBot per maand?" });
closeWidget();
toggleWidget();

import { openWidget, closeWidget, toggleWidget } from "@leadbot/react";

openWidget();
openWidget({ stepUuid: "CHAT-STAP-ID" });
openWidget({ stepUuid: "CHAT-STAP-ID", message: "Wat kost LeadBot per maand?" });
closeWidget();
toggleWidget();

import { openWidget, closeWidget, toggleWidget } from "@leadbot/vue";

openWidget();
openWidget({ stepUuid: "CHAT-STAP-ID" });
openWidget({ stepUuid: "CHAT-STAP-ID", message: "Wat kost LeadBot per maand?" });
closeWidget();
toggleWidget();

De parameters van openWidget

openWidget() neemt één optioneel object met twee sleutels. Samen bepalen ze niet alleen dát de widget opengaat, maar ook waar de bezoeker uitkomt.

• stepUuid — string — De stap waar de widget direct naartoe navigeert. De bezoeker slaat daarmee het begin van de flow over. Een onbekend of inmiddels verwijderd stap-ID is geen fout: de widget gaat dan gewoon open bij de eerste stap.
• message — string — Het bericht dat namens de bezoeker wordt verstuurd zodra die stap open is. Alleen een chatbot-stap doet hier iets mee; bij andere staptypen wordt het genegeerd.

Wat elke combinatie doet

Vier mogelijkheden, van 'gewoon openen' tot 'meteen midden in een gesprek'.

Je mag de functie ook aanroepen terwijl de widget al open is: het gesprek navigeert dan naar de opgegeven stap en verstuurt het bericht daar. Is die stap eerder in het gesprek al langsgekomen en niet meer de huidige stap, dan blijft de widget gewoon open staan zonder het bericht te versturen.

Een aanroep vanuit je code verplaatst de focus niet naar de widget, zodat je pagina niet onder de bezoeker vandaan springt. De enige uitzondering is een chatstap zonder bericht: dan gaat de cursor bewust in het chatveld staan, want dat is precies waar die aanroep voor bedoeld is.

• openWidget() — Opent de widget alsof de bezoeker op het starticoon klikt. De flow begint bij de eerste stap.
• openWidget({ stepUuid }) — Opent de widget bij die stap. Bij een chatstap staat de cursor meteen in het invoerveld, zodat de bezoeker alleen nog hoeft te typen.
• openWidget({ stepUuid, message }) — Opent de widget bij die stap en stuurt het bericht als eerste beurt van de bezoeker. Bij een chatstap begint je AI-agent dus meteen met antwoorden.
• openWidget({ message }) — Zonder stepUuid is dit een gewone open-actie en wordt het bericht genegeerd. Een bericht heeft alleen betekenis samen met de stap waar het naartoe moet.

Het stap-ID van je chatstap vinden

stepUuid is de UUID van de gepubliceerde stap in je gewone LeadBot. Je vindt hem in de configuratie die de widget zelf ophaalt.

Dat ID blijft hetzelfde als je later opnieuw publiceert; het verandert alleen als je de stap verwijdert en opnieuw aanmaakt. Zet het één keer als constante bovenaan je code, dan hoef je het maar op één plek bij te werken.

Liever helemaal zonder code? Met het knopcomponent kies je de LeadBot, de stap en de gespreksstarter uit keuzelijsten in het dashboard. Zie Alle componenten en hun instellingen .

1. 1 Open een pagina waarop je gewone LeadBot staat.
2. 2 Open de ontwikkelaarstools van je browser en ga naar het tabblad Netwerk.
3. 3 Ververs de pagina en zoek het verzoek retrieve-flow.
4. 4 In het antwoord staat een lijst steps. Zoek de stap met step_type "chatbot" en kopieer de waarde van uuid.

Gespreksstarters buiten de widget

Gespreksstarters zijn de voorbeeldvragen die je bij je chatstap instelt. In de widget verschijnen ze als aanklikbare suggesties onder het gesprek; met openWidget() zet je diezelfde vragen overal op je site, in je eigen vormgeving.

Geef je een message mee die precies overeenkomt met een van je ingestelde gespreksstarters, dan volgt de chat dezelfde weg als een klik op die starter in de widget. Hoofdletters en spaties aan het begin of eind maken daarbij niet uit. Heeft die starter een vast antwoord, dan krijgt de bezoeker dat antwoord meteen te zien, zonder AI-aanroep. Elk ander bericht gaat als gewone vraag naar je agent.

Houd de tekst van je externe knoppen dus gelijk aan je gespreksstarters in het dashboard, dan blijven vaste antwoorden werken. Wijkt de tekst af, dan werkt het nog steeds — de agent beantwoordt de vraag dan zelf.

Voorbeeld: je eigen knoppen als gespreksstarters

Drie knoppen onder je prijstabel, in je eigen huisstijl, op de plek die jij kiest. Elke knop opent de widget bij de chatstap met de bijbehorende vraag er al in — één klik en de bezoeker zit midden in een gesprek.

De knoptekst en het bericht zijn hier bewust dezelfde tekst: zo herkent de chat de gespreksstarter en klopt ook wat de bezoeker in het gesprek terugziet.

import { openWidget } from "@leadbot/components";

const CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";
const starters = [
  "Wat kost LeadBot per maand?",
  "Kan ik LeadBot eerst gratis proberen?",
  "Welke integraties zijn er?",
];

const container = document.querySelector("#leadbot-starters");

for (const question of starters) {
  const button = document.createElement("button");
  button.type = "button";
  button.textContent = question;
  button.addEventListener("click", () => {
    openWidget({ stepUuid: CHAT_STEP, message: question });
  });
  container.append(button);
}

import { openWidget } from "@leadbot/react";

const CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";
const STARTERS = [
  "Wat kost LeadBot per maand?",
  "Kan ik LeadBot eerst gratis proberen?",
  "Welke integraties zijn er?",
];

export function ChatStarters() {
  return (
    <div className="chat-starters">
      {STARTERS.map((question) => (
        <button
          key={question}
          type="button"
          onClick={() => openWidget({ stepUuid: CHAT_STEP, message: question })}
        >
          {question}
        </button>
      ))}
    </div>
  );
}

<script setup>
import { openWidget } from "@leadbot/vue";

const CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";
const starters = [
  "Wat kost LeadBot per maand?",
  "Kan ik LeadBot eerst gratis proberen?",
  "Welke integraties zijn er?",
];
</script>

<template>
  <div class="chat-starters">
    <button
      v-for="question in starters"
      :key="question"
      type="button"
      @click="openWidget({ stepUuid: CHAT_STEP, message: question })"
    >
      {{ question }}
    </button>
  </div>
</template>

Voorbeeld: een eigen invoerveld

Een vraagveld midden in je pagina dat bij verzenden de widget opent met precies wat de bezoeker typte. Ideaal als vervanging van een zoekbalk in je helpcentrum: de bezoeker typt zijn vraag waar hij hem verwacht, en het antwoord komt van je AI-agent.

Gebruik een echt formulier met een submit-afhandelaar, dan werkt Enter vanzelf en blijft het veld toegankelijk voor toetsenbord en schermlezer. Verstuur alleen als er echt iets is ingevuld, en maak het veld daarna leeg: het gesprek gaat verder in de widget.

// <form id="leadbot-ask"><input name="q" placeholder="Stel je vraag" /><button>Vraag het</button></form>
import { openWidget } from "@leadbot/components";

const CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";
const form = document.querySelector("#leadbot-ask");
const input = form.querySelector("input");

form.addEventListener("submit", (event) => {
  event.preventDefault();
  const question = input.value.trim();
  if (!question) return;

  openWidget({ stepUuid: CHAT_STEP, message: question });
  input.value = "";
});

import { useState } from "react";
import { openWidget } from "@leadbot/react";

const CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";

export function AskLeadBot() {
  const [value, setValue] = useState("");

  function handleSubmit(event) {
    event.preventDefault();
    const question = value.trim();
    if (!question) return;

    openWidget({ stepUuid: CHAT_STEP, message: question });
    setValue("");
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="leadbot-ask">Stel je vraag</label>
      <input
        id="leadbot-ask"
        value={value}
        onChange={(event) => setValue(event.target.value)}
      />
      <button type="submit">Vraag het de assistent</button>
    </form>
  );
}

<script setup>
import { ref } from "vue";
import { openWidget } from "@leadbot/vue";

const CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";
const value = ref("");

function handleSubmit() {
  const question = value.value.trim();
  if (!question) return;

  openWidget({ stepUuid: CHAT_STEP, message: question });
  value.value = "";
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <label for="leadbot-ask">Stel je vraag</label>
    <input id="leadbot-ask" v-model="value" />
    <button type="submit">Vraag het de assistent</button>
  </form>
</template>

Zonder de SDK: alleen de scripttag

Gebruik je de SDK niet, maar staat de gewone scripttag wel op je site? Dan bereik je hetzelfde zonder iets te installeren. Zolang de widget op de pagina staat, registreert hij zichzelf als window.LeadBot met open, close, toggle en de eigenschap isOpen. Daarnaast luistert hij op het document naar de gebeurtenissen leadbot:open, leadbot:close en leadbot:toggle, met dezelfde parameters in detail.

Beide routes komen tegelijk beschikbaar en doen precies hetzelfde; de SDK probeert eerst window.LeadBot en valt daarna terug op de gebeurtenis. Staat de widget nog niet op de pagina, dan gebeurt er in beide gevallen niets.

<button type="button" data-leadbot-question="Wat kost LeadBot per maand?">
  Wat kost LeadBot per maand?
</button>

<script>
  var CHAT_STEP = "0d4f1c9e-je-chatstap-uuid";

  document.addEventListener("click", function (event) {
    var button = event.target.closest("[data-leadbot-question]");
    if (!button) return;

    var detail = {
      stepUuid: CHAT_STEP,
      message: button.dataset.leadbotQuestion,
    };

    if (window.LeadBot && window.LeadBot.open) {
      window.LeadBot.open(detail);
    } else {
      document.dispatchEvent(new CustomEvent("leadbot:open", { detail: detail }));
    }
  });
</script>

Waar je op moet letten

Een paar dingen die je een zoektocht besparen.

• De widget moet op die pagina staan — De zichtbaarheidsregels van je LeadBot gelden gewoon. Verschijnt de widget op deze pagina niet, dan valt er ook niets te openen en doet de aanroep niets.
• Het stap-ID hoort bij de bot op de pagina — Een stap uit een andere LeadBot is voor deze widget onbekend. De widget gaat dan open bij de eerste stap in plaats van bij jouw stap.
• Alleen chatstappen doen iets met message — Wijst stepUuid naar een formulier, een knoppenstap of een ander staptype, dan navigeert de widget er wel naartoe, maar wordt het bericht genegeerd.
• Alles wordt gewoon gemeten — Een open-actie vanuit je code telt als een gewone widget-open in Google Analytics, en het gesprek verschijnt inclusief het verstuurde bericht in je Inbox.