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

# Tarayıcı (WebRTC) softphone'unu kurun

> Temsilcilerinize tarayıcının içinde eksiksiz bir çağrı yüzeyi verin — panonun yerleşik softphone'undan kendi uygulamanıza gömülü bir SIP istemcisine — arayan kimliği kontrolü, döndürülebilir kimlik bilgileri ve gelen çaldırmalar için mobil push yoluyla.

# Tarayıcı (WebRTC) softphone'unu kurun

Tarayıcı softphone'u, bir temsilcinin PSTN çağrılarını tarayıcıdan ayrılmadan yapmasını ve yanıtlamasını sağlar — masa telefonu yok, masaüstü SIP uygulaması yok. Bunu bir temsilcinin önüne koymanın üç yolu vardır ve altta aynı kimlik bilgisiyle aynı altyapıyı paylaşırlar:

1. **Yerleşik pano softphone'u** — Orbit, pano içinde hazır bir softphone sunar. Bu, sıfır kodlu yoldur ve çoğu ekip için doğru başlangıç noktasıdır.
2. **Gömülü LiveKit tabanlı softphone** (`@devotel-orbit/web` içinde `Softphone`) — softphone'u kendi ajan çalışma alanınıza (CRM, çağrı merkezi duvarı, iç araç) kendi arayüzünüzle monte edersiniz.
3. **Gömülü SIP-over-WSS softphone** (SIP-register yolu) — Orbit'in WebRTC'den-SIP ağ geçidine doğrudan register olan klasik bir SIP istemcisi (örn. JsSIP); standart SIP semantiği ve kendi çağrı kontrol mantığını isteyen ekipler için.

Bu rehber, kurulumu gerçekte yapacağınız sırayla anlatır: cihazları kaydedin, kimlik bilgisi üretin, gelen çağrıların softphone'u nasıl bulacağını seçin, bir istemci bağlayın, sonra doğrulayın.

> [!NOTE]
>
> Tarayıcı softphone'u yalnızca mikrofonlu bir tarayıcıya ihtiyaç duyar. Gelen push bildirimleri (bölüm 1), temsilciler Orbit mobil uygulamasına geçtiğinde devreye giren bir mobil eşlikçidir — tarayıcının kendisi için gerekli değildir.

## 1. Cihaz kaydı ve VoIP push token'ları (mobil)

Temsilcileriniz yalnızca tarayıcıda çalışıyorsa bu bölümü atlayın. Bir **VoIP cihazını** yalnızca, temsilcinin gelen çağrıları telefonunda yerel bir çağrı olarak çaldırması gerektiğinde kaydedin — yani Orbit mobil uygulaması, arka plana alınmış veya kilitliyken bile pasif bir banner göstermek yerine bir telefon çağrısı gibi çalsın.

Bir VoIP cihazı kaydetmek tek bir API çağrısıdır:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/push/voip-devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "voip_token": "APNS_VOIP_TOKEN_HEX",
    "bundle_id": "com.yourcompany.orbit-agent"
  }'
```

* `platform`, `ios` veya `android`'dir. iOS'ta `voip_token` PushKit (CallKit) token'ıdır; Android'de yüksek öncelikli çağrı kanalı için kullanılan FCM kayıt token'ıdır.
* `bundle_id` (yalnızca iOS) uygulama paket kimliğidir — VoIP push konusu `<bundle_id>.voip`'tir.
* Yanıt, kayıtlı cihazı döndürür (`id`, `platform`, `last_seen_at`).

Filoyu `GET /push/voip-devices` (listeleme) ve `DELETE /push/voip-devices/:id` (cihaz kaydını kaldırma) ile yönetin. Bunları normalde elle çağırmazsınız — mobil SDK kendi satırını kaydeder, tazeler ve kaldırır. Kalıcı olarak ölü bir token (işletim sistemi iptal etti veya uygulama kaldırıldı) otomatik olarak revoked işaretlenir ve sonraki gelen çaldırmada atlanır; böylece bayat bir cihaz asla kuyruğun çaldırma döngüsünü tıkamaz.

> [!WARNING]
>
> VoIP token'ı, normal bir push token'ıyla **aynı** değildir. iOS, VoIP yetkisini pazarlama veya uyarı push'ları için yeniden kullanan uygulamalardan geri alır; bu yüzden iki token türü kesinlikle ayrık tutulur. Bir `voip_token`'a asla çağrı dışı push göndermeyin.

## 2. Softphone kimlik bilgisi üretin

Temsilcinin tarayıcısı, bağlanabilmeden önce kısa ömürlü bir kimlik bilgisine ihtiyaç duyar. Hangi uç noktaya üreteceğiniz, seçtiğiniz istemciye bağlıdır — pano, gömülü LiveKit veya gömülü SIP.

### Yerleşik pano / gömülü LiveKit softphone

Softphone'un ilk adımı bir token isteğidir. `POST /voice/softphone/token`, kısa ömürlü bir LiveKit erişim token'ı ve bağlanılacak medya URL'sini döndürür:

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

Yanıt (kısaltılmış):

```json theme={null}
{
  "data": {
    "token": "<livekit access token>",
    "media_url": "wss://..."
  }
}
```

Token, kullanıcı başına bir odaya kapsamlanır; böylece iki temsilci asla bir oturumu paylaşmaz. Bağlandıktan sonra çağrı başlatma `{ "to": "+15550123", "from": "+15559876" }` ile `POST /voice/softphone/dial`'dır — tam parça için bölüm 4'e bakın.

### Gömülü SIP/WSS softphone

Bir SIP istemcisi doğrudan WebSocket üzerinden register olur. `POST /voice/softphone/register`, kimliği doğrulanmış API isteğinizi kısa ömürlü bir SIP kimlik bilgisiyle değiştirir:

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

Yanıt (kısaltılmış):

```json theme={null}
{
  "data": {
    "sipUsername": "u_agent_x1a2b3",
    "sipPassword": "...",
    "sipDomain": "sip.orbit.devotel.io",
    "wssUrl": "wss://...",
    "iceServers": [{ "urls": "stun:..." }],
    "callerIdNumber": "+15559876",
    "expiresAt": 1716110400000
  }
}
```

Tasarımınızı üzerine kuracağınız temel özellikler:

* Kimlik bilgileri **60 dakika** yaşar — `expiresAt`'den önce yeniden register olun, yoksa oturum düşer.
* `callerIdNumber`, organizasyonunuzun sahip olduğu bir numara olmalıdır (aksi halde 403) — giden CLI sahteciliği bu şekilde engellenir.
* Kullanıcı adı organizasyonunuza bağlanır; böylece çalınan bir kullanıcı adı başka bir tenant'a karşı yeniden oynatılamaz.
* Token üretimi **owner/admin/developer** kapsamlıdır — herkese açık, anonim bir uç nokta değildir.

> [!NOTE]
>
> Bir temsilci ayrıldığında veya bir token sızdığında kimlik bilgisini `DELETE /voice/softphone/credentials/:username` ile derhal iptal edin. İptal yalnızca owner tarafından yapılabilir; böylece sızmış bir kimlik bilgisi küçük etki alanlı bir olay olarak kalır.

## 3. Gelen çağrıların softphone'a nasıl ulaşacağını seçin

Gelen çağrılar, bir temsilcinin tarayıcısına düşecek şekilde yönlendirilmelidir. Üç tenant sahipliği seçeneğiniz vardır — telefon numaralarınızın kurulumuna uyanı kullanın.

* **DNIS → kuyruk → softphone.** En yaygın yol: telefon numaranızın gelen yönlendirmesi çağrıyı bir ACD kuyruğuna gönderir, kuyruk ise bunu müsait bir temsilcinin tarayıcı softphone'una önerir (ve mobil uygulamadaysalar bir VoIP push — bölüm 1). Bunu panonun numara yönlendirmesinde numara başına veya flows oluşturucu üzerinden kurarsınız.
* **DNIS → SIP yönlendirme.** Gelen çağrıları, softphone kayıtlarınızın yaşadığı SIP alanına yönlendirin. Gelen trafiğiniz zaten SIP'e düşüyorsa (örneğin SIP URI'nize iletilen bir DID) ve kayıtlı softphone'un doğrudan yanıtlamasını istiyorsanız bunu kullanın.
* **Arayanın softphone'u dışarı arar.** Giden odaklı ekiplerde gelen sorunu hiç doğmaz — temsilci çağrıları başlatır ve gelen yanıt, bir kuyruğa yönlendirilmiş bir numaradadır (birinci seçeneğe dönüş).

Hangisini seçerseniz seçin, softphone'un kendi kimlik bilgisi asla değişmez — bölümler 1, 2 ve 4 her gelen topolojisinde özdeştir. Gelen yönlendirme, softphone'un değil *numaranın* bir özelliğidir.

## 4. Tam JS parçası — mikrofon, VoIP push + tarayıcı yedeği

İşte eksiksiz, kopyala-yapıştır bir tarayıcı softphone'u. Her iki gömülü seçenekle de çalışır (LiveKit ve SIP-over-WSS) ve tarayıcı yedeği gerçeğini ele alır: bazı temsilciler, birincil medya yolunun kullanılamadığı tarayıcılarda veya ağlarda olacaktır; bu yüzden her zaman bir yedek bağlarsınız.

```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
  // Optional: force a media URL. Omit to use the token response.
  // mediaUrl: "wss://...",
  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 — so the permission prompt is
//    attributed and the mic isn't held open on an idle tab.
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 (the caller's desk phone or mobile
//    rings, and the agent talks there). This is also the path when an
//    enterprise network blocks WebRTC entirely.
function handleSoftphoneFailure(err) {
  console.warn("WebRTC unavailable, falling back:", err.message);
  // show "call me on my device" UI → POST /voice/click-to-call instead
}

// VoIP push (mobile only): the browser cannot receive a VoIP push -
// mobile handles it natively. From the browser, the inbound ring just
// arrives when an inbound call is routed to the agent's room.
```

> [!WARNING]
>
> WebRTC bir `getUserMedia` izni ve bir HTTPS sayfası gerektirir. "Hiçbir şey yapmayan" bir softphone neredeyse her zaman şunlardan biridir: HTTP (güvenli olmayan) bir sayfa, reddedilmiş mikrofon istemi veya UDP 3478'i (ya da TCP 5349 TLS relay) engelleyen bir kurumsal ağ. Kurumsal bir güvenlik duvarının ihtiyaç duyduğu izin listesi için [Browser softphone network requirements](https://docs.orbit.devotel.io/voice/network-requirements.md)'a bakın.

## 5. Doğrulama ve sorun giderme

**Kurulumu uçtan uca doğrulayın:**

1. Bir kimlik bilgisi üretin (bölüm 2), istemciyi bağlayın (bölüm 4) ve bir oda `connect` / SIP `registered` olayı arayın.
2. Kendi cep telefonunuza giden bir çağrı başlatın — çalma sesi, ardından yanıtta çift yönlü ses duymalısınız.
3. Numaranıza bir gelen çağrı yönlendirin (bölüm 3) ve softphone'un çalıp yanıtladığını doğrulayın.
4. Bir mobil VoIP cihazı kaydettiyseniz (bölüm 1), mobil uygulamayı arka plana alın ve yerel bir gelen çağrı arayüzünün göründüğünü doğrulayın.

**Sorun giderme kuralları, karşılaşacağınız sırayla:**

| Belirti | Denetlenecek |
| - | - |
| Register'da `403 Organisation does not own phone number …` | `callerIdNumber`, hesabınızda aktif bir numara değildir (bu bir sahiplik kapısıdır, biçimlendirme hatası değil). |
| `SERVICE_UNAVAILABLE` / "softphone is not configured" | Operatör SIP WSS/HMAC yapılandırmasını sunucu tarafında kurmamış — tarayıcı ilerleyemez. |
| Mikrofon istemi hiç görünmüyor | Sayfa HTTPS değil ya da kullanıcı hareketi yerine sayfa yüklenmesinde istiyorsunuz. |
| Register/bağlanma başarılı, çağrı sessiz | Kurumsal ağ UDP/TURN'ü engelledi — [network requirements sayfasında](https://docs.orbit.devotel.io/voice/network-requirements.md) relay ana makinelerini ve portları ile proxy istisnalarını doğrulayın. |
| Oturum \~60 dk sonra ölüyor | Kimlik bilgisi `expiresAt`'de yeniden üretilmiyor — tazeleyin. |
| Mobil çalıyor ama tarayıcı çalmıyor (veya tersi) | İkisinin aynı anda çalması beklenir — bu paralel çaldırmadır, bir arıza değil. |
| Gelen çağrı softphone'a ulaşmıyor | Numara, softphone'un oturduğu kuyruğa veya SIP URI'ye yönlendirilmemiş — istemcide değil, bölüm 3'te düzeltin. |

Ayrıca yanlış uç noktayı yeniden kullanmadığınızı da doğrulayın: register (SIP/WSS) ↔ SIP istemcileri, token ↔ LiveKit istemcileri, `voip-devices` ↔ yalnızca mobil push.

## Bundan sonra nereye

* [Browser softphone network requirements](https://docs.orbit.devotel.io/voice/network-requirements.md) —
  kurumsal bir güvenlik duvarında veya VPN'de tarayıcı aramalarına izin vermek
  için portlar, ana makineler ve proxy kontrol listesi.
* [SDK demo test-call page](https://docs.orbit.devotel.io/guides/sdk-demo-browser-softphone.md) —
  panodan gerçek bir giden test çağrısı başlatın (Developer → SDK Live Demo)
  ve bu kurulumu uçtan uca sağlama alın.
* [SIP trunk setup](https://docs.orbit.devotel.io/guides/sip-trunk-setup.md) — tarayıcı softphone'unun
  yanına kendi taşıyıcınızı/trunk'ınızı getirmek istiyorsanız.
* [Voice queues](https://docs.orbit.devotel.io/guides/voice-queues.md) — gelen çağrıların softphone
  yanıtlamadan önce geçtiği ACD kuyruğu.
* [Web SDK](https://docs.orbit.devotel.io/sdks/web.md) — `Softphone` ve diğer SDK yüzeyleri için tam olay haritası.
* [Agent first-week onboarding](https://docs.orbit.devotel.io/guides/agent-first-week-onboarding-journey.md) —
  softphone'u yeni bir temsilcinin ilk haftasına yerleştiren yolculuk
  (yerelleştirilmiş varyantı yayınlanana dek İngilizce kaynaktan).


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