Brancher des actions sur votre chatbot

Le principe : Flopia est le cerveau, votre serveur les mains

Flopia décide quelle action lancer, mais ne l'exécute jamais et ne touche jamais à vos données. C'est votre serveur qui déclare les actions possibles et qui les exécute, sur les données de la personne connectée, avec une confirmation avant toute écriture.

La détection « connecté ou non » se fait chez vous : si la personne n'est pas connectée, votre serveur n'envoie aucune action à Flopia (chatbot de questions seulement). Si elle est connectée, vous envoyez votre liste d'actions.

Prérequis

• Un projet Flopia avec l'option « actions autorisées » activée, et son token (flopia_…). Le token est un secret : il reste sur votre serveur, jamais dans le navigateur.
• Votre serveur peut faire des appels HTTP sortants vers https://flopia.fr.

1. Afficher la bulle

Ajoutez cette ligne sur vos pages, avant la fermeture du corps :

<script src="https://flopia.fr/chatbot.js?v=5" defer></script>

La bulle appelle votre site en même origine sur trois routes que vous exposez :

Route (sur votre serveur)	Rôle
GET /api/chatbot/config	Apparence de la bulle (relayée depuis Flopia).
POST /api/chatbot	Reçoit un message, répond en flux (SSE).
POST /api/chatbot/confirmer	Valide une action préparée.

2. Le cœur : appeler le cerveau de Flopia

Votre serveur parle à Flopia sur une seule route, avec votre token :

POST https://flopia.fr/api/ia/completion
En-tête : X-Flopia-Token: <votre token>, Content-Type: application/json
Corps   : { system, messages, tools?, maxTokens? }
→ { texte, outils: [{ id, name, input }], stopReason }

• system : vos consignes (qui est l'assistant, comment répondre).
• messages : l'historique au format { role: 'user' | 'assistant', content }.
• tools : vos actions déclarées. À n'envoyer que si la personne est connectée. Sans tools, l'assistant répond seulement aux questions.
• La réponse contient soit du texte, soit des appels d'outils (outils) à exécuter chez vous. Flopia n'exécute rien.

3. Déclarer et exécuter vos actions

Une action, c'est une définition (ce que l'assistant peut appeler) et une fonction (ce que votre serveur fait). La définition suit le format standard « JSON Schema » :

{
  "name": "marquer_commande_expediee",
  "description": "Marque une commande comme expédiée. N'exécute rien directement : la personne confirmera.",
  "input_schema": {
    "type": "object",
    "properties": { "id": { "type": "string", "description": "Identifiant de la commande." } },
    "required": ["id"]
  }
}

Règle d'or :

• Actions de lecture (lister, consulter) : votre serveur les exécute tout de suite et renvoie le résultat au cerveau pour qu'il continue.
• Actions d'écriture (modifier, envoyer, supprimer) : votre serveur ne les exécute pas tout de suite. Il renvoie à la bulle un événement de confirmation ; l'écriture n'a lieu qu'après le « Confirmer » de la personne. La bulle affiche le bouton toute seule.

La boucle (route POST /api/chatbot)

1. La personne est-elle connectée ? Si oui, tools = vos définitions, sinon tools = [].
2. Appeler /api/ia/completion avec system, messages, tools.
3. Lire la réponse : action d'écriture → préparer une confirmation (jeton gardé 15 min) → envoyer à la bulle { type: 'confirmation', jeton, action: { titre } }. Action(s) de lecture → les exécuter, ajouter le résultat aux messages, recommencer. Sinon → envoyer { type: 'texte', t: … }.
4. Terminer avec { type: 'fin' }.

La route POST /api/chatbot/confirmer retrouve l'action par son jeton (en vérifiant que c'est la même personne), l'exécute pour de vrai, puis renvoie { type: 'texte', t: '✓ …' }.

Le contrat de la bulle (flux SSE)

Vos routes POST répondent en text/event-stream, une ligne data: {json} par événement :

Événement	Sens
{ "type": "texte", "t": "…" }	Un morceau de réponse (ou la réponse entière).
{ "type": "confirmation", "jeton": "…", "action": { "titre": "…" } }	Une action à confirmer (la bulle affiche Confirmer / Annuler).
{ "type": "erreur", "message": "…" }	Une erreur à afficher.
{ "type": "fin" }	Fin du flux.

Sécurité (à respecter)

• Le token reste sur votre serveur, jamais envoyé au navigateur.
• N'envoyez des tools que pour une personne connectée.
• Toute action ne doit agir que sur les données de la personne connectée, jamais celles d'une autre.
• Les actions d'écriture passent toujours par une confirmation.
• Vérifiez à la confirmation que c'est bien la personne qui a demandé l'action.

Besoin d'aide ?

Un exemple de serveur complet (Node) et le détail des contrats sont disponibles sur demande : écrivez-nous à [email protected] et nous vous aidons à brancher vos actions.