Genel Bakış
Bu dokümantasyon, Voyce Mini SSO (Single Sign-On) ve Voyce Entegrasyon Servisleri için kullanılan API uç noktalarını (endpoint), istek/yanıt yapılarını ve iframe iletişim mekanizmalarını açıklamaktadır.
API Base URL:
https://api.{tenant}.voyce.ccMini Uygulama URL:
https://mini.{tenant}.voyce.ccTüm istekler JSON formatında yapılmalıdır.
Kimlik doğrulama için CtiToken zorunludur.
1. Voyce Mini SSO (Single Sign-On)
Bu servis, harici sistemlerden Voyce Mini uygulamasına otomatik giriş (auto-login) yapılmasını sağlar.
Endpoint
POST https://api.{tenant}.voyce.cc/Auth/v1/SSOHeader’lar
Content-Type: application/json
Request Body
{ "username": "isim.soyisim", "domain": "domain", "ctiToken": "ctiToken" }Alan | Açıklama |
| Kullanıcı adı |
| Domain bilgisi |
| Kimlik doğrulama token’ı |
Response (Başarılı)
{ "acknowledged": true, "token": "JWT_TOKEN_DEGERI" }Alan | Açıklama |
| İşlemin başarılı olup olmadığı |
| JWT (JSON Web Token) |
Örnek cURL İsteği
curl -X POST https://api.{tenant}.voyce.cc/Auth/v1/SSO \ -H "Content-Type: application/json" \ -d '{ "username": "isim.soyisim", "domain": "domain", "ctiToken": "ctiToken" }'2. Otomatik Giriş (Auto Login)
SSO endpoint’inden dönen JWT token, Voyce Mini uygulamasına otomatik giriş yapmak için URL parametresi olarak kullanılır.
Kullanım
https://mini.{tenant}.voyce.cc/?t=JWT_TOKENÖrnek
https://mini.{tenant}.voyce.cc/?t=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Bu URL açıldığında kullanıcı otomatik olarak sisteme giriş yapar.
3. Voyce Entegrasyon Servisleri
Bu servisler, harici uygulamaların Voyce altyapısı ile entegre olmasını sağlar.
Genel Bilgiler
Servis adı: integration-voyce
Tüm isteklerde CtiToken zorunludur
Yanlış veya eksik token durumunda 401 Unauthorized döner
3.1 Click to Call API
Belirli bir kullanıcı adına çağrı başlatmak için kullanılır.
Endpoint
POST /integration-voyce/v1/ClickToCall
Örnek cURL
curl -X POST http://api.{tenant}.voyce.cc/integration-voyce/v1/ClickToCall \ -H "Content-Type: application/json" \ -d '{ "Username": "kullanici_adi", "Domain": "domain", "RemoteNumber": "5555555555", "Queue": "kuyruk_internal_name", "Classification": "siniflandirma", "CtiToken": "ctiToken" }'Açıklama
Bu istek, belirtilen kullanıcı için Click to Call sürecini başlatır.
3.2 Kampanyaları Listeleme API
Endpoint
POST /integration-voyce/v1/Campaign
Örnek cURL
curl -X POST http://api.{tenant}.voyce.cc/integration-voyce/v1/Campaign \ -H "Content-Type: application/json" \ -d '{ "Domain": "domain_adi", "CtiToken": "ctiToken" }'Açıklama
Belirtilen domaine ait tüm kampanyaları listeler.
3.3 Kuyrukları Listeleme API
Endpoint
POST /integration-voyce/v1/Queue
Örnek cURL
curl -X POST http://api.{tenant}.voyce.cc/integration-voyce/v1/Queue \ -H "Content-Type: application/json" \ -d '{ "Domain": "domain_adi", "CtiToken": "ctiToken" }'Açıklama
Belirtilen domaine ait kuyrukları listeler.
3.4 Projeleri Listeleme API
Endpoint
POST /integration-voyce/v1/Project
Örnek cURL
curl -X POST http://api.{tenant}.voyce.cc/integration-voyce/v1/Project \ -H "Content-Type: application/json" \ -d '{ "Domain": "domain_adi", "CtiToken": "ctiToken" }'Açıklama
Belirtilen domaine ait projeleri listeler.
4. Güvenlik Notları
CtiTokenher istekte zorunludurYanlış token → 401 Unauthorized
Tüm veri alışverişi JSON formatında yapılmalıdır
HTTPS kullanılması önerilir
5. Iframe ile Event İletişimi
Voyce Mini uygulaması iframe içerisinde çalıştırıldığında, ana sayfa ile iframe arasında postMessage yöntemi ile iletişim kurulur.
5.1 Iframe’den Ana Sayfaya Event Dinleme
Örnek JavaScript
window.addEventListener('message', function (event) { console.log('Received message:', event.data); if (event.data.event === 'InteractionSentToAgent') { console.log(event.data); } if (event.data.event === 'InteractionSuccessful') { console.log(event.data); } if (event.data.event === 'AgentStatusChange') { console.log(event.data); } if (event.data.event === 'AgentNoAnswerInteraction') { console.log(event.data); } if (event.data.event === 'AgentRejectedInteraction') { console.log(event.data); } });Event Açıklamaları
Event | Açıklama |
| Kuyruktan temsilciye çağrı geldi |
| Çağrı başarıyla tamamlandı |
| Temsilci durumu değişti |
| Çağrı yanıtlanmadı |
| Çağrı reddedildi |
5.2 Ana Sayfadan Iframe’e Event Gönderme
Örnek JavaScript
var voyceIframeWindow = document.getElementById('voyceIframe').contentWindow; var message = { Event: 'ClickToCall', PhoneNumber: phoneNumber }; voyceIframeWindow.postMessage(message, '*');6. Iframe Ses ve Kamera İzinleri
Iframe içerisinden ses veya video akışı yapılacaksa allow özelliği eklenmelidir.
Örnek Iframe Tag’i
<iframe src="https://mini.{tenant}.voyce.cc" allow="microphone; camera" width="200" height="400"> </iframe>İzinler
İzin | Açıklama |
| Mikrofon erişimi |
| Kamera erişimi |
| (Bazı tarayıcılarda) ses çıkışı |
Bu izinler, WebRTC gibi gerçek zamanlı ses/video teknolojilerinin düzgün çalışması için gereklidir.