3CX Programlanabilir Dahilileriyle Kendi AI Ses Uygulamanızı Yapın

Call Control API’si, Call Control SDK’sı ve desteklenen bir gerçek zamanlı yapay zeka sağlayıcısı kullanarak, harici bir sunucuda barındırılan bir AI ses uygulamasını 3CX’e bağlayın.

Giriş

3CX Programlanabilir Dahililer, harici olarak barındırılan bir uygulamanın PBX’e bağlanmasına ve yerel bir dahili hat gibi çalışmasına olanak tanır. Uygulama, aramaları alabilir, her iki yönde ses akışı sağlayabilir ve 3CX Çağrı Kontrol API’si aracılığıyla çağrı yönlendirmesini kontrol edebilir.

Agentic Çağrı Kontrol örnekleri, aşağıdakiler için çalışır durumda Node.js uygulamaları sunar:

  • OpenAI Realtime
  • Google Gemini Live
  • xAI Grok Voice Agent
  • Alibaba Cloud Qwen Omni Realtime

Her örnek, tek bir çift yönlü gerçek zamanlı ses oturumu kullanır. Konuşma tanıma, akıl yürütme ve konuşma üretimi, seçilen AI sağlayıcısı tarafından gerçekleştirilirken, 3CX ise telefon hizmetleri, çağrı yönlendirme, dahili numaralar, SIP trunkları ve DID'leri sağlamaya devam eder.

Örnekler, yayınlanmış 3CX API'leri aracılığıyla bağlanır ve PBX kaynak kodunda herhangi bir değişiklik gerektirmez. Ayrıca 3CX MCP uç noktasına da bağlanırlar; böylece ses uygulaması, telefon rehberi araması gibi yetkili PBX araçlarını kullanabilir. Takvimler, CRM'ler ve diğer iş sistemleri için isteğe bağlı harici MCP sunucuları eklenebilir.

Hangi seçeneği kullanmalıyım?

Bu kılavuz, uygulamanın 3CX dışında, sizin yönettiğiniz altyapı üzerinde çalıştığı Programlanabilir Dahilileri kapsamaktadır. Yapılandırmaya hazır bir çözüm için yerleşik 3CX AI Temsilcilerini kullanın. Doğrudan 3CX Sunucusu üzerinde çalışan özel uygulamalar için AI Çağrı Komut Dosyalarını kullanın.

Ne Yapıyor Olacaksınız

Bu kılavuzun sonunda, aşağıdakileri yapabilen bir harici AI ses uygulamasına sahip olacaksınız:

  • 3CX İstemci Kimliği aracılığıyla dahili aramaları alma.
  • Atanmış bir DID aracılığıyla harici aramaları alma.
  • Seçtiğiniz AI sağlayıcısını kullanarak gerçek zamanlı sesli görüşme yapma.
  • MCP aracılığıyla 3CX telefon rehberinde arama yapma.
  • 3CX Çağrı Kontrolü aracılığıyla bir aramayı aktarma, sesli mesaja yönlendirme veya sonlandırma.
  • Ek MCP sunucularına bağlanma ve seçilen araçları modele sunma.

Sağlanan temsilci profili, temel bir resepsiyonist akışını uygular. Bu profil bir başlangıç noktası olarak tasarlanmıştır ve randevu rezervasyonu, müşteri bilgileri, anketler, dahili yardım masaları ve diğer iş akışları için genişletilebilir.

Başlamadan Önce

Şunlara ihtiyacınız var:

  • Call Control API erişimine sahip bir 3CX V20 Güncelleme 10 sistemi.
  • API Hizmet Sorumlusu oluşturmak için yönetici erişimi.
  • Uygulamayı barındıracak bilgisayar veya sunucuda Node.js 20 veya daha yeni bir sürüm.
  • Depo ile birlikte gelen Yarn sürümü.
  • En az bir desteklenen AI sağlayıcısı için bir API anahtarı ve kullanılabilir kota.
  • Uygulama sunucusundan 3CX HTTPS FQDN'sine ve seçilen sağlayıcının WebSocket uç noktalarına ağ erişimi.

Adım 1: Örnekleri İndirin

Agentic Call Control deposunu kopyalayın veya indirin: Agentic Call Control deposunu açın

Bir terminalden, deponun kök dizinine geçin ve tüm çalışma alanı bağımlılıklarını yükleyin:

yarn install

“yarn” komutu mevcut değilse, önce Corepack'i etkinleştirin:

corepack enable

yarn install

Yarn’ı her sağlayıcı dizinine ayrı ayrı yüklemeyin. Depo, bir Yarn çalışma alanıdır ve kök dizininden yüklenmelidir.

Adım 2: Bir 3CX Hizmet İlkesi Oluşturun

Harici uygulamanın PBX ile kimlik doğrulaması yapmak için kullanacağı kimlik bilgilerini oluşturun.

  • 3CX Web İstemcisi’ne giriş yapın ve Yönetici’yi açın.
  • Entegrasyonlar > API’yegidin.
  • Hizmet İlkesi oluşturmak için Ekle’ye tıklayın.
  • Bir İstemci Kimliği girin; örneğin, ai-receptionist. Bu, uygulamanın appId’si ve kullanıcıların uygulamayı aramak için arayabilecekleri dahili olacaktır.
  • Uygulama için 3CX Çağrı Kontrol API erişimini etkinleştirin.
  • İsteğe bağlı olarak, harici arayanların uygulamaya doğrudan ulaşabilmesi gerekiyorsa bir DID atayın.
  • İsteğe bağlı olarak, uygulamanın izleyebileceği veya kontrol edebileceği dahili numaraları seçin. Yalnızca amaçlanan iş akışının gerektirdiği erişimi verin.
  • Hizmet İlkesi'ni kaydedin.
  • Oluşturulan API anahtarını veya İstemci Gizli Anahtarını hemen kopyalayın. Bu, appSecret olarak kullanılır ve yalnızca bir kez görüntülenir.
  • Create the credentials the external application will use to authenticate with the PBX.

Adım 3: Bir AI Sağlayıcı Seçin

Birlikte verilen örneklerden birini kullanın.

Sağlayıcı

Örnek klasörü

Sağlayıcı kimlik bilgileri

Başlama komutu

OpenAI Realtime

examples/openai-realtime

openaiApiKey

yarn start:openai

Google Gemini Live

examples/gemini-realtime

geminiApiKey

yarn start:gemini

xAI Grok Voice Agent

examples/xai-realtime

xaiApiKey

yarn start:xai

Alibaba Qwen Omni Realtime

examples/alibaba-qwen-realtime

dashscopeApiKey

yarn start:alibaba-qwen

Seçilen sağlayıcının konsolunda API anahtarını oluşturun ve güvenli bir şekilde kaydedin:

Güncel model kullanılabilirliği, sesler, bölgeler, fiyatlandırma ve hız sınırları hakkında bilgi için, seçilen sağlayıcının belgelerine ve ilgili örnek dizinindeki README dosyasına bakın.

Qwen bölgesi ile ilgili not: DashScope kimlik bilgileri ve uç noktaları bölgeye özeldir. API anahtarının oluşturulduğu bölge ve çalışma alanı için gerekli olan uç noktasını kullanın.

Adım 4: Sağlayıcı Yapılandırması Oluşturun

config.yaml.example dosyasını, seçilen örnek dizindeki config.yaml dosyasına kopyalayın.

OpenAI

cp examples/openai-realtime/config.yaml.example examples/openai-realtime/config.yaml

Gemini

cp examples/gemini-realtime/config.yaml.example examples/gemini-realtime/config.yaml

xAI

cp examples/xai-realtime/config.yaml.example examples/xai-realtime/config.yaml

Alibaba Qwen

cp examples/alibaba-qwen-realtime/config.yaml.example examples/alibaba-qwen-realtime/config.yaml

Windows PowerShell'de, cp komutu yerine Copy-Item komutunu kullanın.

Yeni config.yaml dosyasını açın ve 3CX için ortak değerleri girin:

appId: ai-receptionist

appSecret: your-3cx-api-key

pbxBase: https://your-pbx.example.com

companyName: Your Company

agentName: Assistant

initialGreeting: Thank you for calling. How can I help you today?

Seçilen örnekte belirtilen agentProfile değerini koruyun. OpenAI, Gemini ve xAI “receptionist” değerini kullanır; Qwen ise ayrı İngilizce ve Çince profilleri içerir.

Ardından, seçilen sağlayıcı için kimlik bilgilerini ayarlayın. Örneğin, OpenAI yapılandırması şunları içerir:

openaiApiKey: sk-your-openai-api-key

Model, ses, ses etkinliği algılama ve sağlayıcıya özgü ayarlar için sağlayıcının sağladığı config.yaml.example dosyasını referans kaynağı olarak kullanın. Qwen için, sağlayıcının bölgeye özgü temel URL yapılandırmasını koruyun.

Güvenlik: config.yaml dosyası gizli bilgileri içerir. Bu dosya, sağlanan .gitignore dosyası tarafından hariç tutulmuştur; ancak yine de bu dosyayı paylaşmaktan, kaydetmekten veya destek günlüklerine eklemekten kaçınmalısınız. Üretim ortamında bir gizli bilgi yöneticisi veya ortama dayalı uygulama yöntemi kullanın.

Adım 5: Uygulamayı Başlatın

Deponun kök dizininden seçilen sağlayıcıya ait komutu çalıştırın.

OpenAI

yarn start:openai

Gemini

yarn start:gemini

xAI

yarn start:xai

Alibaba Qwen

yarn start:alibaba-qwen

Başlangıçtaki tam çıktı, sağlayıcıya göre değişiklik gösterir. Başarılı bir başlatma işlemi şunları doğrulamalıdır:

  • Uygulama, 3CX ile kimlik doğrulamasını tamamlamıştır.
  • Çağrı Kontrol SDK’sı ve WebSocket bağlantısı aktiftir.
  • Uygulama, 3CX MCP uç noktasına bağlanmıştır.
  • Etkinleştirilmiş MCP araçları yüklenmiştir.
  • Çağrı işleyicisi başlatılmıştır ve uygulama çağrıları kabul etmeye hazırdır.

Adım 6: Arayın ve Uygulamayı Test Edin

Dahili Bir Arama Yapın

Kayıtlı bir 3CX dahilisinden appId olarak yapılandırılmış Hizmet İlkesi İstemci Kimliğini arayın.

Örneğin, İstemci Kimliği ai-receptionist ise, 3CX Web İstemcisi, masaüstü uygulaması, mobil uygulama veya yapılandırılmış bir telefondan ai-receptionist'i tuşlayın.

Harici Bir arama Yapın

Servis İlkesine bir DID atadıysanız harici bir telefondan o numarayı arayın.

Önerilen Testler

Özelleştirmeden önce iş akışının tamamnı test edint:

  • Temsilcinin, yapılandırılan karşılama mesajıyla yanıt verdiğini doğrulayın.
  • Telefon rehberinde kayıtlı bir kişiyle görüşmek istediğinizi belirtin.
  • Temsilcinin MCP aracılığıyla telefon rehberinde arama yaptığını doğrulayın.
  • Başarılı bir aktarım işlemini test edin.
  • Kullanıcının ulaşılamaması ve sesli mesaj yolunu test edin.
  • Temsilci konuşurken sözünü keserek araya girme davranışını doğrulayın.
  • Aramayı sonlandırın ve uygulamanın aramayı doğru şekilde sonlandırdığını doğrulayın.

Ctrl+C ile uygulamayı durdurun..

Temsilciyi Özelleştirin

Şirket adı ve temsilci adı gibi temel ayarlar config.yaml dosyasında saklanır.

Daha ayrıntılı davranışlar, seçilen örneğin temsilciler dizinindeki YAML profiliyle tanımlanır. Sağlayıcı örneğine bağlı olarak, varsayılan profilin adı receptionist.yaml, receptionist_en.yaml veya receptionist_cn.yaml şeklindedir.

Profil, aşağıdaki gibi alanları kontrol eder:

  • Rol ve sistem komut istemi.
  • Selamlamalar ve dil davranışları.
  • Çağrı filtreleme gereksinimleri.
  • Aktarım öncesi ulaşılabilirlik kontrolleri.
  • İzin verilen çağrı eylemleri.
  • Engellenen dahili numaralar.
  • Spam, düşmanca davranış ve işbirliği yapmayan arayanlara yönelik politikalar.
  • Modele sunulan MCP araçları.

config.yaml dosyasını veya seçilen temsilci profilini değiştirdikten sonra uygulamayı yeniden başlatın.

Komut istemlerini ve araç izinlerini uyumlu tutun. Modele bir eylemi gerçekleştirebileceğini söylemek, altta yatan uygulamaya veya Hizmet İlkesi'ne bu eylemi gerçekleştirme izni vermez.

Basic settings such as the company name and agent name are stored in config.yaml.

3CX MCP Araçlarını Kullanın

Başlangıçta, örnekler 3CX MCP uç noktasına bağlanır ve kimlik doğrulaması yapılmış Hizmet İlkesi için kullanılabilir araçları belirler.

Yalnızca temsilci profilinin mcpTools izin listesinde yer alan araçlar AI modeline sunulur. Varsayılan resepsiyonist profili, telefon rehberinde arama yapmayı etkinleştirir:

mcpTools:

  - list_phonebook

Başlatma günlüğü, sunucudan tespit edilen araçları ve her birinin etkin olup olmadığını gösterir. Yetkilendirilmiş başka bir aracı kullanıma açmak için, aracın tam adını mcpTools dosyasına ekleyin ve uygulamayı yeniden başlatın.

Listeyi, iş akışının gerektirdiği en az sayıda araçla sınırlayın. Modele açılmamış bir araç, model tarafından çağrılamaz.

İlave MCP Sunucular Bağlayın

İsteğe bağlı MCP sunucuları, config.yaml dosyasındaki customMcpServers altında yapılandırılabilir. Bu, ses uygulamasına onaylanmış takvim, CRM veya iş süreci araçlarına erişim imkanı sağlayabilir.

Örnekler, test sırasında kolaylık sağlamak amacıyla auth.type: bearer veya auth.type: none seçeneklerini destekler. Kendi MCP sunucunuzu çalıştırmadan hızlı bir deneme yapmak için Smithery gibi barındırılan bir bağlayıcı kullanın: uzak URL'yi ve bearer jetonunu customMcpServers'a yapıştırın, ardından mcpTools'da bulunan araç adlarını etkinleştirin.

customMcpServers:

  - name: GoogleCalendar

    url: https://mcp.example.com/your-server

    auth:

      type: bearer

      token: your-mcp-bearer-token

    enabled: true

Temsilci profiline eklemek istediğiniz her bir aracı, tam adıyla belirtin:

mcpTools:

  - list_phonebook

  - googlecalendar.quick_add

Özel MCP sunucularında keşfedilen araçla, mevcut 3CX MCP araçlarıyla birleştirilir; ancak modelin hangi araçları kullanabileceğini belirleyen, profil izin listesidir.

HArici MSP sunucuları eklerken:

  • En düşük ayrıcalıklı kimlik bilgilerini kullanın.
  • Yalnızca gerekli araçları kullanıma açın.
  • Araç parametrelerini sunucu tarafında doğrulayın.
  • Uygun olduğu durumlarda, hassas veya geri alınamaz işlemler için onay gerektirin.
  • Uzun süre geçerli olan üretim sırlarını doğrudan kaynak kontrolüne eklemeyin.

Resepsiyonist Örneğinin Ötesine Geçin

Dahil edilen resepsiyonist mantığı, telefon rehberi araması, çağrı aktarma, sesli mesaj ve çağrı sonlandırma işlevlerini göstermektedir. Aynı mimari, aşağıdaki gibi iş akışlarını destekleyecek şekilde genişletilebilir:

  • Randevu planlama.
  • Müşteri veya hesap bilgilerinin aranması.
  • Otomatik anketler.
  • Şirket içi BT veya İK yardım masaları.
  • CRM desteği oluşturma ve güncelleme.
  • Sipariş durumu veya teslimat bilgisi hizmetleri.
  • Özel iş uygulamaları için sesli arayüzler.

Uygulama, iş mantığı, doğrulama, hata yönetimi ve araç güvenliğinden sorumlu olmaya devam eder. 3CX, çağrı bağlantısı, ses akışı ve çağrı kontrol işlevlerini sağlarken, seçilen yapay zeka sağlayıcısı gerçek zamanlı konuşmayı yönetir.

Üretim Kontrol Listesi

Özel bir uygulamayı testin ötesine geçirmeden önce:

  • Otomatik yeniden başlatma ve durum izleme özellikleriyle yönetilen bir hizmet olarak çalıştırın.
  • API kimlik bilgilerini bir gizli anahtar yöneticisiyle koruyun ve bunları düzenli aralıklarla değiştirin.
  • Hizmet İlkesi'ni gerekli dahililer ve işlevlerle sınırlandırın.
  • AI sağlayıcısının veri işleme, saklama ve bölgesel kullanılabilirlik politikalarını inceleyin.
  • Kayıt, transkripsiyon veya AI bilgilerinin ifşası gerektiğinde arayanları bilgilendirin ve onaylarını alın.
  • Sağlayıcı kullanımını, hız sınırlarını ve maliyetleri izleyin.
  • Zaman aşımı süreleri, yeniden deneme işleme ve AI dışı yedek yol ekleyin.
  • Gerçekçi arama koşulları altında aktarma, sesli mesaj, hata ve bağlantı kesilme yollarını test edin.
  • Etkinleştirilmiş her MCP aracını inceleyin ve hassas işlemleri ek doğrulama veya onay ile koruyun.

Sorun Giderme

yarn Tanınmıyor

Node.js 20 ve sonrasının kurulu olduğundan emin olun, sonra Corepack’i etkinleştirin:

corepack enable

Deponun kök dizininden yarn install komutunu tekrar çalıştırın.

PBX Kimlik Doğrulama 401 ya da  403 Hata Kodu Veriyor

appId, appSecret ve pbxBase değerlerinin Hizmet İlkesi ile uyumlu olup olmadığını kontrol edin. Çağrı Kontrol API erişiminin etkinleştirildiğini ve 3CX lisansının ile izinlerinin istenen işlemi desteklediğini doğrulayın.

Uygulama Başlıyor fakat Çağrı Almıyor

Uygulamanın hâlâ çalışır durumda olduğunu doğrulayın, doğru İstemci Kimliğini arayın ve harici aramaları test ederken DID’nin Hizmet İlkesi’ne atandığını kontrol edin.

Bir MCP Aracı Devredışı Bırakılmış Görünüyor

Başlangıç günlüğünde gösterilen araç adını aynen profilin mcpTools listesine kopyalayın, ardından uygulamayı yeniden başlatın. Ayrıca, Hizmet İlkesi'nin aracı kullanma yetkisine sahip olduğunu da doğrulayın.

Transfer ya da Sesli Posta Hata Veriyor

Hedefin geçerli olduğunu ve Hizmet İlkesi tarafından erişilebilir olduğunu doğrulayın. Profilde çağrı filtreleme özelliği etkinleştirilmişse, aktarım denemesi yapılmadan önce gerekli filtreleme alanlarının toplandığını teyit edin.

AI Sağlayıcı Bağlantıyı Reddediyor

API anahtarını, hesap faturalandırmasını, modele erişimi, bölgeyi, kota sınırını ve WebSocket bağlantısını kontrol edin. Qwen için, API anahtarının ve uç noktasının aynı bölgeye ve çalışma alanına ait olduğunu doğrulayın.

Ses Gecikiyor ya da Temsilci Sıkça Bölünüyor

Uygulama sunucusu, 3CX ve AI sağlayıcısı arasındaki ağ gecikmesini ve paket kaybını kontrol edin. config.yaml dosyasında sağlayıcıya özgü ses etkinliği algılama ve ses ayarlarını gözden geçirin.

Son Güncelleme

Bu kılavuz en son 4 Ağustos 2026’da güncellendi.

https://www.3cx.com.tr/kullanici-kilavuzu/programmable-extensions/