Getting Started

Concepts de base

Une vue d’ensemble de tout ce qui compose la plateforme : le rôle de chaque objet, son emplacement dans le tableau de bord et l’API qui l’utilise.

ThunderPhone est une plateforme complète pour créer, exécuter et améliorer des agents vocaux IA. Cette page est la carte : chaque concept que vous rencontrerez, présenté dans une courte section, avec l'interface du dashboard et l'API qui le prend en charge. Parcourez-la une fois, puis revenez-y chaque fois qu'un terme nécessite une explication.

La barre latérale du dashboard reflète 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 à une seule 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 rattachée à une organisation. Ce rattachement rend l'API REST si simple : vous n'indiquez jamais d'identifiant d'organisation dans les chemins d'URL, car votre clé l'identifie déjà.

Dans le dashboard : 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 dit l'agent et son comportement — y compris les actions d'appel telles que les transferts, les appuis sur le clavier et les raccrochages, qui sont de simples lignes du prompt plutôt que des configurations distinctes.
• Un niveau de moteur (spark, bolt, storm-*) : Spark est optimisé pour le coût, Bolt pour la vitesse et 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'acquiescement, piste de fond, délai d'expiration de mise en attente.

Les modifications dans le builder sont enregistrées automatiquement dans un brouillon ; rien n'est mis en ligne tant que vous ne cliquez pas sur Déployer. Chaque déploiement est enregistré dans l'onglet Historique du builder, afin que vous puissiez inspecter et restaurer toute version précédente.

Dans le dashboard : Agents vocaux → le builder 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 vocale contient les voix qu’un agent peut utiliser, leurs échantillons lisibles, les langues compatibles, les regroupements par genre et accent, ainsi que les éventuels suppléments pour les voix/langues premium. Un outil d’écoute payant peut synthétiser votre propre phrase de 1 à 500 caractères avant 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 disposent d’un quota et d’un statut de création asynchrone ; une fois prêtes, elles apparaissent dans le même sélecteur d’agents que les voix de la bibliothèque.

Dans le dashboard : Voix (/dashboard/voices). Consultez la bibliothèque vocale et les 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 sont disponibles :

• Numéros de démonstration — de vrais numéros américains fournis depuis le pool de ThunderPhone, actifs en quelques secondes. Uniquement entrants, ils répondent avec une courte clause de non-responsabilité vocale, et le dashboard limite une organisation à 10 numéros. Parfaits pour un premier test, mais pas pour la production.
• Numéros VoIP — fournis par votre propre opérateur via une connexion VoIP. Twilio et Telnyx se connectent directement (Telnyx propose une configuration guidée) ; SignalWire et Vonage seront bientôt disponibles — aujourd’hui, vous pouvez y accéder via une configuration SIP manuelle, qui accepte n’importe quel trunk SIP. 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 entrant et d’étiqueter le numéro.

Dans le dashboard : Numéros de téléphone (/dashboard/phone-numbers). Consultez 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 journal d’appel. Un appel contient la transcription complète avec rôles, l’historique structuré des tours de parole (y compris les appels d’outils), un enregistrement, le total de facturation, ainsi que des évaluations IA et des rapports de problèmes facultatifs.

Lorsqu’un appel est en direct, vous pouvez l’ouvrir et l’écouter discrètement — vous rejoignez l’appel en silence et personne ne vous entend. Une fois à l’écoute, vous pouvez utiliser le chuchotement : saisissez une instruction qui est envoyée directement à votre agent pendant l’appel ; la personne qui appelle ne l’entend jamais, et l’agent la suit 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. Consultez Examiner, écouter et coacher vos appels.

Dans l’API : /v1/calls — liste, transcription, historique, audio, évaluation, exportation ; /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 adresses e-mail des lecteurs approuvés, importent un logo et une couleur d’accentuation, 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 obtenir d’accès au dashboard.

Dans le dashboard : Portails clients (/dashboard/client-portals). Consultez Portails clients.

Dans l’API : /v1/client-portals pour l’interface de gestion administrative.

Widgets web#

Le widget web offre aux visiteurs de votre site une conversation avec un agent via micro — aucun numéro de téléphone requis. Il s’authentifie avec une clé publiable (pk_live_...) verrouillée par origine sur vos domaines autorisés, ce qui le rend sûr à utiliser dans du code côté client.

Les clés fonctionnent dans l’un de deux modes : agent (lié statiquement à un agent) ou webhook (votre serveur choisit la configuration pour chaque visiteur — voir Configuration dynamique par appel). Les sessions de widget utilisent la même infrastructure d’appel 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 l’exige.

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-vous une fois, puis activez pour chaque opération les outils correspondants (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 rédige la définition de l’outil, ou créez-la manuellement ; un bouton Tester la requête lance un appel sandbox avant le déploiement. Voir Connexions API — l’interface 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 endpoint MCP afin qu’un client MCP externe puisse lister les agents, consulter 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 passe des appels sortants à grande échelle : importez un CSV de contacts, choisissez l’agent et le numéro d’appelant, puis définissez la plage d’appel (jours et heures, avec prise en compte du fuseau horaire), la concurrence et la politique de relance (nombre maximal de tentatives et résultats — pas de réponse, messagerie vocale, échec — à relancer). 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 les appels ponctuels par programmation : l’ API d’appels sortants.

Surveillance en direct#

Live affiche chaque appel en cours dans l’organisation et vous permet d’ouvrir n’importe lequel pour écouter et chuchoter en temps réel. C’est l’interface de supervision : observez un nouveau prompt recevoir son premier trafic réel, ou surveillez une campagne en cours.

Dans le tableau de bord : Live (/dashboard/live). Consultez Surveiller et superviser les appels en direct.

Simulations#

Une simulation est un appelant IA qui mène une véritable conversation avec votre agent — même parcours téléphonique, véritable transcription, véritable évaluation — afin que vous puissiez tester avant (et après) le déploiement. Ciblez 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), et observez l’appel en direct.

Les scénarios sont regroupés en suites qui définissent un taux de réussite minimal et peuvent bloquer des versions 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 d’appels réels en vérifications de régression reproductibles à un seul tour. Chaque exemple fige le contexte de 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 agent/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 (prompts, moteurs ou paramètres différents), répartissez le trafic entre elles et comparez les résultats par variante. Utilisez-la plutôt que d’implémenter vous-même 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 incident signalé sur un appel spécifique — créé par un examinateur humain ou détecté par l’évaluation IA. Les problèmes comportent un niveau de gravité, une source et un statut, et la page Problèmes sert de 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 modes d’envoi :

• Points de terminaison 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 hérité à URL unique : une URL par organisation. Géré dans /v1/webhook ou sous Organisation → Général. Conservé pour assurer 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). Vous disposez de 10 secondes maximum pour répondre ; en cas de délai d’expiration, l’agent attribué statiquement prend en charge l’appel.
• Les événements non bloquants sont des notifications envoyées sans attendre de réponse, avec de nouvelles tentatives utilisant un backoff exponentiel — consultez la sémantique de livraison.

Chaque requête contient une signature HMAC-SHA256 dans 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 en pleine conversation. Vous fournissez à ThunderPhone un schéma de fonction de style 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 et transmet le résultat à l’agent.

Les agents proposent é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 constructeur (consultez Connexions).

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

Équipe et rôles#

Chaque organisation possède 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 — consultez SSO.

Dans le tableau de bord : Organisation → Général. Consultez 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 en sont débités selon le tarif par minute de l’agent (niveau de moteur plus suppléments — le constructeur 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 soit jamais interrompu en pleine phrase.

Dans le tableau de bord : Organisation → Paramètres de facturation et Historique de facturation. Consultez 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é à l’application#

Le tableau de bord inclut un copilote intégré — demandez-lui « comment faire X » et il répond à partir de cette documentation, propose des guides pas à pas qui mettent en évidence les véritables commandes, et peut relancer n’importe quelle visite guidée. C’est le moyen le plus rapide de trouver une commande mentionnée sur cette page. Consultez Demander au copilote intégré à l’application.

Tout assembler#