Concepts fondamentaux

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 :

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.

Dans l’API : /v1/orgs, /v1/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.
• Des capacités associées : applications connectées, connexions API, bases de connaissances, serveurs MCP et outils de fonction 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.

Dans l’API : /v1/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.

Dans l’API : /v1/voices, échantillons vocaux et voix personnalisées.

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, $1/mois plus un supplément de 1 ¢/minute. 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. 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.

Dans l’API : /v1/phone-numbers, /v1/voip-connections, /v1/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.

Dans l’API : /v1/calls — liste, transcription, historique, audio, évaluation, export ; /v1/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.

Dans l’API : /v1/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). 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.

Dans l’API : /v1/publishable-key, /v1/mic-session et la documentation du SDK Widget.

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.

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.
• 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 — l’interface du tableau de bord de /v1/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.
• VoIP (/dashboard/voip-connections) — identifiants de fournisseur pour utiliser vos propres numéros de téléphone. Voir Connecter un fournisseur VoIP.

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.

Dans l’API : /v1/integrations, /v1/mcp-servers et /v1/voip-connections ; voir également Créer une intégration d’outil.

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.

Pour des appels programmatiques ponctuels : l’ API d’appels sortants.

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 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.

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.

Dans l’API : /v1/test-calls et l’exécuteur de suites — consultez Tester un agent de bout en bout.

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.

Dans l’API : /v1/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).

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.

Dans l’API : /v1/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.

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é.

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.

Dans le tableau de bord : Organisation → Alertes. Consultez Alertes.

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 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 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 (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.

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.

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).

Dans l'API : /v1/integrations et la spécification des outils de fonction.

É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.

Dans le tableau de bord : Organisation → Général. Voir Inviter votre équipe.

Dans l'API : /v1/members, /v1/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 ajoutent 3 ¢/min). 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, ainsi que la référence complète des tarifs.

Dans l'API : /v1/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é.

Tout mettre en place#