Eigene Nummern verwenden (VoIP, API)

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.

Unterstützte Anbieter#

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.

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" }
  }'

{
  "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:

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

# 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": "..."}}'

{
  "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 }
  ]
}

# 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:

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:

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

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 und Ausgehende Anrufe tätigen.

Anmeldedaten rotieren#

Wenn ein Anbieterschlüssel rotiert, führen Sie den Ablauf Testen, dann Aktualisieren erneut aus:

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