--- title: "Eigene Nummern verwenden (VoIP, API)" description: "Verbinden Sie Twilio, Telnyx, SignalWire, Vonage, Plivo oder jeden anderen SIP-Trunk über SIP, importieren Sie die Telefonnummern, die Sie bereits besitzen, und lassen Sie ThunderPhone-Agenten Anrufe darüber entgegennehmen und tätigen." --- Mit ThunderPhone genehmigte Nummern können ausgehende Anrufe tätigen und Kampagnen ausführen. Wenn Sie Nummern verwenden möchten, die Ihnen gehören und über Ihren eigenen VoIP-Anbieter laufen, führt Sie dieser Leitfaden durch den Verbindungsablauf: **Zugangsdaten testen → Verbindung erstellen → Nummern importieren → verifizieren**. Das Dashboard bietet unter **Verbindungen → VoIP** (`/dashboard/voip-connections`) eine geführte Version dieses gesamten Ablaufs: zunächst einen Pfad zum Verbinden bestehender Anbieter (Twilio und Telnyx per API-Schlüssel; SignalWire, Vonage, Plivo und jeder andere Trunk über das manuelle SIP-Formular mit anbieterspezifischen Schritten und einem KI-Generator für Einrichtungsanleitungen) und anschließend eine geführte Einrichtung, die ein neues Telnyx-Konto eröffnet. ## Unterstützte Anbieter | Anbieter | `provider`-ID | Hinweise | |----------|---------------|-------| | Twilio | `twilio` | Account SID + Auth Token; eine Verbindung pro Twilio-Konto oder -Unterkonto (siehe [Twilio-Unterkonten](#twilio-subaccounts)) | | Telnyx | `telnyx` | API-Schlüssel; geführtes Onboarding verfügbar (`setup_method: guided_telnyx`) | | SignalWire | `signalwire` | Keine native Anbieter-Verbindung; als `manual` mit der SignalWire-SIP-Voreinstellung verbinden | | Vonage | `vonage` | Keine native Anbieter-Verbindung; als `manual` mit der Vonage-SIP-Voreinstellung verbinden | | Manuelles SIP | `manual` | Beliebiger SIP-Trunk, einschließlich SignalWire, Vonage und Plivo. Wenn Sie von einer dieser Anbieter-Kacheln im Dashboard starten, ist die Verbindung weiterhin `manual` und speichert die Auswahl in `sip_config.preset` (`signalwire`, `vonage` oder `plivo`) | ## 1. Zugangsdaten testen Bevor Sie eine gespeicherte VoIP-Verbindung erstellen, testen Sie die Zugangsdaten des Anbieters, um zu bestätigen, dass sie funktionieren. Dies gibt eine `verification_evidence_id` zurück, die Sie an den Erstellungsschritt übergeben, damit die Zugangsdaten nicht doppelt für Tests belastet werden. ```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 } } ``` Wenn eine Prüfung fehlschlägt, lautet der Antwort-`status` `fail` und `checks` zeigt, welcher Schritt fehlgeschlagen ist. Korrigieren Sie die Konfiguration auf Anbieterseite (Trunk-Zuweisung, IP-Zulassungsliste, Berechtigung für ausgehende Anrufe) und versuchen Sie es erneut. ## 2. Verbindung erstellen Übergeben Sie die soeben erhaltene `verification_evidence_id`: ```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..." }' ``` Die Antwort ist ein [VoipConnection-Objekt](/api-reference/voip-connections#connection-object) mit `status="connected"`. Anmeldedaten und andere geheime Verbindungswerte werden serverseitig gespeichert und von nachfolgenden GET-Anfragen niemals im Klartext zurückgegeben. Um sie zu rotieren, führen Sie einen neuen `test` aus und führen Sie PATCH mit den neuen Nachweisen durch. ### Twilio-Unterkonten Eine Twilio-Verbindung ist an genau das Twilio-Konto gebunden, dessen Account SID und Auth Token sie enthält. Twilio verwaltet Telefonnummern und SIP- Trunks innerhalb jedes Unterkontos. Daher sieht eine mit dem Hauptkonto erstellte Verbindung nur die eigenen Nummern des Hauptkontos, und eine bestehende Verbindung kann später nicht auf ein anderes Unterkonto umgestellt werden. Um Nummern in Unterkonten zu erreichen, erstellen Sie eine Verbindung pro Unterkonto. Das Dashboard erledigt dies für Sie: Wenn Sie ein Hauptkonto mit aktiven Unterkonten verbinden, listet der Einrichtungsdialog diese auf. Wählen Sie die gewünschten aus, und ThunderPhone erstellt in jedem eine Verbindung (und einen SIP-Trunk). Derselbe Ablauf ist über die API verfügbar: ```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..."]}' ``` Die Antwort enthält pro Unterkonto eine Zeile mit dem `status` `created`, `skipped` (bereits verbunden) oder `failed` sowie einem `error`, auf den Sie reagieren können. Die Zeilen sind unabhängig, sodass ein Fehler in einem Unterkonto die anderen niemals blockiert. Eine `discovery_id` bleibt 30 Minuten gültig, sodass eine fehlgeschlagene Zeile einfach erneut versucht werden kann. Unterkonto-Token werden zum Zeitpunkt der Ermittlung von Twilio gelesen und in der neuen Verbindung gespeichert; sie werden niemals über die API zurückgegeben. Jede neue Verbindung importiert und verifiziert Nummern anschließend genau wie eine von Ihnen manuell erstellte Verbindung. Fügen Sie `"enable_transfers": true` hinzu, um auch Anrufweiterleitungen für den SIP-Trunk jeder neuen Verbindung zu aktivieren; ein Fehler dabei wird im `test_result.transfer_enable_error` dieser Verbindung gemeldet und führt nicht zum Fehlschlagen der Zeile. ## 3. Nummern auflisten und importieren Prüfen Sie die für Ihre Anmeldedaten sichtbaren Nummern, die sich noch nicht in einer ThunderPhone-Organisation befinden: ```bash curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Importieren Sie anschließend die gewünschten Nummern: ```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"]}' ``` Jeder Import wird zu einer [Telefonnummernressource](/api-reference/phone-numbers) in Ihrer Organisation mit `number_type="voip"` und `status="provisioning"`. ## 4. Jede importierte Nummer verifizieren Der Import registriert die Nummer als *verfügbar*; um Anrufe tatsächlich über sie weiterzuleiten, ist eine Verifizierung erforderlich. Bei Provider-Verbindungen (Twilio, Telnyx) werden dabei die Provider-Zugangsdaten und die SIP-Erreichbarkeit erneut geprüft. Bei einer **manuellen SIP**-Verbindung wird zunächst ein Loopback-Selbstanruf versucht: ThunderPhone führt einen kurzen Testanruf *von* der Nummer *über* Ihren SIP-Trunk *zurück zu derselben Nummer* durch. Wenn dadurch der eingehende Pfad nicht verifiziert werden kann, wird auf einen kurzen Testanruf *von* der Nummer *über* Ihren SIP-Trunk *zu* einer ThunderPhone-Nummer zurückgegriffen. Diese Tests prüfen Benutzername, Passwort, Transport, ausgehendes Routing und eingehende Zustellung des Trunks. Ihr Netzbetreiber berechnet diese Anrufe wie jeden anderen Anruf. ```bash curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` Bei Erfolg wechselt `voip_verification_status` zu `verified`, und die Nummer erhält `status="active"`. Eine Nummer in Ihrem eigenen Telnyx-Konto nimmt weiterhin eingehende Anrufe an, wenn ihr Testanruf fehlschlägt oder ausgehende Anrufe noch nicht eingerichtet sind: Sie erhält `status="active"` mit auf `unverified` gesetztem `voip_verification_status`, und die Antwort nennt den Grund. Bei einem Fehler beschreibt die Antwort detailliert, was fehlgeschlagen ist — bei einem manuellen Trunk ist das die SIP-Antwort des Anbieters, beispielsweise *„ThunderPhone-Anmeldedaten abgelehnt (SIP 401)“* oder *„ein Anruf konnte nicht weitergeleitet werden (SIP 404)“* — beheben Sie das Problem (Anmeldedaten, zulässige Quell-IP-Adressen, eine fehlende Trunk-Zuweisung im Anbieter-Dashboard) und rufen Sie erneut an. Bei einer manuellen SIP-Verbindung mit Allowlist schlägt der Test eingehender Anrufe ebenfalls fehl, wenn diese Allowed Source IPs einen tatsächlichen eingehenden Anruf blockieren würden. ## 5. Agenten zuweisen und einen Anruf annehmen Sobald die Nummer verifiziert ist, weisen Sie eingehende / ausgehende Agenten genauso zu wie bei einer ThunderPhone-Nummer. Siehe [Eingehende Anrufe bearbeiten](/de/guides/handle-inbound-calls) und [Ausgehende Anrufe tätigen](/de/guides/place-outbound-calls). ## Anmeldedaten rotieren Wenn ein Anbieterschlüssel rotiert, führen Sie den Ablauf Testen, dann Aktualisieren erneut aus: ```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" }' ``` Die Verbindung bleibt bestehen — Sie müssen keine Nummern erneut importieren. --- ## Nächste Schritte Jedes Feld in den Antworten für Verbindung, Nachweis und Import. Agenten zuweisen, zwischen Organisationen übertragen, Nummern freigeben. Da Sie nun Eigentümer der Nummer sind, können Sie ausgehende Anrufe tätigen.