SDK osadzonego widżetu

SDK pozwala stronie otwierać, zamykać, resetować, konfigurować i obserwować dymek czatu Agentkit. Jest dostępne tylko dla osadzenia przez skrypt. Osadzenie iframe nie definiuje window.agentkit.

Instalacja kolejki

Użyj fragmentu ze strony Kanały swojego agenta. Kolejka sprawia, że wywołania sprzed i po załadowaniu skryptu asynchronicznego działają tak samo.

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

Dotychczasowe osadzenie z jednym tagiem nadal działa. Dodaj kolejkę, jeśli wywołujesz SDK przed załadowaniem pakietu.

Sterowanie widżetem i wysyłanie wiadomości

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

Opcja hideMessage ukrywa proaktywną wiadomość w rozmowie. Widżet otworzy się dopiero, gdy asystent zacznie odpowiadać.

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

SDK odrzuca puste, równoczesne i ograniczone wiadomości oraz wysyłanie przy ukrytym lub wyłączonym polu albo podczas czatu na żywo. close nie kończy aktywnego czatu Salesforce.

Wysyłanie przy zamkniętym widżecie

Użyj send, gdy strona ma własne małe pole pytania i pokazuje odpowiedź poza widżetem. Wiadomość trafia do zwykłej rozmowy bez otwierania prezentacji. Nasłuchuj zdarzenia asystenta, a później wywołaj open, aby kontynuować tę samą rozmowę.

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 stosuje te same kontrole, limity, zapisywanie i zdarzenia co open({ message }). Zmienia tylko to, czy prezentacja się otwiera.

Center Stage

Center Stage otwiera tego samego agenta jako wyśrodkowane okno dialogowe na pełnym ekranie nad Twoją stroną zamiast dymka w rogu. To osobny kanał na stronie Kanały, z własnym wyglądem, głosem, instrukcjami i akcjami, wyłączony do czasu, aż go tam włączysz.

Zainstaluj go z tym samym bootstrapem i dodaj data-display="center-stage" do tagu script. Atrybut stoi obok data-chatbot i data-locale:

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

Launcher pozostaje domyślnym sposobem otwierania, a każde wywołanie SDK działa tak samo: open pokazuje okno, close je zamyka, a resetChat, setOptions, identify, zdarzenia i narzędzia przeglądarki zachowują się dokładnie jak w dymku. Okno zatrzymuje fokus, zamyka się klawiszem Escape lub przyciskiem zamknięcia, oddaje fokus elementowi, który je otworzył, i na telefonach wypełnia cały ekran.

Na stronie może działać tylko jedna prezentacja Agentkit. Jeśli załadują się dwa skrypty osadzania, wygrywa data-display pierwszego, a niezgodny duplikat zapisuje ostrzeżenie w konsoli zamiast montować drugi widżet. Ustawienia i czat Center Stage ładują się z własnych endpointów, więc wyłączenie kanału na stronie Kanały zatrzymuje go na każdej witrynie, nawet gdy dymek pozostaje włączony.

Resetowanie czatu i opcji

window.agentkit('resetChat');

Polecenie usuwa zapisaną rozmowę i tworzy nowy identyfikator. Zachowuje tożsamość i tymczasowe opcje strony.

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

Obsługiwane klucze to title, conversation.messagePlaceholder, conversation.initialMessages i conversation.defaultPrompts.prompts. Każdy klucz jest sprawdzany osobno. Wartości działają tylko na bieżącej stronie i nie zmieniają zapisanych ustawień ani pamięci lokalnej.

Zdarzenia

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

Do usunięcia listenera użyj tej samej referencji funkcji. Zdarzenia to user-message, assistant-message, tool-call i tool-result. Zdarzenia wiadomości zawierają { conversationId, content }. Zdarzenia narzędzi są emitowane przed uruchomieniem zarejestrowanego narzędzia przeglądarkowego i po jego zakończeniu. Błąd listenera nie przerywa działania widżetu.

Rejestrowanie narzędzi przeglądarkowych

Utwórz akcję po stronie klienta w panelu, a następnie zarejestruj handler o dokładnie tej samej nazwie akcji na każdej stronie, na której może pojawić się widżet. Ponowna rejestracja zastępuje cały rejestr, dzięki czemu sprzątanie per trasa w aplikacjach single-page jest przewidywalne.

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

Handlery otrzymują { args, toolCallId, signal }. Zwracaj { status: 'success', data } lub { status: 'error', error }; zwykła wartość zgodna z JSON jest traktowana jako sukces. Widżet przerywa pracę po 60 sekundach i zamienia brakujące handlery, rzucone wyjątki, przekroczenia czasu i nieprawidłowe wyniki w ograniczone wyniki błędów, aby asystent mógł kontynuować rozmowę.

Traktuj argumenty narzędzi jako niezaufane dane wejściowe. Trzymaj uprzywilejowane dane uwierzytelniające na własnym serwerze, przekazuj dostarczony signal anulowania do żądań sieciowych i nigdy nie zwracaj sekretów ani zbędnych danych osobowych. Narzędzia klienckie wymagają osadzenia przez skrypt; osadzenie przez iframe nie ma dostępu do funkcji strony nadrzędnej.

Dotychczasowe polecenia tożsamości pozostają zgodne:

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

Zobacz Weryfikacja tożsamości.

W TypeScript zaimportuj kontrakt Agentkit z @kit/chatbot-widget/sdk; w przeglądarce znajduje się pod window.agentkit. Zdarzenia wiadomości zawierają conversationId i content, a zdarzenia narzędzi także toolCallId, toolName, input i output. Polecenia setOptions, resetOptions, resetChat, identify i resetUser są typowane.