Documentatie

Widget Embed SDK

Bestuur de Agentkit-widget vanuit de browser, stuur proactieve berichten, stel paginaopties in en luister naar gebeurtenissen.

Met de embed-SDK kan je pagina de Agentkit-chatballon openen, sluiten, resetten, configureren en volgen. De SDK is alleen beschikbaar voor de script-embed. De iframe-embed definieert window.agentkit niet.

De wachtrij installeren

Gebruik het fragment op de pagina Kanalen van je agent. De wachtrij zorgt dat aanroepen vóór en na het laden van het asynchrone script hetzelfde werken.

<script>
  (function (w) {
    if (w.agentkit) return;
    var q = [];
    var agentkit = function () { q.push(arguments); };
    agentkit.q = q;
    w.agentkit = agentkit;
  })(window);
</script>
<script async data-chatbot="YOUR_CHATBOT_ID" src="https://YOUR_WIDGET_HOST/agentkit-chatbot.js"></script>

De oude embed met één scripttag blijft werken. Voeg de wachtrij toe wanneer je de SDK aanroept voordat de bundle geladen is.

De widget besturen en berichten sturen

window.agentkit('open');
window.agentkit('close');
window.agentkit('open', { message: 'Can you help me choose a plan?' });

Met hideMessage blijft een proactief bericht uit het gesprek en opent de widget pas wanneer de assistent begint te antwoorden.

window.agentkit('open', {
  message: 'Explain the current page in one sentence.',
  hideMessage: true,
});

De SDK weigert lege, gelijktijdige of door de limiet geblokkeerde berichten. Dit geldt ook wanneer het invoerveld verborgen of uitgeschakeld is of een livechat loopt. close beëindigt geen actieve Salesforce-livechat.

Verzenden terwijl de widget gesloten blijft

Gebruik send wanneer je pagina een compact vraagveld toont en het antwoord buiten de widget weergeeft. Het bericht komt in het normale widgetgesprek zonder de presentatie te openen. Luister naar het assistentgebeurtenis en roep later open aan om hetzelfde gesprek voort te zetten.

let pendingQuestion = null;
let questionAccepted = false;

function onUserMessage(event) {
  if (event.detail.content === pendingQuestion) questionAccepted = true;
}

function showAnswer(event) {
  if (!questionAccepted) return;
  document.querySelector('#answer').textContent = event.detail.content;
  pendingQuestion = null;
  questionAccepted = false;
}

window.agentkit('addEventListener', 'user-message', onUserMessage);
window.agentkit('addEventListener', 'assistant-message', showAnswer);

pendingQuestion = 'Do you offer a free plan?';
window.agentkit('send', { message: pendingQuestion });

// Later, from a “Continue in chat” control:
window.agentkit('open');

send gebruikt dezelfde controles, limieten, opslag en gebeurtenissen als open({ message }). Alleen het openen van de presentatie verandert.

Center Stage

Center Stage opent dezelfde agent als een gecentreerde dialoog in focusmodus over je pagina in plaats van de bubbel in de hoek. Het is een eigen kanaal op de pagina Kanalen, met eigen weergave, stem, instructies en acties, en staat uit tot je het daar inschakelt.

Installeer het met dezelfde bootstrap en voeg data-display="center-stage" toe aan de scripttag. Dat attribuut staat naast data-chatbot en data-locale:

<script async data-chatbot="YOUR_CHATBOT_ID" data-display="center-stage" src="https://YOUR_WIDGET_HOST/agentkit-chatbot.js"></script>

De launcher blijft de standaardmanier om het te openen, en elke SDK-aanroep werkt hetzelfde: open toont de dialoog, close sluit hem, en resetChat, setOptions, identify, events en browsertools gedragen zich precies zoals bij de bubbel. De dialoog houdt de focus vast, sluit met Escape of de sluitknop, geeft de focus terug aan wat hem opende en vult op telefoons het hele scherm.

Er kan maar één Agentkit-presentatie per pagina draaien. Laden er twee embed-scripts, dan wint de data-display van het eerste script en logt een afwijkend duplicaat een consolewaarschuwing in plaats van een tweede widget te mounten. Instellingen en chat van Center Stage laden via eigen endpoints, dus het kanaal uitschakelen op de pagina Kanalen stopt het op elke site, ook als de bubbel aan blijft.

Chat en opties resetten

window.agentkit('resetChat');

Deze opdracht verwijdert het opgeslagen gesprek en maakt een nieuw gespreks-id. De identiteit en tijdelijke paginaopties blijven behouden.

window.agentkit('setOptions', {
  title: 'Checkout assistant',
  conversation: {
    messagePlaceholder: 'Ask about checkout',
    initialMessages: ['Need help finishing your order?'],
    defaultPrompts: {
      prompts: ['Delivery times', 'Returns', 'Payment methods'],
    },
  },
});
window.agentkit('resetOptions');
window.agentkit('resetOptions', [
  'title',
  'conversation.initialMessages',
]);

Ondersteunde sleutels zijn title, conversation.messagePlaceholder, conversation.initialMessages en conversation.defaultPrompts.prompts. Elke sleutel wordt apart gecontroleerd. De waarden gelden alleen op de huidige pagina en wijzigen geen opgeslagen instellingen of lokale opslag.

Gebeurtenissen

function onAssistantMessage(event) {
  console.log(event.detail.conversationId);
  console.log(event.detail.content);
}

window.agentkit(
  'addEventListener',
  'assistant-message',
  onAssistantMessage,
);

// Clean up when this page or route no longer needs the listener.
window.agentkit(
  'removeEventListener',
  'assistant-message',
  onAssistantMessage,
);

Gebruik dezelfde functiereferentie om de listener te verwijderen. De gebeurtenissen zijn user-message, assistant-message, tool-call en tool-result. Berichtgebeurtenissen bevatten { conversationId, content }. Toolgebeurtenissen worden vóór en na het uitvoeren van geregistreerde browsertools verzonden. Een fout in een listener onderbreekt de widget niet.

Browsertools registreren

Maak een client-side actie aan in het dashboard en registreer vervolgens op elke pagina waar de widget kan verschijnen een handler met exact dezelfde actienaam. Opnieuw registreren vervangt het volledige register, wat opruimen per route voorspelbaar maakt in single-page-applicaties.

window.agentkit('registerTools', {
  checkInventory: async ({ args, signal }) => {
    const response = await fetch(`/api/inventory?sku=${args.sku}`, { signal });

    if (!response.ok) {
      return { status: 'error', error: 'Inventory is unavailable.' };
    }

    return { status: 'success', data: await response.json() };
  },
});

Handlers ontvangen { args, toolCallId, signal }. Geef { status: 'success', data } of { status: 'error', error } terug; een gewone JSON-compatibele returnwaarde geldt als succes. De widget annuleert het werk na 60 seconden en zet ontbrekende handlers, gegooide excepties, time-outs en ongeldige resultaten om in begrensde foutresultaten, zodat de assistent het gesprek kan voortzetten.

Behandel toolargumenten als niet-vertrouwde invoer. Houd bevoorrechte inloggegevens op je eigen server, geef het meegeleverde abort-signal door aan netwerkverzoeken en geef nooit geheimen of onnodige persoonsgegevens terug. Clienttools vereisen de script-embed; de iframe-embed heeft geen toegang tot functies op de bovenliggende pagina.

De bestaande identiteitsopdrachten blijven werken:

window.agentkit('identify', { token: newToken });
window.agentkit('resetUser');

Lees Identiteitsverificatie.

Importeer voor TypeScript het contract Agentkit uit @kit/chatbot-widget/sdk; in de browser staat het op window.agentkit. Berichtgebeurtenissen bevatten conversationId en content, en toolgebeurtenissen voegen toolCallId, toolName, input en output toe. De opdrachten setOptions, resetOptions, resetChat, identify en resetUser zijn getypeerd.