Concepts clés ============= Chaque fonctionnalité de Manivox.ai s'appuie sur un petit ensemble d'idées imbriquées. Les comprendre vous aidera à concevoir des agents plus intelligents, déboguer plus vite, et donner du sens à chaque réglage de la plateforme. --- Agent ----- Un **Agent** est l'unité de configuration centrale. Il définit tout ce qui concerne la gestion d'un appel : quels fournisseurs IA utiliser, le prompt système, le flux conversationnel, les réglages vocaux, le comportement face au silence, et les actions post-appel. Un seul agent peut gérer des milliers d'appels concurrents, la plateforme instancie un contexte d'exécution par appel, chacun complètement isolé des autres. ### Statuts d'agent StatutSignificationAppels entrantsSimulateur `ACTIVE` En service, l'état dans lequel tout agent est créé. Reste en dehors du chemin d'appel jusqu'à la mise en live de sa première version. ✅ Gérés par la version live. Aucune version live encore → les appels ne peuvent pas l'atteindre. ✅ Fonctionne `ARCHIVED` Hors service. La configuration, les versions et l'historique des appels sont conservés ; désarchivez en un clic pour le remettre en service. ❌ Rejetés ❌ Indisponible (agent masqué des listes du dashboard) Pour mettre un agent hors service temporairement, archivez-le : les appels entrants sont refusés mais rien n'est perdu. Le désarchivage le restaure exactement dans l'état où il était. ### Cycle de vie Un agent est créé `ACTIVE` sans version live, donc les appels réels ne peuvent pas encore l'atteindre. L'éditeur expose deux actions distinctes : - **Save**, écrit l'état de l'éditeur comme une nouvelle version nommée (un point de restauration). Ne change *jamais* ce qu'entendent les appelants. - **Make live**, promeut une version enregistrée vers la **version live** (`published_version_id`) que les appelants entendent. C'est un clic séparé et explicite. La mise en production suit toujours les trois mêmes étapes : **éditer** vos changements, les enregistrer avec **Save**, puis les mettre en service avec **Make live**. Un nouvel agent ne reçoit ses premiers appels qu'après son premier **Make live**. Voir [Versions](https://www.manivox.ai/docs/agents/versions) pour le modèle complet. **Les appels en cours ne sont jamais interrompus.** Quand vous rendez une nouvelle version live, les appels en cours continuent avec la version qui était live à leur démarrage. La nouvelle version ne s'applique qu'aux appels démarrés après. ### Portée et propriété Chaque agent appartient à un **compte client** de votre organisation. Un agent peut être assigné à plusieurs numéros simultanément (un-à-plusieurs) ; un numéro ne pointe que vers un seul agent à la fois. --- Flux conversationnel -------------------- Un **Flux** est un graphe orienté stocké en JSON dans la configuration de l'agent. Il est construit visuellement dans l'éditeur de flux et interprété au runtime à chaque appel. Le graphe a des **nœuds** (actions individuelles) et des **arêtes** (connexions entre nœuds). L'exécution démarre au nœud `start` obligatoire (le nœud Welcome) et parcourt les arêtes selon les entrées de l'appelant, les valeurs des variables et les décisions de classification du LLM. ### Deux familles de nœuds Les nœuds se répartissent en deux catégories fondamentales, et la distinction conditionne la progression du flux : CatégorieExemplesComportement **Conversationnel** Welcome, Chatbot, Agent Le flux *se met en pause* ici et attend que l'appelant parle. Un LLM traite le tour et génère une réponse vocale avant que le flux ne puisse avancer. **Non-conversationnel** Transfer, Hangup Le nœud s'exécute immédiatement, aucune entrée de l'appelant n'est attendue. L'appel transite ou se termine sans nouvel échange conversationnel. Cette distinction est critique pour concevoir des flux : les nœuds conversationnels portent le dialogue ; les nœuds non-conversationnels terminent ou redirigent l'appel. ### Routes de sortie Les nœuds conversationnels (Welcome, Agent, Chatbot) peuvent être configurés avec des **routes de sortie**, des branches nommées qui permettent au flux de quitter le nœud actuel. Chaque route est de l'un de ces deux types : une route **conversationnelle** est une intention en langage naturel qu'un LLM classificateur confronte à la conversation, s'exécutant en parallèle de la génération principale du LLM, si bien qu'une correspondance détectée avant que la réponse principale ne commence déclenche la transition immédiatement, économisant environ 250 ms par rapport à un traitement séquentiel ; une route **basée sur une règle** est une condition déterministe sur un résultat d'outil ou une variable, vérifiée instantanément par le moteur de flux, sans aucun classificateur. Les routes basées sur une règle sont disponibles sur les nœuds Welcome et Agent ; les nœuds Chatbot ne supportent que les routes conversationnelles. Voir [Types de nœuds → Routes de sortie basées sur des règles](https://www.manivox.ai/docs/agents/nodes#rule-based-exits) pour la référence complète. Chaque route de sortie crée un handle de sortie sur le nœud. Vous connectez ces handles aux nœuds qui doivent s'activer quand cette route se déclenche. ### Limites de sécurité Pour éviter les boucles infinies, le runtime impose un **maximum de 200 transitions de nœuds non-conversationnels** dans une même chaîne. Si un flux atteint cette limite, l'appel est terminé avec une erreur et l'incident est journalisé. Concevez vos flux pour éviter les chaînes séquentielles profondes de nœuds non-conversationnels. --- Fournisseurs IA --------------- Manivox.ai est agnostique des fournisseurs. Un fournisseur est un service backend configuré pour une fonction IA spécifique. Les fournisseurs sont mis en place par un administrateur de la plateforme puis rendus disponibles aux organisations. ### Types de fournisseurs TypeFonctionExemples `STT` Speech-to-Text, convertit l'audio de l'appelant en texte en temps réel via un flux WebSocket STT maison `LLM` Large Language Model, génère les réponses conversationnelles à partir de l'historique et du prompt système Endpoints compatibles OpenAI, dans la limite de la liste de modèles validés par la plateforme (compatibilité testée, tool calls inclus) `TTS` Text-to-Speech, convertit le texte en audio, streamé à l'appelant en temps réel au fur et à mesure de la synthèse Cartesia `RAG` Retrieval-Augmented Generation, le backend d'embeddings + recherche vectorielle pour les bases de connaissances RAG interne, ou un endpoint externe personnalisé `CHATBOT` Un endpoint de chat spécifique au domaine (streaming SSE) utilisé dans les nœuds Chatbot à la place du LLM standard. C'est à vous de configurer votre chatbot ; la pipeline vocale Manivox (STT/TTS) le transforme alors en voice bot. Chatbots internes personnalisés `INTEGRATION` Intégrations de services tiers (Composio) Gateway Composio MCP ### Fournir le LLM : deux options Pour le LLM, deux possibilités : Manivox peut vous fournir des modèles **au prix d'achat**, sans aucune mise en place de votre côté ; ou vous branchez **votre propre LLM avec votre clé API**, dans la limite des modèles compatibles avec la plateforme. Dans ce second cas, Manivox n'est pas responsable des latences réseau ni des performances du LLM tiers. ### Sélection de fournisseur par agent Chaque agent sélectionne indépendamment ses fournisseurs STT, LLM et TTS. Chaque nœud Agent du flux peut ensuite être configuré avec son propre **modèle LLM** pour son segment conversationnel, ce qui permet d'utiliser un modèle léger et économique pour un accueil simple et un modèle plus puissant uniquement quand c'est nécessaire. --- Variables --------- Une **variable** est une valeur nommée qui persiste pendant toute la durée d'un même appel. Les variables sont scopées à l'appel, entièrement isolées entre les appels concurrents. Référencez n'importe quelle variable dans les champs texte avec les doubles accolades : `{{variable_name}}`. Si la variable n'est pas encore définie, elle résout à une chaîne vide. Le moteur de substitution compresse les espaces consécutifs et supprime les espaces avant la ponctuation, garantissant un rendu naturel même quand une variable résout à une chaîne vide. ### Les trois buckets de variables Les variables proviennent de trois sources distinctes, peuplées dans l'ordre au démarrage de l'appel : BucketPeuplementExemples **Système** Automatique, avant l'exécution de tout nœud, lecture seule `call_id`, `from_number`, `current_date` **Init (API)** Depuis les fetch API pré-appel, configurés dans les variables d'initialisation de l'agent `customer_name`, `account_id`, `product` **Collectée** Pendant l'appel, par extraction LLM (`collectVariables` dans les nœuds Agent) ou par réponses d'appels d'outils `caller_email`, `order_status`, `birth_date` ### Variables système (liste complète) Ces 12 variables sont toujours disponibles dès le premier nœud, aucune configuration requise : VariableTypeExempleDescription `call_id` string `clh7v2b3e0000356k26fdmzev` Identifiant unique de l'appel (CUID2) `call_start_time` ISO 8601 `2026-05-27T14:32:01+02:00` Horodatage de la prise d'appel `from_number` E.164 `+33612345678` Numéro de l'appelant au format international `from_number_local` string `06 12 34 56 78` Numéro de l'appelant formaté en affichage local (format 06/07 pour la France) `to_number` E.164 `+33155551234` Le numéro qui a reçu l'appel `call_direction` string `inbound` ou `outbound` Direction de l'appel (lowercase tel qu'exposé dans le contexte LLM) `agent_name` string `Acme Receptionist` Nom d'affichage de l'agent (tel que défini dans l'éditeur) `current_date_time` string `27/05/2026 14:32` Date et heure actuelles (fuseau Europe/Paris, JJ/MM/AAAA HH:MM) `current_date` string `27/05/2026` Date seule (JJ/MM/AAAA) `current_time` string `14:32` Heure seule (HH:MM, 24h) `current_day_of_week` string `Tuesday` / `Mardi` Nom du jour de la semaine dans la langue de l'agent `current_year` string `2026` Année courante sur 4 chiffres Toutes les variables de date/heure utilisent le fuseau **Europe/Paris**. Elles sont injectées automatiquement dans le contexte LLM, pas besoin de les référencer explicitement dans le prompt système pour que le LLM connaisse la date et l'heure. --- Appels ------ Un **appel** est l'enregistrement d'une conversation téléphonique. Chaque appel a une direction, un cycle de statuts, et une charge de données riche qui s'accumule au fil de la conversation. ### Direction DirectionComment ça démarreCas d'usage typique `INBOUND` Un appelant compose l'un de vos numéros. La plateforme reçoit l'appel, l'associe à l'agent du numéro, et démarre la conversation. Support client, helpdesk, prise de rendez-vous `OUTBOUND` *Bientôt disponible.* Vous déclencherez l'appel via le dashboard, une [campagne](https://www.manivox.ai/docs/calls/campaigns) ou l'[API Appels](https://www.manivox.ai/docs/api/calls) ; la plateforme composera le numéro cible. Rappels, sondages, relances, prospection sortante ### Statuts d'appel StatutSignification `QUEUED` L'appel a été créé mais la session SIP n'est pas encore établie. Dure typiquement <1 seconde. `RINGING` La jambe d'appel est en cours d'établissement et attend d'être décrochée. En sortant : le SIP INVITE a été envoyé à l'appelé et sonne. En entrant : le SIP INVITE a été reçu et la plateforme connecte l'appelant à l'agent. `IN_PROGRESS` L'appel a été pris. Le runtime de l'agent est actif et la conversation se déroule. `COMPLETED` L'appel s'est terminé normalement, l'agent a atteint un nœud Hangup, l'appelant a raccroché, ou le timeout de silence a expiré. `FAILED` Une erreur technique a empêché l'aboutissement de l'appel, erreur SIP, défaillance d'un fournisseur ou exception du flux. `BUSY` Sortant uniquement : le numéro appelé a retourné un signal d'occupation. `NO_ANSWER` Sortant uniquement : le numéro appelé a sonné mais n'a pas été décroché dans le délai imparti. `CANCELED` L'appel a été annulé avant d'être décroché, typiquement par la plateforme ou via une requête API. ### Contenu d'un enregistrement d'appel Après un appel, l'enregistrement est enrichi avec : - **Transcription**, chaque tour, avec rôle du locuteur, texte, horodatage (epoch ms), et métriques de latence par tour - **Événements**, chronologie des transitions de flux (`node_entered`, `exit_route_taken`, `transfer_attempted`, etc.) - **Variables**, snapshot de toutes les variables d'appel au moment où l'appel s'est terminé - **Appels d'outils**, log détaillé de chaque appel API ou action Composio exécutée pendant l'appel - **Résumé**, résumé de la conversation généré par LLM (produit de manière asynchrone, juste après la fin d'appel) - **Objectifs**, résultats d'évaluation KPI si l'évaluation est configurée sur l'agent - **Enregistrement**, fichier audio WAV, si l'enregistrement était activé --- Organisations et comptes ------------------------ Vos données — agents, appels, numéros, connexions — appartiennent à votre organisation et ne sont accessibles qu'à elle. Aucun accès inter-organisations n'est possible, by design. ### Organisations Votre **organisation** est votre espace racine : elle regroupe vos utilisateurs, agents, appels, campagnes, numéros, clés API et intégrations. Un utilisateur appartient à exactement une organisation. ### Comptes Un **compte** représente un client final (ou une unité métier) au sein de votre organisation — par exemple, un revendeur télécom gérant plusieurs entreprises clientes crée un compte par entreprise. **Chaque client doit avoir son propre compte** : la réglementation sur l'attribution des numéros et la traçabilité légale des appels l'exige. Le compte porte le process KYC (requis pour commander des numéros), les numéros et les agents de ce client. Chaque compte possède également un **mode d'accès** (`AccountAccessMode`) qui détermine s'il est exposé comme portail client. En mode **Interface externe**, le compte est géré uniquement depuis le dashboard de votre organisation ; en mode **Portail Manivox**, le compte est publié comme un portail client hébergé par Manivox dans lequel vos propres clients se connectent directement. Le mode d'accès est la porte d'entrée vers la fonctionnalité de portail, voir [Comptes & Portail](https://www.manivox.ai/docs/accounts/index). ### Rôles utilisateurs RôlePermissions `SUPER_ADMIN` Accès au niveau plateforme. Gère les fournisseurs, trunks, toutes les organisations. Inaccessible aux utilisateurs réguliers. `ADMIN` Administrateur de l'organisation. Accès complet à toutes les ressources de l'organisation, y compris la facturation et la gestion des utilisateurs. `USER` Utilisateur standard. Peut créer et éditer des agents, lancer des appels et des campagnes, gérer les intégrations. `VIEWER` Lecture seule. Peut parcourir les agents, appels, campagnes et statistiques mais ne peut rien créer ni modifier. ### Rôles utilisateurs du portail Quand un compte fonctionne en mode **Portail Manivox**, les personnes qui se connectent à ce portail sont des **utilisateurs de portail** (`AccountUser`), une identité totalement distincte des utilisateurs d'organisation ci-dessus, avec leur propre login et leur propre guard d'authentification. Ils n'apparaissent jamais dans la liste des utilisateurs de votre organisation et ne voient que l'unique compte auquel ils appartiennent. Les utilisateurs de portail ont exactement deux rôles : RôlePermissions `ADMIN` Gère les utilisateurs de portail du compte et peut compléter ou rafraîchir les connexions, en plus de tout ce qu'un viewer peut consulter. `VIEWER` Lecture seule. Peut parcourir les agents, appels et statistiques du compte mais ne peut rien modifier. Voir [Comptes & Portail](https://www.manivox.ai/docs/accounts/index) pour savoir comment activer le portail et inviter des utilisateurs de portail. --- Versions -------- À chaque sauvegarde d'agent, Manivox.ai crée un **snapshot de version** immuable capturant l'état complet de l'agent à cet instant : prompt système, JSON du flux, tous les réglages. Les versions ne sont jamais modifiées sur place, elles s'accumulent en log append-only. ### Chaque sauvegarde est un commit nommé Il n'y a **pas de sauvegarde automatique**. Les modifications s'accumulent uniquement dans le navigateur, le seul chemin d'écriture en base de données est le bouton Save de l'en-tête. En cliquant dessus, une modale s'ouvre avec un nom de version prérempli (`v{N+1}`, modifiable) et des notes optionnelles ; la validation crée le point de contrôle nommé. Les versions sont conservées indéfiniment. Si vous fermez l'onglet ou actualisez la page avant de sauvegarder, les modifications non enregistrées sont perdues. Le navigateur affiche un avertissement « Vous avez des modifications non sauvegardées » lors de la navigation, c'est le seul filet de sécurité. Le bouton Save est désactivé tant que l'éditeur ne contient aucune modification non sauvegardée, il est donc impossible de sauvegarder sans changement, l'historique des versions ne contient que des commits délibérés. ### La version live À tout moment, un agent a au plus **une version live** (`published_version_id`), celle qu'entendent les appelants. **Save ne la change jamais.** Une action **Make live** séparée et explicite déplace le pointeur. L'ancienne version live continue à servir les appels en cours jusqu'à leur fin naturelle. Deux actions de l'historique des versions couvrent l'inspection et le rollback : - **Load in editor**, hydrate l'éditeur avec le contenu de cette version sans rien écrire, et laisse l'éditeur propre. Rendez-la live telle quelle, ou éditez puis sauvegardez pour committer une nouvelle version basée dessus. - **Make live**, déplace le pointeur live vers cette version exacte en un clic, sans créer de nouvelle version. Deux boutons dans l'en-tête, deux effets bien distincts : **Save** enregistre une version de travail — les appelants n'en voient rien — et **Make live** met la version affichée en service pour les appels réels. Tant que vous ne cliquez pas sur Make live, rien ne change pour vos appelants. --- La pipeline vocale ------------------ Comprendre la pipeline temps réel vous aide à régler la latence et diagnostiquer les problèmes. Chaque tour conversationnel suit le même parcours en quatre étapes : La boucle vocale complète, détection de silence VAD, transcript STT, premier token LLM, premier octet audio TTS, se complète en moins de 800 ms sur l'infrastructure Manivox.ai. Le tableau ci-dessous détaille chaque étape. ÉtapeComposantCe qui se passe **Silence VAD** Voice Activity Detection (chez le fournisseur STT) Le fournisseur STT détecte que l'appelant a arrêté de parler. La durée de silence requise pour déclencher est contrôlée par le réglage `End-of-Utterance (EOU)` du fournisseur (par défaut ~300 ms). L'agent ne traite un tour qu'une fois ce seuil de silence franchi, cela évite que l'agent interrompe en milieu de phrase. **Transcript STT** Fournisseur STT L'audio bufferisé de l'appelant est finalisé et le texte transcrit est délivré. Cela arrive presque instantanément après le silence VAD, puisque le STT traite l'audio en temps réel pendant la parole de l'appelant. **Premier token LLM** Fournisseur LLM (streaming) Le transcript est ajouté à l'historique de conversation et envoyé au LLM. Le LLM stream sa réponse token par token. L'agent commence à passer les tokens au TTS dès la première frontière de phrase détectée, il n'attend pas la réponse LLM complète. La classification des routes de sortie tourne en parallèle dans une tâche séparée. **Premier audio TTS** Fournisseur TTS (streaming) Le TTS convertit le premier fragment de phrase en audio et le stream à la branche SIP en temps réel. Les phrases suivantes suivent au fur et à mesure que le LLM continue de générer. L'appelant entend une réponse naturelle et ininterrompue même si le texte complet n'était pas prêt quand l'audio a commencé. La cible de latence end-to-end, entre l'arrêt de parole de l'appelant et le premier octet audio entendu, est **inférieure à 800 ms** sur l'infrastructure Manivox.ai. La latence réelle dépend du réglage EOU du STT, du time-to-first-token du fournisseur LLM, et des conditions réseau entre la plateforme et les fournisseurs IA. --- Bases de connaissances ---------------------- Une **base de connaissances (KB)** est une collection de documents qu'un agent peut interroger au runtime via Retrieval-Augmented Generation (RAG). Une fois configurée, l'agent recherche dans la KB les portions de contenu pertinentes et les injecte dans le contexte LLM avant de générer une réponse, donnant à l'agent une information factuelle et à jour qu'il n'aurait pas depuis ses seules données d'entraînement. Voir [Bases de connaissances](https://www.manivox.ai/docs/knowledge-bases/index) pour les formats de documents, les options d'upload et les détails de configuration RAG. --- Numéros de téléphone (SDA) -------------------------- Un numéro **SDA** (sélection directe à l'arrivée) route les appels entrants vers vos agents. Manivox attribue les numéros à vos comptes ; vous les reliez ensuite à vos agents. Un numéro sans agent assigné rejette les appels entrants. Assignez un agent depuis **Dashboard → Comptes → \[compte\] → Numéros** ou depuis l'onglet *Numéros de téléphone* de l'éditeur d'agent. --- Campagnes --------- Les **campagnes d'appels sortants** arrivent prochainement.