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.

initauto au chargement
ready
open ⇄ closereste monté
destroydémonte
↺ après destroy, init() monte une nouvelle instance
init se lance automatiquement au DOMContentLoaded. open et close ouvrent et ferment la boîte de dialogue pendant que l'instance reste montée. destroy() la démonte et supprime son DOM, après quoi init() en monte une nouvelle.

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énementPayloadQuand il se déclenche
ready{ assistantId: string }L’assistant est monté et pleinement interactif
openundefinedLa boîte de dialogue s’ouvre
closeundefinedLa 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

AttributTypeDescription
assistant-idstringAssistant ID (requis)
site-idstringAlias legacy de assistant-id
originstringURL de base de l’API Olotalk, optionnelle ; par défaut l’API cloud
theme"light" | "dark" | JSONThème UI ; un objet JSON pour un override complet des tokens
modeVoir Shapes, quatorze valeursQuelle forme monter, voir Shapes ci-dessous
reachstringDéclencheurs supplémentaires par-dessus la forme montée, séparés par des virgules : "selection,commandk", voir Combiner les formes
selection-answersstringOù 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
localestringLa 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-urlstringURL de la feuille de style de l’assistant
configChaîne JSONObjet 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.

modeOù il se placeComment il s’ouvre
bubbleUn launcher dans le coin, panneau flottant au-dessus de la pageLe visiteur clique le launcher. La valeur par défaut
startersLauncher du coin, avec des questions suggérées au survolLe visiteur clique le launcher, ou une suggestion
inlineRemplit l’élément où vous le montez, toujours ouvertRien à ouvrir, il fait partie de la page
drawerPleine hauteur, collé au bord, il écarte la page au lieu de la recouvrirVotre propre bouton, data-olotalk-open ou open()
commandkCentré au-dessus d’une page assombrie⌘K / CtrlK
cornerPanneau de coin, rien sur la page au reposVotre propre contrôle, ou un déclencheur reach
centerCentré au-dessus d’une page assombrie, rien au reposVotre propre contrôle, ou un déclencheur reach
expandUne ligne dans votre page qui se déplie sur place, en poussant le contenuLe visiteur presse la ligne
anchoredÀ côté d’un élément, un plan tarifaire, une ligne de specsVotre propre affordance, avec open({ anchor })
fullpageL’assistant est la pageToujours ouvert ; rien à invoquer
sidebarUn rail fixe pleine hauteur au bordToujours ouvert ; rien à invoquer
navfieldRien de chez nous, le champ de recherche de votre navVotre champ soumet, avec open({ prefill })
askbarRien de chez nous, votre propre barre au pied de la pageVotre barre soumet, avec open({ prefill })
selectionRien 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 :

  1. répond dans la langue détectée ;
  2. affiche un prompt inline au-dessus du champ de saisie : Continue in {language}? · Yes / No ;
  3. sur Yes, recharge la config assistant dans la nouvelle locale, remplace le dictionnaire et les suggestions de questions, puis persiste le choix dans localStorage sous olotalk:lang:{assistantId} ;
  4. 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')