Dokumentation

Widget Embed SDK

Steuere das Agentkit-Chat-Widget im Browser, sende proaktive Nachrichten, setze seitenbezogene Optionen und empfange Chat-Ereignisse.

Mit dem Embed SDK kann deine Seite die Agentkit-Chatblase öffnen, schließen, zurücksetzen, konfigurieren und beobachten. Das SDK ist nur beim Script-Embed verfügbar. Das Iframe-Embed definiert window.agentkit nicht.

Warteschlange installieren

Verwende das Snippet von der Kanäle-Seite deines Agenten. Die Warteschlange sorgt dafür, dass Aufrufe vor und nach dem Laden des asynchronen Scripts gleich funktionieren.

<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>

Der bisherige Embed mit nur einem Script-Tag funktioniert weiterhin. Füge die Warteschlange hinzu, wenn du das SDK vor dem Laden des Bundles aufrufst.

Widget steuern und Nachrichten senden

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

Eine proaktive Nachricht bleibt mit hideMessage im Transkript verborgen. Das Widget öffnet sich erst, wenn die Antwort des Assistenten beginnt.

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

Leere, gleichzeitige oder ratenbegrenzte Sendungen werden abgelehnt. Das gilt auch, wenn die Eingabe verborgen oder deaktiviert ist oder ein Live-Chat läuft. close beendet keinen aktiven Salesforce-Live-Chat.

Senden, während das Widget geschlossen bleibt

Mit send kann Ihre Seite eine kompakte Frageoberfläche anbieten und die Antwort außerhalb des Widgets anzeigen. Die Nachricht wird dem normalen Widget-Gespräch hinzugefügt, ohne die Darstellung zu öffnen. Lauschen Sie auf das Assistenten-Ereignis und rufen Sie später open auf, um dasselbe Gespräch fortzusetzen.

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 verwendet dieselben Prüfungen, Ratenbegrenzungen, Speicherung und Nachrichtenereignisse wie open({ message }). Nur die Darstellung bleibt geschlossen.

Center Stage

Center Stage öffnet denselben Agenten als zentrierten Dialog im Fokusmodus über Ihrer Seite statt als Blase in der Ecke. Es ist ein eigener Kanal auf der Seite Kanäle mit eigener Darstellung, Stimme, Anweisungen und Aktionen und bleibt aus, bis Sie ihn dort aktivieren.

Installieren Sie es mit demselben Bootstrap und ergänzen Sie das Script-Tag um data-display="center-stage". Das Attribut steht neben data-chatbot und data-locale:

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

Der Launcher bleibt der Standardweg zum Öffnen, und jeder SDK-Aufruf funktioniert gleich: open zeigt den Dialog, close schließt ihn, und resetChat, setOptions, identify, Ereignisse und Browser-Tools verhalten sich genau wie bei der Blase. Der Dialog hält den Fokus, schließt mit Escape oder seinem Schließen-Button, gibt den Fokus an das öffnende Element zurück und füllt auf Smartphones den ganzen Bildschirm.

Pro Seite kann nur eine Agentkit-Darstellung laufen. Laden zwei Embed-Scripts, gewinnt das data-display des ersten Scripts, und ein abweichendes Duplikat schreibt eine Konsolenwarnung statt ein zweites Widget zu mounten. Center-Stage-Einstellungen und -Chat laden über eigene Endpunkte, daher stoppt das Deaktivieren des Kanals auf der Kanäle-Seite ihn auf jeder Website, auch wenn die Blase aktiv bleibt.

Chat und Optionen zurücksetzen

window.agentkit('resetChat');

Der Befehl löscht das zwischengespeicherte Transkript und erstellt eine neue Konversations-ID. Identität und temporäre Seitenoptionen bleiben erhalten.

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',
]);

Unterstützt werden title, conversation.messagePlaceholder, conversation.initialMessages und conversation.defaultPrompts.prompts. Jede Option wird einzeln geprüft. Die Werte gelten nur für die aktuelle Seite und ändern weder gespeicherte Agenteneinstellungen noch Local Storage.

Ereignisse

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,
);

Verwende beim Entfernen dieselbe Funktionsreferenz. Unterstützte Ereignisse sind user-message, assistant-message, tool-call und tool-result. Nachrichtenereignisse enthalten { conversationId, content }. Tool-Ereignisse werden vor und nach der Ausführung registrierter Browser-Tools ausgelöst. Fehler in einem Handler unterbrechen das Widget nicht.

Browser-Tools registrieren

Lege im Dashboard eine clientseitige Aktion an und registriere dann auf jeder Seite, auf der das Widget erscheinen kann, einen Handler mit exakt demselben Aktionsnamen. Eine erneute Registrierung ersetzt die gesamte Registry, was das Aufräumen pro Route in Single-Page-Anwendungen vorhersehbar macht.

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() };
  },
});

Handler erhalten { args, toolCallId, signal }. Gib { status: 'success', data } oder { status: 'error', error } zurück; ein einfacher JSON-kompatibler Rückgabewert gilt als Erfolg. Das Widget bricht die Ausführung nach 60 Sekunden ab und wandelt fehlende Handler, geworfene Ausnahmen, Timeouts und ungültige Ergebnisse in begrenzte Fehlerergebnisse um, damit der Assistent das Gespräch fortsetzen kann.

Behandle Tool-Argumente als nicht vertrauenswürdige Eingaben. Bewahre privilegierte Zugangsdaten auf deinem eigenen Server auf, reiche das übergebene Abbruch-signal an Netzwerkanfragen weiter und gib niemals Geheimnisse oder unnötige personenbezogene Daten zurück. Client-Tools erfordern das Script-Embed; das Iframe-Embed hat keinen Zugriff auf Funktionen der übergeordneten Seite.

Die bestehenden Identitätsbefehle bleiben kompatibel:

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

Weitere Informationen findest du unter Identitätsprüfung.

Für TypeScript importierst du den Vertrag Agentkit aus @kit/chatbot-widget/sdk; im Browser liegt er unter window.agentkit. Nachrichtenereignisse liefern conversationId und content, Tool-Ereignisse zusätzlich toolCallId, toolName, input und output. Die Befehle setOptions, resetOptions, resetChat, identify und resetUser sind vollständig typisiert.