API JS de l’assistant
Contrôlez l’assistant Olotalk de manière programmatique depuis votre propre JavaScript.
La fonction globale Olotalk() est disponible sur toute page où le snippet du loader est intégré. Une fois le script du loader exécuté, les appels émis avant la fin du boot du bundle assistant sont mis en file puis rejoués automatiquement.
API de commandes
Olotalk(command: string, payload?: any): void | Promise<void>
Olotalk('open')
Ouvre la boîte de dialogue de l’assistant.
Olotalk('open')
Si l’assistant est déjà ouvert, l’appel ne fait rien.
Olotalk('close')
Ferme la boîte de dialogue de l’assistant. L’instance reste montée ; le prochain appel à open() la rouvre dans l’état attendu.
Olotalk('close')
Olotalk('destroy')
Démonte complètement l’assistant et supprime tous les nœuds DOM qu’il a créés. Utilisez-le pour retirer l’assistant d’une page précise sans navigation complète.
await Olotalk('destroy')
Retourne une Promise qui se résout quand le démontage est terminé. Après destroy(), vous pouvez réinitialiser via Olotalk('init').
Olotalk('init', config?)
Déclenche manuellement l’initialisation de l’assistant. Vous pouvez passer une config partielle pour écraser les valeurs définies dans le snippet d’intégration.
// Initialise avec la config du snippet
Olotalk('init')
// Initialise avec un override de locale
Olotalk('init', { locale: 'fr' })
init est appelé automatiquement par le loader sur DOMContentLoaded. Vous n’avez besoin de l’appeler manuellement que si :
- vous définissez
window.OlotalkConfig = { ... }après le boot du loader, ou - vous voulez réinitialiser après un
destroy().
API bas niveau de l’instance assistant
Si vous importez @olotalk/assistant directement au lieu d’utiliser le loader, createAssistant() retourne une instance d’assistant avec méthodes et événements.
import { createAssistant } from '@olotalk/assistant'
const assistant = createAssistant(document.body, {
assistantId: 'ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy',
origin: 'https://api.olotalk.com',
config: assistantConfig,
cssUrl: 'https://cdn.jsdelivr.net/npm/@olotalk/assistant@0/dist/olotalk-assistant.css',
})
Méthodes d’instance
assistant.open()
assistant.open({ prefill: 'Gérez-vous le SSO ?' }) // pose la question
assistant.open({ prefill: passage, send: false }) // la garde pour édition
assistant.close()
assistant.isOpen() // vrai tant que le panneau est visible
assistant.setTheme('dark')
await assistant.setLocale('fr') // conserve la conversation
assistant.destroy({ outro: true })
setLocale retourne une promesse résolue selon que la langue a changé ou non.
Utilisez-la dès que votre propre sélecteur ne recharge pas la page, voir
Piloter la langue depuis votre interface.
Un seul assistant par page
createAssistant() renvoie l’assistant déjà monté pour cet assistantId
quand il existe, plutôt que d’en monter un second. Ainsi plusieurs affordances,
un corner bubble et votre propre bouton « Ask AI », par exemple, partagent
un seul panneau et une seule conversation au lieu d’en ouvrir deux.
Utilisez getAssistant() pour piloter celui qui existe :
import { getAssistant } from '@olotalk/assistant'
document.querySelector('#ask-about-pricing').addEventListener('click', () => {
getAssistant('ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy')
?.open({ prefill: 'What is included in the Growth plan?' })
})
Il renvoie undefined quand rien n’est monté pour cet ID, il n’en monte
jamais un par effet de bord.
Événements d’instance
const unsubscribe = assistant.on('open', () => {
console.log('Assistant ouvert')
})
assistant.on('ready', ({ assistantId }) => {
console.log('Prêt', assistantId)
})
assistant.on('send', ({ text }) => {
console.log('Envoyé', text)
})
unsubscribe()
| Événement | Payload | Quand il se déclenche |
|---|---|---|
ready | { assistantId: string } | L’assistant est monté et pleinement interactif |
open | undefined | La boîte de dialogue s’ouvre |
close | undefined | La boîte de dialogue se ferme |
send | { text: string } | L’utilisateur envoie un message |
cta_click | { id: string; action: ActionType; intent: string } | Le visiteur clique un CTA proposé par l’assistant |
lead_submit | { leadId: string; status: string; score: number } | Le visiteur soumet un formulaire de capture de lead |
ActionType vaut "lead_form" | "link" | "escalate_to_human" | "trigger_webhook" | "book_meeting" | "hubspot_create_contact_deal".
L’intégration basée sur le loader n’expose pas l’instance interne comme API globale publique. Pour les intégrations via script tag, utilisez l’interface de commande Olotalk() ci-dessus.
Élément personnalisé (<olotalk-assistant>)
Le build ESM exporte OlotalkAssistantElement, un Custom Element standard que vous pouvez enregistrer puis utiliser de manière déclarative dans n’importe quel template HTML ou framework.
Enregistrer
import { defineOlotalkAssistantElement } from '@olotalk/assistant'
defineOlotalkAssistantElement() // enregistre <olotalk-assistant>
Appelez cette fonction une fois au démarrage de l’application (par ex. dans main.ts). L’appel multiple est sans effet.
Utiliser
<olotalk-assistant
assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
origin="https://api.olotalk.com"
theme="light"
mode="inline"
css-url="https://cdn.jsdelivr.net/npm/@olotalk/assistant@0/dist/olotalk-assistant.css"
></olotalk-assistant>
Attributs
| Attribut | Type | Description |
|---|---|---|
assistant-id | string | Assistant ID (requis) |
site-id | string | Alias legacy de assistant-id |
origin | string | URL de base de l’API Olotalk, optionnelle ; par défaut l’API cloud |
theme | "light" | "dark" | JSON | Thème UI ; un objet JSON pour un override complet des tokens |
mode | Voir Shapes, quatorze valeurs | Quelle forme monter, voir Shapes ci-dessous |
reach | string | Déclencheurs supplémentaires par-dessus la forme montée, séparés par des virgules : "selection,commandk", voir Combiner les formes |
selection-answers | string | Où un surlignage ouvre le panneau : "beside" (défaut) à côté des mots, "in-place" là où l’assistant vit, voir Combiner les formes |
placement | "floating" | "embedded" | Déprécié, utilisez mode. floating équivaut à bubble, embedded à inline |
locale | string | La langue d’affichage. La changer après le montage échange les textes de l’assistant sur place, en conservant la conversation, voir Piloter la langue depuis votre interface |
css-url | string | URL de la feuille de style de l’assistant |
config | Chaîne JSON | Objet AssistantConfig complet sérialisé en JSON |
Shapes
Un seul assistant, monté à différents endroits. Chaque forme fait tourner la même conversation, le même ancrage et les mêmes citations, seul le montage change.
Chaque ligne tranche trois choses à la fois : où se place le panneau, ce qui l’ouvre, et ce qui est sur la page avant toute action. Ce que décide une forme explique la règle derrière le tableau, et notamment quelles formes ne posent aucun bouton sur la page.
mode | Où il se place | Comment il s’ouvre |
|---|---|---|
bubble | Un launcher dans le coin, panneau flottant au-dessus de la page | Le visiteur clique le launcher. La valeur par défaut |
starters | Launcher du coin, avec des questions suggérées au survol | Le visiteur clique le launcher, ou une suggestion |
inline | Remplit l’élément où vous le montez, toujours ouvert | Rien à ouvrir, il fait partie de la page |
drawer | Pleine hauteur, collé au bord, il écarte la page au lieu de la recouvrir | Votre propre bouton, data-olotalk-open ou open() |
commandk | Centré au-dessus d’une page assombrie | ⌘K / CtrlK |
corner | Panneau de coin, rien sur la page au repos | Votre propre contrôle, ou un déclencheur reach |
center | Centré au-dessus d’une page assombrie, rien au repos | Votre propre contrôle, ou un déclencheur reach |
expand | Une ligne dans votre page qui se déplie sur place, en poussant le contenu | Le visiteur presse la ligne |
anchored | À côté d’un élément, un plan tarifaire, une ligne de specs | Votre propre affordance, avec open({ anchor }) |
fullpage | L’assistant est la page | Toujours ouvert ; rien à invoquer |
sidebar | Un rail fixe pleine hauteur au bord | Toujours ouvert ; rien à invoquer |
navfield | Rien de chez nous, le champ de recherche de votre nav | Votre champ soumet, avec open({ prefill }) |
askbar | Rien de chez nous, votre propre barre au pied de la page | Votre barre soumet, avec open({ prefill }) |
selection | Rien au repos, une offre apparaît là où du texte est surligné | Le visiteur sélectionne un passage et prend l’offre |
La plupart des formes ne dessinent aucun launcher : c’est la colonne
Comment il s’ouvre ci-dessus qui indique ce qui ouvre chacune d’elles, et
partout où elle évoque votre propre bouton, votre champ ou votre barre, il
s’agit de votre code appelant open(). Un drawer prend la vôtre :
import { getAssistant } from '@olotalk/assistant'
document.querySelector('#ask-ai').addEventListener('click', () => {
getAssistant('ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy')?.open()
})
Installé avec le snippet à coller ? Pas besoin d’imports ni de build : le
global Olotalk accepte les mêmes appels et les met en file d’attente jusqu’à
ce que l’assistant soit prêt :
<button onclick="Olotalk('open')">Ask AI</button>
Chaque payload open(...) de cette page voyage de la même façon par le global,
Olotalk('open', { anchor, context, prefill, send }), chaque snippet
ci-dessous a donc son jumeau côté loader : remplacez
getAssistant(id)?.open(…) par Olotalk('open', …).
commandk lie lui-même le raccourci, et seulement monté sous cette forme,
aucun autre mode ne touche cette touche. Comme son état de repos est le néant,
il est introuvable si vous ne l’annoncez pas : accompagnez-le d’un indice dans
votre navigation.
drawer et commandk assombrissent la page derrière eux, verrouillent son
défilement tant qu’ils sont ouverts, retiennent le focus dans le panneau, se
ferment sur Esc ou un clic sur le voile, et rendent le focus à ce
qui les a ouverts.
Ancré à un élément
anchored s’ouvre à côté de ce dont il parle et ne le recouvre jamais,
en dessous de préférence, au-dessus quand la place manque, en suivant l’élément
quand la page défile :
document.querySelector('#growth-tier .ask').addEventListener('click', () => {
getAssistant(id)?.open({
anchor: document.querySelector('#growth-tier'),
context: 'Growth plan',
prefill: 'What is included in the Growth plan?',
send: false,
})
})
Sur un téléphone, il n’y a de place à côté de rien : il devient une feuille en
bas d’écran, et comme l’ancre n’est plus visible, la feuille dit de quoi elle
parle. context est cette étiquette ; sans elle, nous retombons sur le
data-olotalk-context de l’élément, son aria-label, ou son propre titre.
Depuis un passage surligné par le visiteur
selection n’a aucun état de repos. Quand un visiteur surligne un passage de
votre page, une petite offre apparaît au-dessus ; la prendre ouvre l’assistant
avec ce passage dans le composer, non envoyé, un passage surligné n’est
pas une question, et le poser tel quel mettrait des mots dans sa bouche.
<olotalk-assistant assistant-id="ast_oltk_…" mode="selection"></olotalk-assistant>
Il n’y a rien d’autre à câbler. Il ignore les sélections dans les inputs, les textareas et les zones contenteditable, qui édite ne demande pas, borne ce qu’il amorcera entre un mot et un paragraphe, et s’efface devant un clic droit.
Sur un appareil tactile, il n’offre volontairement rien. Y sélectionner du texte fait apparaître le menu Copier / Rechercher du système, qu’on ne peut ni styler, ni déplacer, ni supprimer sans désactiver la sélection et emporter Copier avec elle. Rivaliser avec lui serait pire que ne rien offrir : sur un téléphone cette forme reste silencieuse, et tout autre montage que vous avez continue de fonctionner normalement.
Des champs que vous avez déjà
navfield et askbar ne rendent rien d’eux-mêmes. Le champ est le vôtre,
dans votre navigation, ou une barre au pied d’une doc, et sa soumission ouvre
l’assistant avec la question déjà posée :
form.addEventListener('submit', (e) => {
e.preventDefault()
getAssistant(id)?.open({ prefill: input.value })
})
C’est toute l’intégration. Elle fonctionne avec le markup que vous avez déjà, et c’est le but : la forme, c’est votre champ, pas notre rendu d’un champ.
Combiner les formes
Une page monte une forme, c’est là que vit la conversation, mais on peut l’appeler de plusieurs manières :
- Depuis votre propre interface. N’importe quel bouton, champ ou lien peut
appeler
getAssistant(id).open({ prefill }), quelle que soit la forme montée : un champ de nav à côté d’une bulle de coin, c’est deux lignes de votre code. - Depuis les nôtres, avec
reach. Vous nommez des déclencheurs supplémentaires par-dessus la forme montée :
<script
src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
data-olotalk-mode="bubble"
data-olotalk-reach="selection,commandk"
async
></script>
Vous obtenez une bulle de coin qui s’ouvre aussi quand un visiteur surligne un
passage, à côté du surlignage, le passage cité au-dessus d’un composer vide,
et quand il presse ⌘K. reach accepte selection et
commandk, et tout identifiant inconnu est ignoré avec un avertissement en
console. Peu importe le nombre de portes que vous ajoutez, il n’y a jamais
qu’un seul panneau, une seule conversation et une seule session : reach
ajoute des portes, pas des pièces.
mode="selection" et reach="selection" ne sont pas la même chose
Le mot joue sur deux tableaux, et c’est ici le plus facile à mal lire :
data-olotalk-mode="selection", le sélectionner-pour-demander est l’assistant. Rien ne se pose sur la page au repos, il n’y a de bouton nulle part, et surligner du texte est la seule entrée.data-olotalk-mode="bubble" data-olotalk-reach="selection", la bulle de coin est l’assistant, et le surlignage n’est qu’une entrée supplémentaire vers elle. Le launcher reste là, puisque c’est précisément ce qu’est une bulle.
Si vous voulez le sélectionner-pour-demander sans aucun bouton sur la page, c’est la première forme, toute seule.
Garder le panneau là où il vit
Par défaut, un surlignage amène le panneau jusqu’aux mots : la réponse arrive là où la question a été posée, même pour une bulle de coin. Si votre assistant est un point fixe que vos visiteurs ont déjà repéré, vous préférerez peut-être qu’il ne bouge pas :
data-olotalk-mode="bubble"
data-olotalk-reach="selection"
data-olotalk-selection-answers="in-place"
Le panneau s’ouvre alors là où l’assistant vit, toujours avec le passage cité
au-dessus d’un composer vide. beside est la valeur par défaut, et toute autre
valeur est ignorée avec un avertissement en console. Cela ne concerne que le
déclencheur de sélection : vos propres appels à open({ anchor }) ne changent
pas.
Sur téléphone
Vous ne choisissez pas de forme mobile. À la largeur d’un téléphone, les
montages coin, bord, centré et ancré deviennent la même feuille en bas
d’écran, et inline reste dans le flux où vous l’avez posé. Un embed, les
deux présentations.
Méthodes et propriétés
const el = document.querySelector('olotalk-assistant')
el.open()
el.close()
await el.destroy()
// Définit config/thème par code (déclenche une reconstruction)
el.config = { ...assistantConfig }
el.theme = 'dark'
L’élément se reconstruit automatiquement quand ses attributs observés changent.
Langue adaptative (après le premier tour)
Quand le premier message d’un visiteur est rédigé dans une langue prise en charge différente de la langue courante de l’interface, l’assistant :
- répond dans la langue détectée ;
- affiche un prompt inline au-dessus du champ de saisie :
Continue in {language}? · Yes / No; - sur Yes, recharge la config assistant dans la nouvelle locale, remplace le dictionnaire et les suggestions de questions, puis persiste le choix dans
localStoragesousolotalk:lang:{assistantId}; - sur No, verrouille la locale courante dans la session pour que le prompt ne réapparaisse pas.
Les visiteurs de retour montent directement dans la langue qu’ils ont déjà acceptée. Il n’existe pas d’API pour piloter ce prompt de manière programmatique ; c’est un comportement passif déclenché par la détection côté API.
Pour contourner complètement le prompt, fixez la locale via data-olotalk-locale. Un override explicite l’emporte sur tous les signaux de détection automatique : le prompt ne se déclenche pas et l’interface reste dans la langue choisie.
Piloter la langue depuis votre interface
Si votre site a son propre sélecteur de langue, prévenez l’assistant quand le visiteur s’en sert :
Olotalk('locale', 'fr') // embed par balise script
getAssistant(id).setLocale('fr') // import direct
el.setAttribute('locale', 'fr') // élément personnalisé
L’appel échange l’interface, le sens de lecture et les questions suggérées sur
place, la conversation ouverte est conservée, et prévient le serveur, si
bien que les réponses changent de langue elles aussi, pas seulement le panneau
autour d’elles. Utilisez-le dès que votre sélecteur ne recharge pas la page,
c’est-à-dire dans toute application monopage : l’assistant résout sa langue une
seule fois, au montage, à partir de data-olotalk-locale, puis du choix déjà
accepté par le visiteur, puis de <html lang>, puis du navigateur. Rien ne
relit ces signaux ensuite, donc sans cet appel le panneau continue de répondre
dans la langue que le visiteur vient de quitter.
N’utilisez pas Olotalk('init', { locale }) pour cela : init reconstruit
l’assistant et jette au passage tout ce que le visiteur était en train de
demander.
Un arbitrage mérite d’être connu : fixer une langue, au montage avec
data-olotalk-locale comme après coup avec cet appel, est une instruction
explicite, et elle l’emporte donc sur les signaux du visiteur. Le prompt
adaptatif ci-dessus ne se déclenchera pas tant qu’une langue est fixée, puisque
vous avez déjà répondu à la question qu’il pose. Si vous préférez laisser les
visiteurs choisir eux-mêmes, ne fixez pas de locale : l’assistant suit alors
<html lang> à chaque chargement et propose le changement quand quelqu’un
écrit dans une autre langue.
L’ensemble des langues prises en charge se configure par assistant, sur l’étape Source du builder. Ouvrez votre assistant depuis Assistants, puis développez Ingestion status, coverage & languages. La détection automatique reste bornée à cet ensemble : une langue hors de cette liste est ignorée aussi bien pour la résolution initiale que pour le prompt adaptatif.
Déclencher l’assistant depuis un bouton personnalisé
Un pattern fréquent consiste à utiliser votre propre bouton au lieu du launcher
flottant par défaut. Montez mode="corner" : c’est le même panneau de coin que
bubble, mais sans élément affiché au repos. Ensuite, transformez n’importe quel
bouton en porte avec data-olotalk-open.
<button data-olotalk-open>Discuter avec nous</button>
<script
src="https://cdn.jsdelivr.net/npm/@olotalk/assistant-loader@0/dist/loader.iife.js"
data-olotalk-assistant-id="ast_oltk_7Kd2mQxRv9TbNhLpW3Zsy"
data-olotalk-mode="corner"
async
></script>
Si vous gardez le mode bubble par défaut, votre bouton devient une porte en
plus ; il ne retire pas le launcher intégré. Ce launcher vit dans le shadow root
de l’assistant et n’est pas destiné à être masqué par le CSS de la page.
Types TypeScript
Si vous utilisez TypeScript, déclarez la globale pour obtenir le type-checking :
// global.d.ts
declare global {
interface Window {
Olotalk?: (command: 'open' | 'close' | 'destroy' | 'init' | 'locale', payload?: any) => void | Promise<void>
OlotalkConfig?: {
assistantId?: string
siteId?: string
origin?: string
locale?: string
theme?: 'light' | 'dark' | Record<string, string>
mode?: string // which shape — see Shapes above
reach?: string // extra triggers, e.g. 'selection,commandk'
selectionAnswers?: 'beside' | 'in-place'
placement?: 'floating' | 'embedded' // deprecated — use mode
mount?: string
cdnBase?: string
version?: string
cssUrl?: string
}
// Note: conversion / capture de lead / règles CTA sont configurées côté serveur
// (Action policy dans le dashboard), PAS via cet objet de config client.
}
}
export {}
Avant le boot de l’assistant
N’appelez pas Olotalk() depuis un script qui s’exécute avant le script du
loader lui-même. Une fois le loader présent sur la page, les commandes sont
mises en file automatiquement jusqu’à ce que l’assistant soit prêt ; les
gestionnaires de clic et les scripts exécutés plus tard sont donc sûrs :
// Sûr une fois le script du loader exécuté
Olotalk('open')