--- title: "Utilisez vos propres numéros (VoIP, API)" description: "Connectez Twilio, Telnyx, SignalWire, Vonage, Plivo ou tout autre trunk SIP via SIP, importez les numéros de téléphone que vous possédez déjà et laissez les agents ThunderPhone répondre aux appels et en passer avec ces numéros." --- Les numéros ThunderPhone approuvés peuvent émettre des appels sortants et exécuter des campagnes. Si vous préférez utiliser vos propres numéros via votre propre fournisseur VoIP, ce guide vous accompagne dans le flux de connexion : **tester les identifiants → créer la connexion → importer les numéros → vérifier**. Le tableau de bord propose une version guidée de l’ensemble de ce processus sous **Connexions → VoIP** (`/dashboard/voip-connections`) : d’abord un parcours de connexion d’un compte existant (Twilio et Telnyx par clé API ; SignalWire, Vonage, Plivo et tout autre trunk via le formulaire SIP manuel, avec des étapes propres au fournisseur et un générateur de guide de configuration par IA), puis une configuration guidée qui ouvre un nouveau compte Telnyx. ## Fournisseurs pris en charge | Fournisseur | ID `provider` | Notes | |----------|---------------|-------| | Twilio | `twilio` | SID de compte + jeton d'authentification ; une connexion par compte ou sous-compte Twilio (voir les [sous-comptes Twilio](#twilio-subaccounts)) | | Telnyx | `telnyx` | Clé API ; onboarding guidé disponible (`setup_method: guided_telnyx`) | | SignalWire | `signalwire` | Aucune connexion native au fournisseur ; connectez-le en tant que `manual` avec le préréglage SIP SignalWire | | Vonage | `vonage` | Aucune connexion native au fournisseur ; connectez-le en tant que `manual` avec le préréglage SIP Vonage | | SIP manuel | `manual` | Tout trunk SIP, y compris SignalWire, Vonage et Plivo. Si vous partez de l’une de ces tuiles de fournisseur dans le tableau de bord, la connexion reste `manual` et enregistre le choix dans `sip_config.preset` (`signalwire`, `vonage` ou `plivo`) | ## 1. Tester les identifiants Avant de créer une connexion VoIP persistante, testez les identifiants du fournisseur pour confirmer qu’ils fonctionnent. Cette opération renvoie un `verification_evidence_id` à transmettre à l’étape de création afin que les identifiants ne soient pas facturés deux fois pour les tests. ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections/test \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "telnyx", "credentials": { "apiKey": "KEY...", "connectionId": "123456" }, "sip_config": { "domain": "acme.sip.telnyx.com" } }' ``` ```json Response { "status": "pass", "verification_evidence_id": "b9a2...", "suggested_connection_name": "Telnyx: Acme Main (+15550001234)", "checks": { "credentials_valid": true, "inbound_reachable": true, "outbound_authorized": true } } ``` Si une vérification échoue, le `status` de la réponse sera `fail` et `checks` indiquera l’étape ayant échoué. Corrigez la configuration côté fournisseur (affectation du trunk, liste d’autorisation IP, autorisation des appels sortants), puis réessayez. ## 2. Créez la connexion Transmettez le `verification_evidence_id` que vous venez d’obtenir : ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Telnyx Main", "provider": "telnyx", "setup_method": "api_key", "credentials": { "apiKey": "KEY...", "connectionId": "123456" }, "sip_config": { "domain": "acme.sip.telnyx.com" }, "verification_evidence_id": "b9a2..." }' ``` La réponse est un [objet VoipConnection](/api-reference/voip-connections#connection-object) avec `status="connected"`. Les identifiants et autres valeurs secrètes de connexion sont stockés côté serveur et ne sont jamais renvoyés en texte brut par les GET suivants — pour les renouveler, exécutez un nouveau `test` et effectuez un PATCH avec les nouvelles preuves. ### Sous-comptes Twilio Une connexion Twilio est liée au compte Twilio unique dont elle contient l’Account SID et l’Auth Token. Twilio conserve les numéros de téléphone et les trunks SIP dans chaque sous-compte. Une connexion établie avec le compte parent ne voit donc que les propres numéros du parent, et une connexion existante ne peut pas être basculée vers un autre sous-compte ultérieurement. Pour accéder aux numéros détenus dans des sous-comptes, créez une connexion par sous-compte. Le tableau de bord le fait pour vous : lorsque vous connectez un compte parent qui possède des sous-comptes actifs, la boîte de dialogue de configuration les liste, vous cochez ceux que vous souhaitez utiliser, et ThunderPhone crée une connexion (et un trunk SIP) dans chacun d’eux. Le même flux est disponible via l’API : ```bash # Discover active subaccounts visible to the parent credentials curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}' ``` ```json Response { "discovery_id": "7c1e...", "parent": { "sid": "ACparent...", "friendly_name": "Acme" }, "subaccounts": [ { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null }, { "sid": "ACsales...", "friendly_name": "Acme Sales", "already_connected": true, "connection_id": 5 } ] } ``` ```bash # Create a connection for each selected subaccount curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}' ``` La réponse contient une ligne par sous-compte, avec un `status` de `created`, `skipped` (déjà connecté) ou `failed`, ainsi qu’une `error` sur laquelle vous pouvez agir. Les lignes sont indépendantes : un échec dans un sous-compte ne bloque jamais les autres, et un `discovery_id` reste valide pendant 30 minutes afin qu’une ligne en échec puisse simplement être relancée. Les jetons des sous-comptes sont lus depuis Twilio au moment de la découverte et stockés dans la nouvelle connexion ; ils ne sont jamais renvoyés par l’API. Chaque nouvelle connexion importe ensuite et vérifie les numéros exactement comme une connexion créée manuellement. Ajoutez `"enable_transfers": true` pour activer également les transferts d’appels sur le trunk SIP de chaque nouvelle connexion ; un échec à cette étape est signalé dans le champ `test_result.transfer_enable_error` de cette connexion et ne fait pas échouer la ligne. ## 3. Listez et importez des numéros Inspectez les numéros visibles avec vos identifiants qui ne figurent pas déjà dans une organisation ThunderPhone : ```bash curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Importez ensuite ceux que vous souhaitez utiliser : ```bash curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"numbers": ["+15550001234", "+15550009999"]}' ``` Chaque importation devient une [ressource de numéro de téléphone](/api-reference/phone-numbers) dans votre organisation avec `number_type="voip"` et `status="provisioning"`. ## 4. Vérifier chaque numéro importé L’importation enregistre le numéro comme *disponible* ; le routage effectif des appels via ce numéro nécessite une vérification. Pour les connexions à un fournisseur (Twilio, Telnyx), celle-ci vérifie à nouveau les identifiants du fournisseur et l’accessibilité SIP. Pour une connexion **SIP manuelle**, elle essaie d’abord un auto-appel en boucle : ThunderPhone effectue un court appel de test *depuis* le numéro, *via* votre trunk SIP, *vers ce même numéro*. Si cela ne permet pas de vérifier le chemin entrant, elle utilise un court appel de test *depuis* le numéro, *via* votre trunk SIP, *vers* un numéro ThunderPhone. Ces tests vérifient le nom d’utilisateur, le mot de passe, le transport, le routage sortant et la livraison entrante du trunk. Votre opérateur facture ces appels comme tous les autres. ```bash curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` En cas de réussite, `voip_verification_status` passe à `verified` et le numéro passe à `status="active"`. Un numéro de votre propre compte Telnyx continue de recevoir des appels entrants lorsque son appel de test échoue ou que les appels sortants ne sont pas encore configurés : il passe à `status="active"` avec `voip_verification_status` défini sur `unverified`, et la réponse en indique la raison. En cas d’échec, la réponse détaille ce qui a échoué — pour un trunk manuel, il s’agit de la réponse SIP de l’opérateur, par exemple *« identifiants ThunderPhone refusés (SIP 401) »* ou *« impossible d’acheminer un appel (SIP 404) »* — corrigez le problème (identifiants, adresses IP source autorisées, affectation de trunk manquante dans le tableau de bord du fournisseur), puis relancez l’appel. Pour une connexion SIP manuelle autorisée par liste blanche, le test d’appel entrant échoue également si ces IP sources autorisées bloqueraient un véritable appel entrant. ## 5. Affecter des agents et recevoir un appel Une fois le numéro vérifié, affectez des agents entrants / sortants de la même manière que pour un numéro ThunderPhone. Consultez [Traiter les appels entrants](/fr/guides/handle-inbound-calls) et [Passer des appels sortants](/fr/guides/place-outbound-calls). ## Rotation des identifiants Lorsqu’une clé fournisseur est renouvelée, exécutez à nouveau le flux de test puis de mise à jour : ```bash # 1. Test the new credentials curl -X POST https://api.thunderphone.com/v1/voip-connections/test ... # 2. PATCH the connection with the new evidence curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "credentials": { "apiKey": "NEW_KEY..." }, "verification_evidence_id": "fresh-evidence-id" }' ``` La connexion reste en place — il n’est pas nécessaire de réimporter les numéros. --- ## Étapes suivantes Tous les champs des réponses de connexion, de preuve et d’importation. Affectez des agents, transférez entre organisations, libérez des numéros. Maintenant que vous possédez le numéro, commencez à passer des appels sortants.