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:

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

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:

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.

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:

curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/token \
  -H "Authorization: Bearer YOUR_API_KEY"

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

{
  "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:

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ış):

{
  "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.

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.

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.

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’a bakın.

5. Doğrulama ve sorun giderme

Kurulumu uçtan uca doğrulayın:

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.
Kendi cep telefonunuza giden bir çağrı başlatın — çalma sesi, ardından yanıtta çift yönlü ses duymalısınız.
Numaranıza bir gelen çağrı yönlendirin (bölüm 3) ve softphone’un çalıp yanıtladığını doğrulayın.
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 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 — 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 — 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 — tarayıcı softphone’unun yanına kendi taşıyıcınızı/trunk’ınızı getirmek istiyorsanız.
Voice queues — gelen çağrıların softphone yanıtlamadan önce geçtiği ACD kuyruğu.
Web SDK — Softphone ve diğer SDK yüzeyleri için tam olay haritası.
Agent first-week onboarding — softphone’u yeni bir temsilcinin ilk haftasına yerleştiren yolculuk (yerelleştirilmiş varyantı yayınlanana dek İngilizce kaynaktan).

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

Tarayıcı (WebRTC) softphone'unu kurun

Tarayıcı (WebRTC) softphone’unu kurun

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

2. Softphone kimlik bilgisi üretin

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

Gömülü SIP/WSS softphone

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

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

5. Doğrulama ve sorun giderme

Bundan sonra nereye

​Tarayıcı (WebRTC) softphone’unu kurun

​1. Cihaz kaydı ve VoIP push token’ları (mobil)

​2. Softphone kimlik bilgisi üretin

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

​Gömülü SIP/WSS softphone

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

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

​5. Doğrulama ve sorun giderme

​Bundan sonra nereye

Tarayıcı (WebRTC) softphone’unu kurun

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

2. Softphone kimlik bilgisi üretin

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

Gömülü SIP/WSS softphone

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

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

5. Doğrulama ve sorun giderme

Bundan sonra nereye