> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Eigene Rufnummern verwenden (VoIP, API)

> Verbinden Sie Twilio oder Telnyx — oder einen beliebigen SIP-Trunk — und importieren Sie Rufnummern aus Ihrem bestehenden Konto.

Demo-Nummern eignen sich gut für die Prototypenerstellung, aber für Produktionsverkehr sollten Sie Rufnummern verwenden, die Ihnen gehören und über Ihren eigenen VoIP-Anbieter bereitgestellt werden. Dieser Leitfaden führt Sie durch den dreistufigen Ablauf: **Anmeldedaten testen → Verbindung erstellen → Nummern importieren → überprüfen**.

<Note>
  Das Dashboard bietet unter **Verbindungen → VoIP** (`/dashboard/voip-connections`) eine geführte Version dieses gesamten Ablaufs: eine geführte Telnyx-Einrichtung für die Kontoerstellung und API-Schlüssel, einen Pfad zum Verbinden eines bestehenden Kontos sowie ein manuelles SIP-Formular mit einem Generator für KI-Einrichtungsleitfäden.
</Note>

## Unterstützte Anbieter

| Anbieter      | `provider`-ID | Hinweise                                                                      |
| ------------- | ------------- | ----------------------------------------------------------------------------- |
| Twilio        | `twilio`      | API-Schlüssel + Secret                                                        |
| Telnyx        | `telnyx`      | API-Schlüssel; geführtes Onboarding verfügbar (`setup_method: guided_telnyx`) |
| SignalWire    | `signalwire`  | **Demnächst verfügbar** — verbinden Sie sich heute über manuelles SIP         |
| Vonage        | `vonage`      | **Demnächst verfügbar** — verbinden Sie sich heute über manuelles SIP         |
| Manuelles SIP | `manual`      | Jeder SIP-Trunk — verwenden Sie Ihre eigene Konfiguration                     |

## 1. Anmeldedaten testen

Bevor Sie eine gespeicherte VoIP-Verbindung erstellen, testen Sie die
Anmeldedaten 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 Anmeldedaten für Tests nicht doppelt abgerechnet werden.

```bash theme={null}
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 theme={null}
{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}
```

Falls eine Prüfung fehlschlägt, ist der Antwort-`status` `fail` und `checks`
zeigt, welcher Schritt fehlgeschlagen ist. Korrigieren Sie die Konfiguration auf Anbieterseite
(SIP-Trunk-Zuweisung, IP-Zulassungsliste, Berechtigung für ausgehende Anrufe) und versuchen Sie es erneut.

## 2. Verbindung erstellen

Übergeben Sie die gerade erhaltene `verification_evidence_id`:

```bash theme={null}
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 werden auf Serverseite gespeichert und bei nachfolgenden
GET-Anfragen niemals im Klartext zurückgegeben — für eine Rotation führen Sie einen neuen
`test` aus und senden Sie einen PATCH mit dem neuen Nachweis.

## 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 theme={null}
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 theme={null}
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 [Rufnummernressource](/api-reference/phone-numbers)
in Ihrer Organisation mit `source="voip"` und `status="provisioning"`.

## 4. Überprüfen Sie jede importierte Nummer

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

```bash theme={null}
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 das Problem (häufig eine fehlende Trunk-Zuweisung im
Provider-Dashboard) und rufen Sie den Endpunkt erneut auf.

## 5. Weisen Sie Agenten zu und nehmen Sie einen Anruf entgegen

Sobald die Nummer verifiziert ist, weisen Sie eingehende / ausgehende Agenten
genauso zu wie bei einer Demo-Nummer. Siehe
[Eingehende Anrufe bearbeiten](/de/guides/handle-inbound-calls) und
[Ausgehende Anrufe tätigen](/de/guides/place-outbound-calls).

## Zugangsdaten rotieren

Wenn ein Provider-Schlüssel rotiert wird, führen Sie den Ablauf „testen, dann aktualisieren“ erneut aus:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Referenz für VoIP-Verbindungen" icon="phone-volume" href="/api-reference/voip-connections">
    Jedes Feld in den Antworten für Verbindung, Nachweis und Import.
  </Card>

  <Card title="Referenz für Telefonnummern" icon="phone" href="/api-reference/phone-numbers">
    Agenten zuweisen, zwischen Organisationen übertragen, Nummern freigeben.
  </Card>

  <Card title="Ausgehende Anrufe tätigen" icon="arrow-up-right" href="/de/guides/place-outbound-calls">
    Da Ihnen die Nummer jetzt gehört, können Sie ausgehende Anrufe tätigen.
  </Card>
</CardGroup>