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

# Configurer le softphone navigateur (WebRTC)

> Offrez à vos agents une surface d'appel complète dans leur navigateur — du softphone intégré au dashboard au client SIP embarqué dans votre propre application — avec contrôle du caller-ID, des identifiants rotatifs et un chemin push mobile pour les appels entrants.

## Note de langue

Cette version française est une traduction abrégée : les sections « 1. Device registration & VoIP push tokens (mobile) » et « 3. Choose how inbound calls reach the softphone » n'existent qu'en anglais : [/en/guides/voice-softphone-browser-calling](https://docs.orbit.devotel.io/en/guides/voice-softphone-browser-calling). Les blocs de code, chemins d'endpoints, noms de champs API et codes d'erreur restent en anglais.

# Configurer le softphone navigateur (WebRTC)

Le softphone navigateur permet à un agent de passer et de recevoir des appels PSTN sans quitter le navigateur — pas de téléphone de bureau, pas d'application SIP desktop. Trois manières de le mettre devant un agent, qui partagent les mêmes identifiants et la même infrastructure :

1. **Le softphone intégré au dashboard** — Orbit livre un softphone prêt à l'emploi dans le dashboard. C'est le chemin sans code et le bon point de départ pour la plupart des équipes.
2. **Un softphone embarqué basé sur LiveKit** (`Softphone` dans `@devotel-orbit/web`) — vous montez le softphone dans votre propre espace agent (CRM, mur de centre de contact, outil interne) avec votre propre UI.
3. **Un softphone SIP-over-WSS embarqué** (le chemin d'enregistrement SIP) — un client SIP classique (par ex. JsSIP) qui s'enregistre directement auprès de la passerelle WebRTC-vers-SIP d'Orbit.

## 2. Émettre les identifiants du softphone

Un navigateur d'agent a besoin d'un identifiant de courte durée avant de pouvoir se connecter. L'endpoint d'émission dépend du client choisi — dashboard, LiveKit embarqué ou SIP embarqué.

### Softphone dashboard intégré / LiveKit embarqué

`POST /voice/softphone/token` rend un jeton d'accès LiveKit de courte durée plus l'URL média de connexion :

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

Le jeton est limité à une salle par utilisateur : deux agents ne partagent jamais une session. Passer un appel une fois connecté, c'est `POST /voice/softphone/dial` avec `{ "to": "+15550123", "from": "+15559876" }`.

### Softphone SIP/WSS embarqué

Un client SIP s'enregistre directement par WebSocket. `POST /voice/softphone/register` échange votre requête API authentifiée contre un identifiant SIP de courte durée :

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

Propriétés clés autour desquelles concevoir :

* Les identifiants vivent **60 minutes** — ré-enregistrez avant `expiresAt` sinon la session tombe.
* `callerIdNumber` doit être un numéro que votre organisation possède (sinon 403) — c'est ainsi que le spoofing de CLI sortant est bloqué.
* Le nom d'utilisateur est lié à votre organisation : un nom volé ne peut pas être rejoué contre un autre tenant.
* L'émission de jetons est limitée à **owner/admin/developer** — pas d'endpoint public anonyme.

> [!NOTE]
>
> Révoquez un identifiant immédiatement avec `DELETE /voice/softphone/credentials/:username` si un agent part ou si un jeton fuite.

## 4. Extrait JS complet — micro, push VoIP + repli navigateur

Voici un softphone navigateur complet, à copier-coller. Il fonctionne avec les deux options embarquées (LiveKit et SIP-over-WSS) et traite la réalité du repli navigateur :

```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 exige une autorisation `getUserMedia` et une page HTTPS. Un softphone qui « ne fait rien » est presque toujours l'un des trois : une page HTTP (non sécurisée), une invite micro refusée, ou un réseau d'entreprise qui bloque UDP 3478.

## 5. Vérification & dépannage

**Vérifier le setup de bout en bout :**

1. Émettez un identifiant (section 2), connectez le client (section 4) et guettez l'événement `connect` ou SIP `registered`.
2. Passez un appel sortant vers votre propre mobile — vous devriez entendre la sonnerie puis un audio bidirectionnel.
3. Faites router un appel entrant vers votre numéro et confirmez que le softphone sonne et répond.

**Règles de dépannage, dans l'ordre où vous les rencontrerez :**

| Symptôme | Vérification |
| - | - |
| `403 Organisation does not own phone number …` au register | `callerIdNumber` n'est pas un numéro actif de votre compte (c'est une porte de propriété, pas un bug de format). |
| `SERVICE_UNAVAILABLE` / "softphone is not configured" | L'opérateur n'a pas posé la config SIP WSS/HMAC côté serveur. |
| L'invite micro n'apparaît jamais | La page n'est pas en HTTPS, ou la demande est faite au chargement plutôt que sur un geste utilisateur. |
| Register/connect réussit, appel muet | Réseau d'entreprise bloquant UDP/TURN — vérifiez le chemin ICE. |
| La session meurt après \~60 min | L'identifiant n'est pas ré-émis à `expiresAt` — rafraîchissez-le. |
| L'entrant n'atteint pas le softphone | Le numéro n'est pas routé vers la file ou la SIP URI où siège le softphone — corrigez en section 3, pas dans le client. |

## Où aller ensuite

* [SDK demo test-call page](https://docs.orbit.devotel.io/guides/sdk-demo-browser-softphone.md) — passez un vrai appel sortant de test depuis le dashboard (Developer → SDK Live Demo).
* [SIP trunk setup](https://docs.orbit.devotel.io/guides/sip-trunk-setup.md) — si vous voulez apporter votre propre carrier/trunk à côté du softphone navigateur.
* [Voice queues](https://docs.orbit.devotel.io/guides/voice-queues.md) — les files ACD par lesquelles passent les appels entrants avant qu'un softphone réponde.
* [Web SDK](https://docs.orbit.devotel.io/sdks/web.md) — la carte complète des événements de `Softphone` et des autres surfaces SDK.


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