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

# Browser-Softphone (WebRTC) einrichten

> Geben Sie Ihren Agenten eine vollständige Telefoniefläche im Browser — vom eingebauten Dashboard-Softphone bis zum eingebetteten SIP-Client in Ihrer eigenen App — mit Caller-ID-Kontrolle, rotierbaren Zugangsdaten und Mobile-Push-Pfad für eingehende Anrufe.

## Sprachhinweis

Diese deutsche Variante ist eine gekürzte Übersetzung: Die Abschnitte „1. Device registration & VoIP push tokens (mobile)" und „3. Choose how inbound calls reach the softphone" existieren nur in der englischen Fassung: [/en/guides/voice-softphone-browser-calling](https://docs.orbit.devotel.io/en/guides/voice-softphone-browser-calling). Code-Blöcke, Endpoint-Pfade, API-Feldnamen und Fehlercodes bleiben englisch.

# Browser-Softphone (WebRTC) einrichten

Das Browser-Softphone ermöglicht es einem Agenten, PSTN-Anrufe zu tätigen und anzunehmen, ohne den Browser zu verlassen — kein Tischtelefon, keine Desktop-SIP-App. Es gibt drei Wege, es einem Agenten voranzustellen, und sie teilen sich dieselben Zugangsdaten und dieselbe Infrastruktur:

1. **Das eingebaute Dashboard-Softphone** — Orbit liefert ein fertiges Softphone im Dashboard. Das ist der Zero-Code-Weg und der richtige Startpunkt für die meisten Teams.
2. **Ein eingebettetes LiveKit-basiertes Softphone** (`Softphone` in `@devotel-orbit/web`) — Sie mounten das Softphone mit eigener UI in Ihrem eigenen Agenten-Arbeitsplatz (CRM, Contact-Centre-Wall, internes Tool).
3. **Ein eingebettetes SIP-over-WSS-Softphone** (der SIP-Register-Weg) — ein klassischer SIP-Client (z. B. JsSIP), der sich direkt gegen Orbits WebRTC-zu-SIP-Gateway registriert.

## 2. Softphone-Zugangsdaten ausstellen

Ein Agenten-Browser benötigt ein kurzlebiges Credential, bevor er sich verbinden kann. Welcher Endpoint genutzt wird, hängt vom gewählten Client ab — Dashboard, eingebettetes LiveKit oder eingebettetes SIP.

### Eingebautes Dashboard- / eingebettetes LiveKit-Softphone

`POST /voice/softphone/token` liefert ein kurzlebiges LiveKit-Access-Token plus die Media-URL für die Verbindung:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/token \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Das Token ist auf einen Raum je Nutzer begrenzt, damit zwei Agenten nie eine Session teilen. Ein Anruf nach dem Verbinden ist `POST /voice/softphone/dial` mit `{ "to": "+15550123", "from": "+15559876" }`.

### Eingebettetes SIP/WSS-Softphone

Ein SIP-Client registriert sich direkt über einen WebSocket. `POST /voice/softphone/register` tauscht Ihren authentifizierten API-Request gegen ein kurzlebiges SIP-Credential:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callerIdNumber": "+15559876", "deviceLabel": "agent-desk-04" }'
```

Wichtige Eigenschaften für Ihr Design:

* Credentials leben **60 Minuten** — registrieren Sie vor `expiresAt` neu, sonst bricht die Session ab.
* `callerIdNumber` muss eine Nummer sein, die Ihre Organisation besitzt (anderenfalls 403) — so wird CLI-Spoofing beim ausgehenden Anruf blockiert.
* Der Username ist an Ihre Organisation gebunden, ein gestohlener Username kann nicht gegen einen anderen Tenant wiederverwendet werden.
* Die Token-Ausstellung ist auf **owner/admin/developer** begrenzt — kein öffentlicher, anonymer Endpoint.

> [!NOTE]
>
> Widerrufen Sie ein Credential sofort mit `DELETE /voice/softphone/credentials/:username`, wenn ein Agent geht oder ein Token leakt.

## 4. Vollständiges JS-Beispiel — Mikrofon, VoIP-Push + Browser-Fallback

Hier ist ein vollständiges, kopierbares Browser-Softphone. Es funktioniert mit beiden eingebetteten Optionen (LiveKit und SIP-over-WSS) und behandelt die Browser-Fallback-Realität:

```js theme={null}
import { OrbitSoftphone } from "@devotel-orbit/web";

const softphone = new OrbitSoftphone({
  apiBaseUrl: "https://api.orbit.devotel.io",
  apiKey: "YOUR_API_KEY", // serve from your backend — never commit it
  onCallStateChange: (s) => console.log("softphone state:", s),
  onError: (e) => handleSoftphoneFailure(e), // ← fallback lives here
});

// 1. Mic is gated on the browser's getUserMedia. Ask for it on a user
//    gesture (a click) — not page load.
async function armMicrophone() {
  await navigator.mediaDevices.getUserMedia({ audio: true });
  await softphone.connect(); // mints token + publishes mic
}

// 2. Place an outbound call.
async function callCustomer(e164) {
  return softphone.dial(e164); // returns call_id when ringing
}

// 3. Fallback: if the browser/media path can't connect, hand the call
//    to a click-to-call bridge.
function handleSoftphoneFailure(err) {
  console.warn("WebRTC unavailable, falling back:", err.message);
  // show "call me on my device" UI → POST /voice/click-to-call instead
}
```

> [!WARNING]
>
> WebRTC benötigt eine `getUserMedia`-Freigabe und eine HTTPS-Seite. Ein Softphone, das „nichts tut", ist fast immer eines von drei Dingen: eine HTTP-Seite (nicht sicher), eine abgelehnte Mikrofon-Abfrage oder ein Firmennetzwerk, das UDP 3478 blockiert.

## 5. Verifikation & Fehlerbehebung

**Setup End-to-End prüfen:**

1. Credential ausstellen (Abschnitt 2), Client verbinden (Abschnitt 4) und auf das `connect`- bzw. SIP-`registered`-Ereignis achten.
2. Einen ausgehenden Anruf auf das eigene Mobiltelefon tätigen — Sie sollten Klingeln und dann Zwei-Wege-Audio hören.
3. Einen eingehenden Anruf auf Ihre Nummer routen lassen und bestätigen, dass das Softphone klingelt und annimmt.

**Fehlerbehebung, in der Reihenfolge, in der Sie ihr begegnen:**

| Symptom | Prüfung |
| - | - |
| `403 Organisation does not own phone number …` beim Register | `callerIdNumber` ist keine aktive Nummer in Ihrem Account (eine Eigentumsprüfung, kein Formatfehler). |
| `SERVICE_UNAVAILABLE` / "softphone is not configured" | Der Betreiber hat die SIP-WSS/HMAC-Konfiguration serverseitig nicht gesetzt. |
| Mikrofon-Abfrage erscheint nie | Seite ist kein HTTPS, oder die Abfrage erfolgt beim Seitenlad statt bei einer Nutzeraktion. |
| Register/Connect erfolgreich, Anruf stumm | Firmennetzwerk blockiert UDP/TURN — ICE/TURN-Fallback prüfen. |
| Session stirbt nach ca. 60 min | Das Credential wird bei `expiresAt` nicht neu ausgestellt — auffrischen. |
| Eingehend erreicht das Softphone nicht | Die Nummer ist nicht auf die Queue oder SIP-URI geroutet, auf der das Softphone sitzt — in Abschnitt 3 beheben, nicht im Client. |

## Nächste Schritte

* [SDK demo test-call page](https://docs.orbit.devotel.io/guides/sdk-demo-browser-softphone.md) — einen echten ausgehenden Testanruf aus dem Dashboard tätigen (Developer → SDK Live Demo).
* [SIP trunk setup](https://docs.orbit.devotel.io/guides/sip-trunk-setup.md) — wenn Sie eigene Carrier/Trunks neben dem Browser-Softphone mitbringen wollen.
* [Voice queues](https://docs.orbit.devotel.io/guides/voice-queues.md) — die ACD-Queues, durch die eingehende Anrufe laufen, bevor ein Softphone antwortet.
* [Web SDK](https://docs.orbit.devotel.io/sdks/web.md) — vollständige Event-Map für `Softphone` und die anderen SDK-Flächen.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.