--- title: "Concepts fondamentaux" description: "Une vue d’ensemble de tout ce qui compose la plateforme : le rôle de chaque objet, son emplacement dans le dashboard et l’API qui l’utilise." --- ThunderPhone est une plateforme complète permettant de créer, d’exécuter et d’améliorer des agents vocaux IA. Cette page est la carte : chaque concept que vous rencontrerez, une courte section chacun, avec l’interface du tableau de bord et l’API qui la prend en charge. Parcourez-la une première fois, puis revenez-y chaque fois qu’un terme nécessite des explications. La barre latérale du tableau de bord reprend cette structure : [Agents](#agents), [voix](#voices), [numéros de téléphone](#phone-numbers), [widgets web](#web-widgets), [appels](#calls), [portails clients](#client-portals), [bases de connaissances](#knowledge-bases). [Surveillance en direct](#live-monitoring) et [campagnes](#campaigns) sortantes. [Applications, API, serveurs MCP et fournisseurs VoIP](#connections) que vos agents peuvent utiliser. [Simulations](#simulations), [ensembles de validation](#validation-sets), [expériences](#experiments), [problèmes](#issues), [rapports](#reports), [observabilité](#observability). [Équipe et rôles](#team-and-roles), [clés API](#organizations), [alertes](#alerts), [facturation](#billing). [Webhooks](#webhooks) et [outils de fonction](#function-tools) pour votre propre code. --- ## Organisations Une **organisation** est l’unité de location. Toutes les autres ressources — agents, numéros de téléphone, appels, clés — appartiennent à exactement une organisation. Votre compte peut appartenir à plusieurs organisations ; chacune dispose de son propre solde, de ses propres clés et de sa propre liste de membres. La clé API `sk_live_` que vous créez dans **Organisation → Clés** est liée à une organisation. Cette liaison rend l’API REST si simple : vous n’ajoutez jamais d’identifiant d’organisation aux chemins d’URL, car votre clé l’identifie déjà. **Dans le tableau de bord :** le sélecteur d’organisation (pied de la barre latérale) et les paramètres **Organisation** — onglets Mon compte, Général, Clés, Alertes, Paramètres de facturation et Historique de facturation. Consultez la [référence des paramètres d’organisation](/fr/guides/organization-settings). **Dans l’API :** [`/v1/orgs`](/api-reference/organizations), [`/v1/developer/api-keys`](/api-reference/developer-api-keys). --- ## Agents Un **agent** est la configuration IA qui exécute un appel. Il regroupe : - Un **prompt** qui régit ce que l’agent dit et son comportement — y compris les actions d’appel telles que les transferts, les pressions sur le clavier et les raccrochages, qui sont de simples lignes du prompt plutôt qu’une configuration distincte. - Un **niveau de moteur** (`spark`, `bolt`, `storm-*`) : Spark est optimisé pour le coût, Bolt pour la vitesse, Storm pour l’intelligence sur les prompts complexes. - Une **voix**, une **langue principale** et des **langues supplémentaires** facultatives — l’agent bascule automatiquement lorsqu’un appelant change de langue. Consultez les [langues prises en charge](/fr/guides/supported-languages). - Des capacités associées : [applications connectées](#connections), [connexions API](#connections), [bases de connaissances](#knowledge-bases), [serveurs MCP](#connections) et [outils de fonction](#function-tools) intégrés. - Des paramètres de comportement : ordre de prise de parole, mode d’acquiescements verbaux, piste sonore d’arrière-plan, délai d’attente en attente. Les modifications dans le générateur **sont automatiquement enregistrées dans un brouillon** ; rien n’est mis en ligne avant que vous ne cliquiez sur **Déployer**. Chaque déploiement est instantané dans l’onglet **Historique** du générateur ; vous pouvez ainsi examiner et restaurer toute version précédente. **Dans le tableau de bord :** **Agents vocaux** → le générateur d’agent (`/dashboard/agents`). Consultez [Créez votre premier agent vocal](/fr/guides/build-an-agent). **Dans l’API :** [`/v1/agents`](/api-reference/agents) — CRUD, duplication, transfert, historique des versions et assistants de prompt. --- ## Voix La **bibliothèque de voix** contient les voix qu’un agent peut utiliser, leurs échantillons écoutables, les langues compatibles, les regroupements par genre et accent, ainsi que les éventuels suppléments pour les voix ou langues premium. Un essai payant permet de synthétiser votre propre phrase de 1 à 500 caractères avant de faire votre choix. Les organisations éligibles peuvent également créer des **voix personnalisées** à partir d’un court échantillon WAV ou MP3. Les voix personnalisées ont un quota et un statut de création asynchrone ; une fois prêtes, elles apparaissent dans le même sélecteur d’agent que les voix de la bibliothèque. **Dans le dashboard :** **Voix** (`/dashboard/voices`). Voir [Bibliothèque de voix et voix personnalisées](/fr/guides/voice-library). **Dans l’API :** [`/v1/voices`](/api-reference/voices), [échantillons vocaux](/api-reference/voice-samples) et [voix personnalisées](/api-reference/custom-voices). --- ## Numéros de téléphone Un **numéro de téléphone** appartient à une organisation et assure le routage des appels entrants vers un agent (et peut prendre en charge les appels sortants). Deux sources : - **Numéros ThunderPhone** — véritables numéros américains fournis depuis le pool de ThunderPhone, actifs en quelques secondes, {/* rate:phone */}$1/mois plus un supplément de 1 ¢/minute{/* /rate */}. Ils sont initialement réservés aux appels entrants. Un administrateur de l'organisation peut demander l'activation des appels sortants depuis la page Numéros de téléphone ; ThunderPhone examine chaque demande manuellement, et les numéros approuvés peuvent passer des appels et lancer des campagnes. Une organisation peut en détenir 25 par défaut. - **Numéros VoIP** — fournis par votre propre opérateur via une [connexion VoIP](#connections). Twilio et Telnyx se connectent directement avec une clé API (Telnyx propose également une configuration guidée pour les nouveaux comptes) ; SignalWire, Vonage, Plivo et tout autre trunk SIP se connectent via une configuration SIP, une configuration SIP manuelle. Une fois importés et vérifiés, les numéros VoIP prennent en charge les appels entrants et sortants. Chaque ligne de numéro vous permet de définir un mode de routage, de choisir l’agent pour les appels entrants et d’ajouter un libellé au numéro. **Dans le dashboard :** **Numéros de téléphone** (`/dashboard/phone-numbers`). Voir [Obtenir un numéro de téléphone](/fr/guides/get-a-phone-number). **Dans l’API :** [`/v1/phone-numbers`](/api-reference/phone-numbers), [`/v1/voip-connections`](/api-reference/voip-connections), [`/v1/phone-number-labels`](/api-reference/phone-number-labels). --- ## Appels Chaque appel entrant, appel sortant, simulation et session de widget devient un **historique d’appel**. Un appel inclut la transcription complète étiquetée par rôle, l’historique structuré des tours (y compris les appels d’outils), un enregistrement, le total de facturation, ainsi que des évaluations par IA et rapports de problèmes facultatifs. Lorsqu’un appel est **en direct**, vous pouvez l’ouvrir et **écouter discrètement** — vous rejoignez l’appel en silence et personne ne vous entend. Une fois à l’écoute, vous pouvez **chuchoter** : saisissez une instruction qui est envoyée directement à votre agent pendant l’appel ; l’appelant ne l’entend jamais et l’agent l’exécute en direct. **Dans le dashboard :** **Historique des appels** (`/dashboard/call-history`) pour les archives et les détails de chaque appel ; **En direct** pour les appels en cours. Voir [Examiner, écouter et coacher vos appels](/fr/guides/review-calls). **Dans l’API :** [`/v1/calls`](/api-reference/calls) — liste, transcription, historique, audio, évaluation, export ; [`/v1/issue-reports`](/api-reference/issue-reports). --- ## Portails clients Un **portail client** est une vue de l’historique des appels en lecture seule, personnalisée à votre marque, destinée à un client externe. Les administrateurs de l’organisation choisissent les agents dont les appels apparaissent, ajoutent les e-mails des lecteurs approuvés, téléversent un logo et une couleur d’accent, et peuvent éventuellement vérifier un domaine personnalisé. Les lecteurs du portail peuvent consulter les détails des appels, les transcriptions et les enregistrements disponibles sans recevoir d’accès au dashboard. **Dans le dashboard :** **Portails clients** (`/dashboard/client-portals`). Voir [Portails clients](/fr/guides/client-portals). **Dans l’API :** [`/v1/client-portals`](/api-reference/client-portals) pour l’interface de gestion destinée aux administrateurs. --- ## Widgets web Le **widget web** offre aux visiteurs de votre site une conversation au micro avec un agent vocal — sans numéro de téléphone nécessaire. Il s’authentifie avec une **clé publiable** (`pk_live_...`) que les navigateurs ne peuvent utiliser que depuis vos domaines autorisés, ce qui le rend sûr dans le code côté client. La liste des domaines ne constitue pas une authentification, et les paramètres de session qu’une page peut envoyer sont désactivés tant que vous ne les avez pas autorisés sur la clé. Les clés fonctionnent dans l’un des deux modes suivants : `agent` (lié statiquement à un agent) ou `webhook` (votre serveur choisit la configuration pour chaque visiteur — voir [Configuration dynamique par appel](/fr/guides/dynamic-call-config)). Les sessions de widget passent par la même infrastructure d’appels que les appels téléphoniques. **Dans le tableau de bord :** **Widgets web** (`/dashboard/web-widgets`) — créez des widgets, définissez le mode et l’agent, gérez les domaines autorisés et copiez l’extrait d’intégration. Voir [Créer un widget web](/fr/guides/embed-a-web-widget-dashboard). **Dans l’API :** [`/v1/publishable-key`](/api-reference/publishable-keys), [`/v1/mic-session`](/api-reference/mic-sessions) et la [documentation du SDK Widget](/fr/widget/overview). --- ## Bases de connaissances Une **base de connaissances** est un ensemble de documents que votre agent peut rechercher pendant un appel afin d’étayer ses réponses — importez des fichiers, collez du texte ou importez des pages web par URL, puis associez la base de connaissances à un agent dans le builder. L’agent l’interroge avec un outil de recherche intégré lorsque la conversation le nécessite. **Dans le tableau de bord :** **Connaissances** (`/dashboard/knowledge`) pour la bibliothèque de documents ; la section **Connaissances** du builder pour en associer une à un agent. Voir [Donner une base de connaissances à votre agent](/fr/guides/knowledge-base). --- ## Connexions Les connexions permettent aux agents d’interagir avec le monde extérieur. Quatre types, un groupe dans la barre latérale : - **Applications** (`/dashboard/app-connections`) — connexions OAuth à Slack, HubSpot, Salesforce, Google Calendar, Google Sheets et Cal.com. Connectez-les une seule fois, puis activez les outils par opération (publier un message Slack, créer ou mettre à jour un contact HubSpot, réserver un créneau Cal.com…) pour n’importe quel agent. Voir [Connecter des applications](/fr/guides/connect-apps). - **API** (`/dashboard/api-connections`) — transformez n’importe quelle API HTTP en action d’agent. Collez une commande cURL et l’assistant IA prépare la définition de l’outil, ou créez-la manuellement ; un bouton **Tester la requête** lance un appel de sandbox avant le déploiement. Voir [Connexions API](/fr/guides/api-connections) — l’interface du tableau de bord de [`/v1/integrations`](/api-reference/integrations). - **MCP** (`/dashboard/mcp-connections`) — ajoutez un serveur Model Context Protocol par URL et laissez l’agent utiliser les outils qu’il expose. Voir [Ajouter un serveur MCP](/fr/guides/mcp-servers). - **VoIP** (`/dashboard/voip-connections`) — identifiants de fournisseur pour [utiliser vos propres numéros de téléphone](#phone-numbers). Voir [Connecter un fournisseur VoIP](/fr/guides/voip-providers). ThunderPhone expose également son propre point de terminaison MCP afin qu’un client MCP externe puisse répertorier les agents, examiner les appels et les transcriptions, et passer des appels. Voir [Utiliser ThunderPhone comme serveur MCP](/fr/guides/thunderphone-mcp-server). **Dans l’API :** [`/v1/integrations`](/api-reference/integrations), [`/v1/mcp-servers`](/api-reference/mcp-servers) et [`/v1/voip-connections`](/api-reference/voip-connections) ; voir également [Créer une intégration d’outil](/fr/guides/build-tool-integration). --- ## Campagnes Une **campagne** effectue des appels sortants à grande échelle : importez un fichier CSV de contacts, choisissez l’agent et le numéro d’appelant, puis définissez la fenêtre d’appel (jours et heures, avec prise en compte du fuseau horaire), la simultanéité et la politique de nouvelle tentative (nombre maximal de tentatives et résultats concernés — pas de réponse, messagerie vocale, échec — par une nouvelle tentative). La campagne parcourt la liste et enregistre chaque appel dans l’historique des appels. **Dans le tableau de bord :** **Campagnes** (`/dashboard/campaigns`). Voir [Lancer une campagne d’appels sortants](/fr/guides/outbound-campaigns). **Pour des appels programmatiques ponctuels :** l’ [API d’appels sortants](/fr/guides/place-outbound-calls). ## Surveillance en direct **En direct** affiche chaque appel en cours dans l’organisation et vous permet d’ouvrir n’importe lequel pour [écouter et utiliser le chuchotement](#calls) en temps réel. C’est l’interface de supervision : observez le premier trafic réel d’un nouveau prompt, ou gardez un œil sur une campagne en cours. **Dans le tableau de bord :** **En direct** (`/dashboard/live`). Consultez [Observer et superviser les appels en direct](/fr/guides/monitor-live-calls). --- ## Simulations Une **simulation** est un appelant IA qui mène une vraie conversation avec votre agent — même parcours téléphonique, vraie transcription, vraie évaluation — afin que vous puissiez tester avant (et après) votre mise en production. Dirigez-la vers un agent ou un numéro de téléphone, rédigez vous-même le scénario de l’appelant ou **générez des scénarios avec l’IA** à partir du prompt de l’agent (y compris les cas limites, si vous le demandez), puis observez l’appel en direct. Les scénarios sont regroupés en **suites** qui définissent un taux de réussite minimal et peuvent conditionner les mises en production dans CI ; les régressions par rapport à la référence acceptée sont signalées pour chaque scénario. **Dans le tableau de bord :** **Simulations** (`/dashboard/simulations`), ainsi que le bouton **Simulation** dans le générateur d’agents. Consultez [Simuler un appel](/fr/guides/simulate-a-call). **Dans l’API :** [`/v1/test-calls`](/api-reference/test-calls) et l’exécuteur de suites — consultez [Tester un agent de bout en bout](/fr/guides/test-agents). --- ## Ensembles de validation Un **ensemble de validation** transforme des moments réels d’appels en vérifications de régression reproductibles à un seul tour. Chaque exemple fige le contexte de la conversation, l’audio pertinent de l’appelant, la réponse d’origine et le comportement attendu. Les relectures s’exécutent sur le brouillon actuel de l’agent sans passer un autre appel, et la boîte de dialogue de déploiement peut indiquer si la dernière exécution correspond toujours à ce brouillon. **Dans le tableau de bord :** **Ensembles de validation** (`/dashboard/validation`) pour le jeu de données de l’organisation et l’onglet **Validation** du générateur d’agents pour les exécutions. Consultez [Ensembles de validation](/fr/guides/validation-sets). **Dans l’API :** [`/v1/validation-sets`](/api-reference/validation-sets) et les points de terminaison de relecture d’agent et d’exemple sur la même page de référence. --- ## Expériences Une **expérience** effectue des tests A/B de configurations d’agents sur du trafic réel : définissez des variantes (différents prompts, moteurs ou paramètres), répartissez le trafic entre elles et comparez les résultats par variante. Utilisez-la plutôt que de créer manuellement une logique de répartition dans un webhook. **Dans le tableau de bord :** **Expériences** (`/dashboard/experiments`) et l’onglet **A/B** dans le générateur d’agents. Consultez [Expériences (tests A/B)](/fr/guides/experiments-ab-testing). --- ## Problèmes Un **problème** est un problème signalé sur un appel spécifique — remonté par un évaluateur humain ou détecté par l’évaluation IA. Les problèmes comportent une gravité, une source et un statut, et la page Problèmes est la file de triage : filtrez, inspectez l’appel concerné et suivez les corrections. **Dans le tableau de bord :** **Problèmes** (`/dashboard/issues`), ainsi que le signalement par appel dans l’Historique des appels. Consultez [Triage des problèmes](/fr/guides/issues). **Dans l’API :** [`/v1/issue-reports`](/api-reference/issue-reports). --- ## Rapports Un **rapport** répond à une question en langage naturel sur vos données d’appels (« Quelles étaient les trois principales raisons pour lesquelles les appelants ont demandé à parler à un humain la semaine dernière ? ») avec une analyse rédigée par l’IA, limitée aux agents et à la plage de dates que vous choisissez. **Dans le tableau de bord :** **Rapports** (`/dashboard/reports`). Consultez [Rapports](/fr/guides/reports). --- ## Observabilité L’**observabilité** est l’interface des métriques : volume d’appels, résultats et qualité au fil du temps, filtrables par agent et fenêtre temporelle, avec export pour les analyses en aval. **Dans le tableau de bord :** **Observabilité** (`/dashboard/observability`). Consultez [Observabilité](/fr/guides/observability). --- ## Alertes Une **règle d’alerte** surveille une métrique (taux de réussite, taux d’échec, score moyen, volume d’appels, régressions de suites) sur une fenêtre temporelle et se déclenche lorsqu’elle franchit votre seuil. Les notifications sont envoyées par e-mail et Slack, et déclenchent un événement `alert.triggered` vers vos [points de terminaison webhook](/fr/webhooks/endpoints). **Dans le tableau de bord :** **Organisation → Alertes**. Consultez [Alertes](/fr/guides/alerts). --- ## Webhooks ThunderPhone envoie des **webhooks HTTP POST** à votre serveur lorsque des événements se produisent pendant et après un appel. Deux modèles de livraison : - **Points de terminaison de webhook** (recommandé) : gérez plusieurs URL dans [`/v1/developer/webhook-endpoints`](/fr/webhooks/endpoints) avec des secrets et des abonnements aux événements propres à chaque point de terminaison. - **Webhook monourl hérité** : une URL par organisation. Géré dans [`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) ou sous **Organisation → Général**. Conservé pour la rétrocompatibilité. Les événements se répartissent en deux catégories : - Les **événements bloquants** attendent que votre serveur réponde avec une configuration qui façonne l’appel en cours — les [événements d’appel entrant](/fr/webhooks/call-incoming) (`telephony.incoming` / `web.incoming`). Un appel téléphonique attend jusqu’à 13 secondes, avec une nouvelle tentative incluse, et une session de widget attend 10 secondes. Il n’existe aucun agent de secours : sans configuration utilisable, l’appel téléphonique est terminé et la session de widget échoue. - Les **événements non bloquants** sont des notifications envoyées sans attente de réponse, avec de nouvelles tentatives selon un délai d’attente exponentiel — consultez [la sémantique de livraison](/fr/webhooks/overview). Chaque requête contient une signature HMAC-SHA256 horodatée dans `X-ThunderPhone-Signature-V2`, ainsi que l’ancienne signature portant uniquement sur le corps `X-ThunderPhone-Signature`. Consultez [la vérification de signature](/fr/webhooks/overview). --- ## Outils de fonction Un **outil de fonction** est un point de terminaison HTTP que votre agent peut appeler au cours d'une conversation. Vous fournissez à ThunderPhone un schéma de fonction au format OpenAI ainsi qu'une URL de point de terminaison ; l'agent décide quand l'appeler, et ThunderPhone effectue la requête HTTP signée depuis ses serveurs puis transmet le résultat à l'agent. Les agents incluent également des **capacités d'appel intégrées** — transférer l'appel, envoyer une saisie au clavier (DTMF), terminer l'appel, attendre en attente — que vous activez avec de simples lignes de prompt plutôt qu'avec des définitions d'outils. **Dans le tableau de bord :** la section **Connexions API** du builder (voir [Connexions](#connections)). **Dans l'API :** [`/v1/integrations`](/api-reference/integrations) et la [spécification des outils de fonction](/fr/tools/overview). --- ## Équipe et rôles Chaque organisation dispose d'une liste de membres avec deux rôles : les **Membres** créent et exploitent des agents ; les **Administrateurs** gèrent également l'équipe et la facturation. Invitez par e-mail — les invitations expirent après 7 jours et peuvent être révoquées ; le menu ⋯ sur la ligne d'un membre permet de modifier les rôles ou de supprimer quelqu'un. L'authentification unique peut être configurée pour toute l'organisation — voir [SSO](/fr/guides/sso). **Dans le tableau de bord :** **Organisation → Général**. Voir [Inviter votre équipe](/fr/guides/invite-your-team). **Dans l'API :** [`/v1/members`](/api-reference/members), [`/v1/invites`](/api-reference/invites). --- ## Facturation ThunderPhone est **prépayé**. Chaque organisation dispose d'un solde en USD ; les appels le débitent au tarif par minute de l'agent (niveau de moteur plus suppléments — le builder affiche le tarif tout compris en direct lorsque vous modifiez les paramètres, et les [langues supplémentaires sélectionnées](/fr/guides/supported-languages) ajoutent {/* rate:language */}3 ¢/min{/* /rate */}). Lorsque le solde atteint zéro, les appels entrants sont refusés et les appels sortants renvoient `402 Payment Required`. Rechargez manuellement ou activez la **recharge automatique** avec un seuil de solde, un montant de recharge et une limite mensuelle de dépenses facultative — afin qu'un appel ne s'interrompe jamais au milieu d'une phrase. **Dans le tableau de bord :** **Organisation → Paramètres de facturation** et **Historique de facturation**. Voir [Ajouter des fonds et activer la recharge automatique](/fr/guides/billing-and-topups), ainsi que la [référence complète des tarifs](/fr/guides/pricing). **Dans l'API :** [`/v1/billing`](/api-reference/billing). --- ## Le copilote intégré Le tableau de bord inclut un **copilote** intégré — demandez-lui « comment faire X » et il répond à partir de cette documentation, propose des parcours guidés clic par clic qui mettent en évidence les véritables commandes, et peut rejouer n'importe laquelle des visites guidées. C'est le moyen le plus rapide de trouver une commande mentionnée sur cette page. Voir [Interroger le copilote intégré](/fr/guides/ask-the-copilot). --- ## Tout mettre en place L’assistant en cinq étapes : agent → facturation → numéro → simulation → révision. Le même premier appel en quatre requêtes REST. Créez un agent, approvisionnez-le, obtenez un numéro, simulez et examinez les appels. Applications OAuth, API personnalisées, serveurs MCP et fournisseurs VoIP. Rapports, observabilité, expériences, problèmes et alertes. Invitations et rôles, clés API, sécurité et SSO. Les recettes API : appels entrants, appels sortants, configuration dynamique, outils, tests. Effectuez correctement la vérification HMAC une fois et réutilisez-la partout.