Developer cookbook

Eigene Nummern nutzen (VoIP, API)

Verbinden Sie Twilio oder Telnyx – oder einen beliebigen SIP-Trunk –, importieren Sie Ihre vorhandenen Telefonnummern und lassen Sie ThunderPhone-Agenten darüber Anrufe entgegennehmen und tätigen.

Demonummern eignen sich für die Prototypenerstellung, aber Produktionsdatenverkehr sollte Nummern verwenden, die Ihnen über Ihren eigenen VoIP-Anbieter gehören. Dieser Leitfaden führt Sie durch den dreistufigen Ablauf: Zugangsdaten testen → Verbindung erstellen → Nummern importieren → verifizieren.

Unterstützte Anbieter#

1. Zugangsdaten testen#

Bevor Sie eine persistente VoIP-Verbindung erstellen, prüfen Sie die Anbieterzugangsdaten, um ihre Funktion zu bestätigen. Dadurch wird eine verification_evidence_id zurückgegeben, die Sie an den Erstellungsschritt übergeben, damit die Zugangsdaten nicht doppelt für Tests abgerechnet 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 anbieterseitige Konfiguration (Trunk-Zuweisung, IP-Zulassungsliste, Autorisierung für ausgehende Anrufe) und versuchen Sie es erneut.

2. Verbindung erstellen#

Übergeben Sie die gerade 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". Zugangsdaten werden serverseitig gespeichert und von nachfolgenden GET-Anfragen niemals als Klartext zurückgegeben — führen Sie für eine Rotation einen neuen test aus und PATCHen Sie mit dem neuen Nachweis.

3. Nummern auflisten und importieren#

Prüfen Sie die für Ihre Zugangsdaten sichtbaren Nummern, die noch nicht in einer ThunderPhone-Organisation vorhanden sind:

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 source="voip" und status="provisioning".

4. Jede importierte Nummer verifizieren#

Durch den Import wird die Nummer als verfügbar registriert; um Anrufe tatsächlich darüber weiterzuleiten, ist eine Roundtrip-Verifizierung erforderlich (eingehende Einwahlprüfung + ausgehende Autorisierungsprüfung).

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". Bei einem Fehler beschreibt die Antwort, was fehlgeschlagen ist — beheben Sie ihn (oft fehlt eine Trunk-Zuweisung im Provider-Dashboard) und rufen Sie den Endpunkt erneut auf.

5. Agenten zuweisen und einen Anruf annehmen#

Nachdem die Nummer verifiziert wurde, weisen Sie eingehende / ausgehende Agenten auf dieselbe Weise wie einer Demo-Nummer zu. Siehe Eingehende Anrufe bearbeiten und Ausgehende Anrufe tätigen.

Zugangsdaten rotieren#

Wenn ein Provider-Schlüssel rotiert wird, führen Sie den Ablauf „erst 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 die Nummern nicht erneut importieren.

Nächste Schritte#