SDK d'intégration du widget

Le SDK permet à votre page d'ouvrir, fermer, réinitialiser, configurer et observer la bulle de chat Agentkit. Il est disponible uniquement avec l'intégration par script. L'intégration iframe ne définit pas window.agentkit.

Installer la file d'attente

Utilisez l'extrait de la page Canaux de votre agent. La file garantit le même comportement avant et après le chargement du script asynchrone.

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

L'ancienne intégration à une seule balise fonctionne toujours. Ajoutez la file si vous appelez le SDK avant la fin du chargement du bundle.

Contrôler le widget et envoyer un message

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

Avec hideMessage, le message proactif reste masqué dans la conversation et le widget ne s'ouvre que lorsque l'assistant commence à répondre.

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

Le SDK refuse les messages vides, simultanés ou limités par quota, ainsi que les envois lorsque la saisie est masquée ou désactivée ou qu'un chat en direct est actif. close ne termine pas un chat Salesforce actif.

Envoyer tout en gardant le widget fermé

Utilisez send pour proposer une interface de question compacte et afficher la réponse hors du widget. Le message rejoint la conversation normale sans ouvrir la présentation. Écoutez l’événement de l’assistant, puis appelez open pour poursuivre la même conversation.

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 applique les mêmes contrôles, limites, règles de persistance et événements que open({ message }). Seule l’ouverture de la présentation change.

Center Stage

Center Stage ouvre le même agent dans une boîte de dialogue centrée en plein écran par-dessus votre page, au lieu de la bulle dans le coin. C'est un canal à part entière sur la page Canaux, avec son propre affichage, sa voix, ses instructions et ses actions, et il reste désactivé tant que vous ne l'activez pas là.

Installez-le avec le même bootstrap et ajoutez data-display="center-stage" à la balise script. L'attribut se place à côté de data-chatbot et data-locale :

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

Le lanceur reste le moyen par défaut de l'ouvrir, et chaque appel du SDK fonctionne de la même façon : open affiche la boîte de dialogue, close la ferme, et resetChat, setOptions, identify, les événements et les outils du navigateur se comportent exactement comme pour la bulle. La boîte de dialogue conserve le focus, se ferme avec Échap ou son bouton de fermeture, rend le focus à l'élément qui l'a ouverte et occupe tout l'écran sur téléphone.

Une seule présentation Agentkit peut s'exécuter par page. Si deux scripts d'intégration se chargent, le data-display du premier l'emporte et un doublon différent écrit un avertissement dans la console au lieu de monter un second widget. Les réglages et le chat de Center Stage se chargent depuis leurs propres points de terminaison ; désactiver le canal sur la page Canaux l'arrête donc sur tous les sites même si la bulle reste active.

Réinitialiser le chat et les options

window.agentkit('resetChat');

Cette commande efface la conversation en cache et crée un nouvel identifiant. Elle conserve l'identité et les options temporaires de la page.

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

Les clés prises en charge sont title, conversation.messagePlaceholder, conversation.initialMessages et conversation.defaultPrompts.prompts. Chaque clé est validée séparément. Les valeurs restent dans la page courante et ne modifient ni les réglages enregistrés ni le stockage local.

Événements

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

Utilisez la même référence de fonction pour retirer l'écouteur. Les événements sont user-message, assistant-message, tool-call et tool-result. Les événements de message contiennent { conversationId, content }. Les événements d'outil sont émis avant et après l'exécution des outils du navigateur enregistrés. Une erreur dans un écouteur n'interrompt pas le widget.

Enregistrer des outils du navigateur

Créez une action côté client dans le tableau de bord, puis enregistrez un handler portant exactement le même nom d'action sur chaque page où le widget peut apparaître. Un nouvel enregistrement remplace le registre complet, ce qui rend le nettoyage par route prévisible dans les applications monopages.

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

Les handlers reçoivent { args, toolCallId, signal }. Renvoyez { status: 'success', data } ou { status: 'error', error } ; une valeur de retour compatible JSON est traitée comme un succès. Le widget annule le travail après 60 secondes et transforme les handlers manquants, les exceptions levées, les délais dépassés et les résultats invalides en résultats d'erreur bornés afin que l'assistant puisse poursuivre la conversation.

Traitez les arguments des outils comme des entrées non fiables. Conservez les identifiants privilégiés sur votre propre serveur, transmettez le signal d'annulation fourni aux requêtes réseau et ne renvoyez jamais de secrets ni de données personnelles superflues. Les outils client nécessitent l'embed par script ; l'embed par iframe ne peut pas accéder aux fonctions de la page parente.

Les commandes d'identité existantes restent compatibles :

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

Consultez Vérification d'identité.

En TypeScript, importez le contrat Agentkit depuis @kit/chatbot-widget/sdk; il se trouve sous window.agentkit dans le navigateur. Les événements de message fournissent conversationId et content, et les événements d'outil ajoutent toolCallId, toolName, input et output. Les commandes setOptions, resetOptions, resetChat, identify et resetUser sont typées.