--- title: "Gebruik je eigen nummers (VoIP, API)" description: "Koppel Twilio, Telnyx, SignalWire, Vonage, Plivo en elke andere SIP-trunk via SIP, importeer de telefoonnummers die je al hebt en laat ThunderPhone-spraakagenten oproepen beantwoorden en plaatsen." --- Goedgekeurde ThunderPhone-nummers kunnen uitgaande oproepen plaatsen en campagnes uitvoeren. Als je liever nummers gebruikt die je bezit via je eigen VoIP-provider, leidt deze handleiding je door het verbindingsproces: **referenties testen → verbinding maken → nummers importeren → verifiëren**. Het dashboard biedt een begeleide versie van deze volledige procedure onder **Verbindingen → VoIP** (`/dashboard/voip-connections`): eerst een traject om een bestaande verbinding te maken (Twilio en Telnyx via API-sleutel; SignalWire, Vonage, Plivo en elke andere trunk via het handmatige SIP-formulier met providerspecifieke stappen en een AI-generator voor installatiehandleidingen), en daarna een begeleide installatie die een nieuw Telnyx-account opent. ## Ondersteunde providers | Provider | `provider`-id | Opmerkingen | |----------|---------------|-------------| | Twilio | `twilio` | Account-SID + Auth Token; één verbinding per Twilio-account of subaccount (zie [Twilio-subaccounts](#twilio-subaccounts)) | | Telnyx | `telnyx` | API-sleutel; begeleide onboarding beschikbaar (`setup_method: guided_telnyx`) | | SignalWire | `signalwire` | Geen native providerverbinding; verbind deze als `manual` met de SignalWire SIP-preset | | Vonage | `vonage` | Geen native providerverbinding; verbind deze als `manual` met de Vonage SIP-preset | | Handmatige SIP | `manual` | Elke SIP-trunk, inclusief SignalWire, Vonage en Plivo. Als je vanuit een van die providertegels in het dashboard begint, is de verbinding nog steeds `manual` en wordt de keuze opgeslagen in `sip_config.preset` (`signalwire`, `vonage` of `plivo`) | ## 1. Referenties testen Voordat je een opgeslagen VoIP-verbinding maakt, test je de provider- referenties om te bevestigen dat ze werken. Dit retourneert een `verification_evidence_id` die je doorgeeft aan de aanmaakstap, zodat de referenties niet dubbel in rekening worden gebracht voor 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 } } ``` Als een controle mislukt, is de `status` van het antwoord `fail` en toont `checks` welke stap is mislukt. Corrigeer de configuratie aan de providerzijde (toewijzing van trunks, IP-toegangslijst, autorisatie voor uitgaande oproepen) en probeer het opnieuw. ## 2. Maak de verbinding Geef de `verification_evidence_id` door die je zojuist hebt gekregen: ```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..." }' ``` Het antwoord is een [VoipConnection-object](/api-reference/voip-connections#connection-object) met `status="connected"`. Inloggegevens worden server-side opgeslagen en bij latere GET-aanvragen nooit als platte tekst geretourneerd — voer om te roteren een nieuwe `test` uit en gebruik PATCH met het nieuwe bewijs. ### Twilio-subaccounts Een Twilio-verbinding is gekoppeld aan het specifieke Twilio-account waarvan de Account SID en Auth Token zijn opgeslagen. Twilio bewaart telefoonnummers en SIP- trunks binnen elk subaccount, dus een verbinding die met het hoofdaccount is gemaakt, ziet alleen de eigen nummers van het hoofdaccount, en een bestaande verbinding kan later niet naar een ander subaccount worden overgezet. Maak voor nummers in subaccounts één verbinding per subaccount. Het dashboard doet dit voor je: wanneer je een hoofdaccount met actieve subaccounts verbindt, worden deze in het insteldialoogvenster weergegeven, vink je de gewenste aan en maakt ThunderPhone in elk account een verbinding (en een SIP-trunk). Dezelfde flow is beschikbaar via de 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..."]}' ``` Het antwoord bevat één rij per subaccount met de `status` `created`, `skipped` (al verbonden) of `failed`, plus een `error` waarop je kunt handelen. Rijen zijn onafhankelijk, dus een fout in één subaccount blokkeert de andere nooit. Een `discovery_id` blijft 30 minuten geldig, zodat je een mislukte rij eenvoudig opnieuw kunt proberen. Tokens van subaccounts worden tijdens de detectie uit Twilio gelezen en opgeslagen in de nieuwe verbinding; ze worden nooit via de API geretourneerd. Elke nieuwe verbinding importeert en verifieert vervolgens nummers precies zoals een verbinding die je handmatig hebt gemaakt. Voeg `"enable_transfers": true` toe om ook oproepdoorschakelingen in te schakelen voor de SIP-trunk van elke nieuwe verbinding; een fout daarbij wordt gemeld in de `test_result.transfer_enable_error` van die verbinding en laat de rij niet mislukken. ## 3. Nummers weergeven en importeren Bekijk de nummers die zichtbaar zijn met je inloggegevens en die nog niet in een ThunderPhone-organisatie staan: ```bash curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Importeer vervolgens de nummers die je wilt: ```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"]}' ``` Elke import wordt een [telefoonnummerresource](/api-reference/phone-numbers) in je organisatie met `number_type="voip"` en `status="provisioning"`. ## 4. Verifieer elk geïmporteerd nummer Importeren registreert het nummer als *beschikbaar*; om gesprekken daadwerkelijk erdoorheen te routeren, is verificatie nodig. Voor providerverbindingen (Twilio, Telnyx) worden daarbij de providerreferenties en SIP-bereikbaarheid opnieuw gecontroleerd. Voor een **handmatige SIP**-verbinding wordt eerst een loopback-zelfoproep geprobeerd: ThunderPhone plaatst een korte testoproep *vanaf* het nummer, *via* je SIP- trunk, *terug naar hetzelfde nummer*. Als daarmee het inkomende pad niet wordt geverifieerd, valt het terug op een korte testoproep *vanaf* het nummer, *via* je SIP-trunk, *naar* een ThunderPhone-nummer. Deze tests controleren de gebruikersnaam, het wachtwoord, transport, uitgaande routering en inkomende aflevering van de trunk. Je provider brengt deze oproepen net als alle andere in rekening. ```bash curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Bij succes verandert `voip_verification_status` in `verified` en krijgt het nummer `status="active"`. Een nummer in je eigen Telnyx-account blijft inkomende oproepen ontvangen wanneer de testoproep mislukt of uitgaand verkeer nog niet is ingesteld: het krijgt `status="active"` met `voip_verification_status` ingesteld op `unverified`, en het antwoord vermeldt waarom. Bij een fout geeft het antwoord precies aan wat er is mislukt — voor een handmatige trunk is dat het SIP-antwoord van de provider, bijvoorbeeld *"de inloggegevens van ThunderPhone afgewezen (SIP 401)"* of *"kon een oproep niet routeren (SIP 404)"* — los dit op (inloggegevens, toegestane bron-IP-adressen, een ontbrekende trunktoewijzing in het providerdashboard) en probeer opnieuw. Voor een handmatige SIP-verbinding met een toelatingslijst mislukt de test voor inkomende oproepen ook als die Allowed Source IPs een echte inkomende oproep zouden blokkeren. ## 5. Wijs agenten toe en neem een oproep aan Zodra het nummer is geverifieerd, wijs je inkomende / uitgaande spraakagenten op dezelfde manier toe als aan een ThunderPhone-nummer. Zie [Inkomende oproepen afhandelen](/nl/guides/handle-inbound-calls) en [Uitgaande oproepen plaatsen](/nl/guides/place-outbound-calls). ## Referenties roteren Wanneer een providersleutel wordt geroteerd, voer je de test-en-updateprocedure opnieuw uit: ```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" }' ``` De verbinding blijft bestaan — je hoeft nummers niet opnieuw te importeren. --- ## Volgende stappen Elk veld in de responsen voor verbindingen, bewijs en import. Wijs agenten toe, zet over tussen organisaties, geef nummers vrij. Nu je het nummer bezit, kun je uitgaande oproepen plaatsen.