Getting Started

Temel kavramlar

Platformdaki her şeyin haritası — her nesnenin ne yaptığı, panoda nerede bulunduğu ve hangi API’nin onunla etkileşime geçtiği.

ThunderPhone, sesli yapay zeka ajanları oluşturmak, çalıştırmak ve geliştirmek için eksiksiz bir platformdur. Bu sayfa haritanızdır: karşılaşacağınız her kavram, her biri kısa bir bölümde, kontrol paneli alanı ve bunu destekleyen API ile birlikte açıklanır. Bir kez göz gezdirin, ardından bir terimin açıklanması gerektiğinde geri dönün.

Kontrol paneli kenar çubuğu bu yapıyı yansıtır:

Organizasyonlar#

Bir organizasyon, kiracılık birimidir. Ajanlar, telefon numaraları, aramalar ve anahtarlar gibi diğer tüm kaynaklar tam olarak bir organizasyona aittir. Hesabınız birçok organizasyona ait olabilir; her birinin kendi bakiyesi, kendi anahtarları ve kendi üye listesi vardır.

Organizasyon → Anahtarlar altında oluşturduğunuz sk_live_ API anahtarı tek bir organizasyona bağlıdır. REST API'nin bu kadar yalın olmasını sağlayan bu bağdır: Anahtarınız organizasyonu zaten tanımladığı için URL yollarına hiçbir zaman organizasyon kimliği eklemezsiniz.

Kontrol panelinde: organizasyon seçici (kenar çubuğu alt bilgisi) ve Organizasyon ayarları — Hesabım, Genel, Anahtarlar, Uyarılar, Faturalandırma Ayarları ve Faturalandırma Geçmişi sekmeleri. Organizasyon ayarları referansına bakın.

API'de: /v1/orgs, /v1/developer/api-keys.

Ajanlar#

Bir ajan, bir aramayı çalıştıran yapay zeka yapılandırmasıdır. Şunları bir araya getirir:

• Ajanın ne söyleyeceğini ve nasıl davranacağını yöneten bir istem — aktarımlar, tuş takımı basımları ve aramayı sonlandırma gibi arama eylemleri de buna dahildir; bunlar ayrı yapılandırmalar yerine düz istem satırlarıdır.
• Bir motor katmanı (spark, bolt, storm-*): Spark maliyet için, Bolt hız için, Storm ise karmaşık istemlerde zeka için optimize edilmiştir.
• Bir ses, bir ana dil ve isteğe bağlı ek diller — arayan kişi dili değiştirdiğinde ajan otomatik olarak geçiş yapar. Desteklenen dillere bakın.
• Ekli yetenekler: bağlı uygulamalar, API bağlantıları, bilgi tabanları, MCP sunucuları ve satır içi fonksiyon araçları.
• Davranış ayarları: konuşma sırası, onay modu, arka plan parçası, bekletme zaman aşımı.

Oluşturucudaki düzenlemeler otomatik olarak bir taslağa kaydedilir; siz Yayınla seçeneğine tıklayana kadar hiçbir şey yayına alınmaz. Her yayına alma, oluşturucunun Geçmiş sekmesinde anlık görüntü olarak kaydedilir; böylece önceki herhangi bir sürümü inceleyebilir ve geri yükleyebilirsiniz.

Kontrol panelinde: Sesli AI Ajanları → ajan oluşturucu (/dashboard/agents). İlk sesli yapay zeka ajanınızı oluşturun.

API'de: /v1/agents — CRUD, çoğaltma, aktarma, sürüm geçmişi ve istem yardımcıları.

Sesler#

Ses kitaplığı, bir ajanın kullanabileceği sesleri, oynatılabilir örneklerini, uyumlu dilleri, cinsiyet ve aksan gruplarını ve tüm premium ses/dil ek ücretlerini içerir. Seçim yapmadan önce ücretli örnekleyici ile 1–500 karakterlik kendi ifadenizi sentezleyebilirsiniz.

Uygun kuruluşlar, kısa bir WAV veya MP3 örneğinden özel sesler de oluşturabilir. Özel seslerin kotası ve eşzamansız oluşturma durumu vardır; hazır olduklarında, kitaplık sesleriyle aynı ajan seçicisinde görünürler.

Panoda: Sesler (/dashboard/voices). Bkz. Ses kitaplığı ve özel sesler.

API'de: /v1/voices, ses örnekleri ve özel sesler.

Telefon numaraları#

Bir telefon numarası bir kuruluşa aittir ve gelen aramaları bir ajana yönlendirir (ayrıca giden aramaları taşıyabilir). İki kaynak vardır:

• Demo numaraları — ThunderPhone havuzundan sağlanan gerçek ABD numaralarıdır ve saniyeler içinde etkinleşir. Yalnızca gelen aramaları destekler, kısa bir sesli bilgilendirmeyle yanıt verir ve pano bir kuruluşu bunlardan 10 adetle sınırlar. İlk test için idealdir; üretim için değildir.
• VoIP numaraları — kendi sağlayıcınızdan bir VoIP bağlantısı aracılığıyla getirilir. Twilio ve Telnyx doğrudan bağlanır (Telnyx rehberli kurulum sunar); SignalWire ve Vonage yakında eklenecektir — bugün bu hizmetlere, herhangi bir SIP trunk'ını kabul eden manuel SIP yapılandırmasıyla erişebilirsiniz. İçe aktarıldıktan ve doğrulandıktan sonra VoIP numaraları gelen ve giden aramaları destekler.

Her numara satırında bir yönlendirme modu ayarlayabilir, gelen aramalar için ajanı seçebilir ve numarayı etiketleyebilirsiniz.

Panoda: Telefon Numaraları (/dashboard/phone-numbers). Bkz. Telefon numarası alın.

API'de: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

Aramalar#

Her gelen arama, giden arama, simülasyon ve pencere öğesi oturumu bir arama kaydı olur. Bir arama; rollerle etiketlenmiş eksiksiz görüşme metnini, yapılandırılmış tur geçmişini (araç çağrıları dahil), bir kaydı, faturalandırma toplamını ve isteğe bağlı AI derecelendirme ile sorun raporlarını içerir.

Bir arama canlı durumdayken aramayı açıp dinleyebilirsiniz — sessizce katılırsınız ve aramadaki hiç kimse sizi duymaz. Dinlemeye başladıktan sonra fısıldayabilirsiniz: arama sırasında doğrudan ajanınıza giden bir talimat yazın; arayan kişi bunu asla duymaz ve ajan talimatı canlı olarak uygular.

Panoda: Arşiv ve arama başına ayrıntılar için Arama Geçmişi (/dashboard/call-history); devam eden aramalar için Canlı. Bkz. Aramalarınızı inceleyin, dinleyin ve yönlendirin.

API'de: /v1/calls — liste, görüşme metni, geçmiş, ses, derecelendirme, dışa aktarma; /v1/issue-reports.

Müşteri portalları#

Bir müşteri portalı, harici bir müşteri için markalı, salt okunur bir arama geçmişi görünümüdür. Kuruluş yöneticileri, aramalarının görüneceği ajanları seçer, onaylı görüntüleyici e-posta adreslerini ekler, logo ve vurgu rengi yükler ve isteğe bağlı olarak özel bir alan adını doğrular. Portal görüntüleyicileri, pano erişimi almadan arama ayrıntılarını, görüşme metinlerini ve mevcut kayıtları inceleyebilir.

Panoda: Müşteri portalları (/dashboard/client-portals). Bkz. Müşteri portalları.

API'de: Yönetici yönetim alanı için /v1/client-portals.

Web bileşenleri#

Web bileşeni, site ziyaretçilerinize mikrofon tabanlı olarak bir ajanla konuşma imkanı sunar — telefon numarası gerekmez. İzin verilen alan adlarınıza kaynak bazında kilitlenen bir yayınlanabilir anahtarla (pk_live_...) kimlik doğrulaması yapar; bu nedenle istemci tarafı kodda kullanmak güvenlidir.

Anahtarlar iki moddan birinde çalışır: agent (tek bir ajana statik olarak bağlı) veya webhook (sunucunuz her ziyaretçi için yapılandırmayı seçer — bkz. Çağrı başına dinamik yapılandırma). Bileşen oturumları, telefon çağrılarıyla aynı çağrı altyapısından geçer.

Kontrol panelinde: Web Bileşenleri (/dashboard/web-widgets) — bileşenler oluşturun, modu ve ajanı ayarlayın, izin verilen alan adlarını yönetin ve yerleştirme kod parçacığını kopyalayın. Bkz. Web bileşeni oluşturma.

API'de: /v1/publishable-key, /v1/mic-session ve Bileşen SDK belgeleri.

Bilgi tabanları#

Bilgi tabanı, ajanınızın yanıtlarını temellendirmek için çağrı sırasında arayabileceği bir belge kümesidir — dosya yükleyin, metin yapıştırın veya URL ile web sayfalarını içe aktarın; ardından oluşturucuda bilgi tabanını bir ajana ekleyin. Ajan, konuşma gerektirdiğinde yerleşik arama aracını kullanarak bu bilgi tabanını sorgular.

Kontrol panelinde: Belge kitaplığı için Bilgi (/dashboard/knowledge); bir ajana bilgi tabanı eklemek için oluşturucudaki Bilgi bölümü. Bkz. Ajanınıza bilgi tabanı ekleme.

Bağlantılar#

Bağlantılar, ajanların dış dünyaya ulaşmasını sağlar. Dört tür, tek bir kenar çubuğu grubu:

• Uygulamalar (/dashboard/app-connections) — Slack, HubSpot, Salesforce, Google Calendar, Google Sheets ve Cal.com için OAuth bağlantıları. Bir kez bağlayın, ardından işlem bazlı araçları (Slack mesajı gönderme, HubSpot kişisini güncelleme veya ekleme, Cal.com zaman aralığı ayırtma…) herhangi bir ajan için etkinleştirin. Bkz. Uygulamaları bağlama.
• API'ler (/dashboard/api-connections) — herhangi bir HTTP API'sini ajan eylemine dönüştürün. Bir cURL komutu yapıştırın; yapay zeka sihirbazı araç tanımının taslağını oluşturur. Alternatif olarak aracı manuel oluşturun; İsteği Test Et düğmesi yayına almadan önce korumalı alanda bir çağrı gerçekleştirir. Bkz. API bağlantıları — bunun kontrol panelindeki karşılığı /v1/integrations.
• MCP (/dashboard/mcp-connections) — URL ile bir Model Context Protocol sunucusu ekleyin ve ajanın sunduğu araçları kullanmasına izin verin. Bkz. MCP sunucusu ekleme.
• VoIP (/dashboard/voip-connections) — kendi telefon numaralarınızı getirmek için sağlayıcı kimlik bilgileri. Bkz. VoIP sağlayıcısı bağlama.

ThunderPhone ayrıca harici bir MCP istemcisinin ajanları listeleyebilmesi, çağrıları ve transkriptleri inceleyebilmesi ve çağrı başlatabilmesi için kendi MCP uç noktasını sunar. Bkz. ThunderPhone'u MCP sunucusu olarak kullanma.

API'de: /v1/integrations, /v1/mcp-servers ve /v1/voip-connections; ayrıca bkz. Araç entegrasyonu oluşturma.

Kampanyalar#

Bir kampanya, büyük ölçekte giden çağrılar başlatır: kişi içeren bir CSV yükleyin, ajanı ve arayan numarayı seçin; ardından arama zaman aralığını (günler ve saatler, saat dilimine duyarlı), eşzamanlılık düzeyini ve yeniden deneme politikasını (maksimum deneme sayısı ile hangi sonuçların — yanıt yok, sesli mesaj, başarısız — yeniden deneneceğini) ayarlayın. Kampanya listedeki kişileri sırayla işler ve her çağrıyı Çağrı Geçmişi'ne kaydeder.

Kontrol panelinde: Kampanyalar (/dashboard/campaigns). Bkz. Giden çağrı kampanyası yürütme.

Tek seferlik programatik çağrılar için: giden çağrılar API'si.

Canlı izleme#

Canlı, kuruluş genelindeki devam eden tüm çağrıları gösterir ve bunlardan herhangi birini gerçek zamanlı olarak dinlemek ve fısıldamak için açmanıza olanak tanır. Bu, denetim alanıdır: yeni bir istemin ilk gerçek trafiğini izleyin veya devam eden bir kampanyayı takip edin.

Kontrol panelinde: Canlı (/dashboard/live). Bkz. Canlı çağrıları izleme ve denetleme.

Simülasyonlar#

Bir simülasyon, yapay zeka arayanın ajanınızla gerçek bir görüşme yapmasıdır — aynı telefon altyapısı yolu, gerçek transkript, gerçek değerlendirme — böylece yayına almadan önce (ve sonra) test edebilirsiniz. Bir ajana veya telefon numarasına yönlendirin, arayan senaryosunu kendiniz yazın ya da ajanın isteminden yapay zekayla senaryolar oluşturun (isterseniz uç durumlar da dahil edilir) ve çağrıyı canlı izleyin.

Senaryolar, minimum geçiş oranını sabitleyen ve CI'da sürüm yayınlarını engelleyebilen paketler halinde gruplandırılır; kabul edilen temel çizgiye göre gerilemeler her senaryo için raporlanır.

Kontrol panelinde: Simülasyonlar (/dashboard/simulations) ve ajan oluşturucudaki Simülasyon düğmesi. Bkz. Bir çağrıyı simüle etme.

API'de: /v1/test-calls ve paket çalıştırıcısı — bkz. Bir ajanı uçtan uca test etme.

Doğrulama kümeleri#

Bir doğrulama kümesi, gerçek çağrı anlarını tekrarlanabilir, tek turlu gerileme kontrollerine dönüştürür. Her örnek, görüşme bağlamını, ilgili arayan sesini, özgün yanıtı ve beklenen davranışı sabitler. Tekrar yürütmeler, başka bir çağrı başlatmadan mevcut ajan taslağına karşı çalışır ve yayınlama iletişim kutusu, en son çalıştırmanın hâlâ bu taslakla eşleşip eşleşmediğini gösterebilir.

Kontrol panelinde: kuruluş veri kümesi için Doğrulama kümeleri (/dashboard/validation) ve çalıştırmalar için ajan oluşturucunun Doğrulama sekmesi. Bkz. Doğrulama kümeleri.

API'de: /v1/validation-sets ve aynı referans sayfasındaki ajan/örnek tekrar yürütme uç noktaları.

Deneyler#

Bir deney, canlı trafikte ajan yapılandırmalarını A/B testiyle karşılaştırır: varyantları (farklı istemler, motorlar veya ayarlar) tanımlayın, trafiği bunlar arasında bölüştürün ve sonuçları varyant bazında karşılaştırın. Webhook'ta bucket mantığını elle oluşturmak yerine bunu kullanın.

Kontrol panelinde: Deneyler (/dashboard/experiments) ve ajan oluşturucudaki A/B sekmesi. Bkz. Deneyler (A/B testi).

Sorunlar#

Bir sorun, belirli bir çağrıda işaretlenmiş bir problemdir — insan denetçi tarafından bildirilir veya yapay zeka değerlendirmesiyle tespit edilir. Sorunlar önem derecesi, kaynak ve durum bilgilerini taşır; Sorunlar sayfası ise önceliklendirme kuyruğudur: filtreleyin, sorunlu çağrıyı inceleyin ve düzeltmeleri takip edin.

Kontrol panelinde: Sorunlar (/dashboard/issues) ve Çağrı Geçmişi'ndeki çağrı bazlı işaretleme. Bkz. Sorun önceliklendirme.

API'de: /v1/issue-reports.

Raporlar#

Bir rapor, çağrı verileriniz hakkında doğal dilde sorulan bir soruyu ("Geçen hafta arayanların bir insanla konuşmak istemesinin en yaygın üç nedeni neydi?") seçtiğiniz ajanlar ve tarih aralığıyla sınırlı, yapay zeka tarafından yazılmış bir analizle yanıtlar.

Kontrol panelinde: Raporlar (/dashboard/reports). Bkz. Raporlar.

Gözlemlenebilirlik#

Gözlemlenebilirlik, metrik alanıdır: çağrı hacmi, sonuçlar ve zaman içindeki kalite; ajan ve zaman aralığına göre filtrelenebilir ve sonraki analizler için dışa aktarılabilir.

Kontrol panelinde: Gözlemlenebilirlik (/dashboard/observability). Bkz. Gözlemlenebilirlik.

Uyarılar#

Bir uyarı kuralı, bir zaman aralığında bir metriği (başarı oranı, başarısızlık oranı, ortalama puan, çağrı hacmi, paket gerilemeleri) izler ve eşiğinizi aştığında tetiklenir. Bildirimler e-posta ve Slack'e gönderilir ve webhook uç noktalarınıza bir alert.triggered olayı tetikler.

Kontrol panelinde: Kuruluş → Uyarılar. Bkz. Uyarılar.

Web kancaları#

ThunderPhone, bir arama sırasında ve sonrasında gerçekleşen olaylarda sunucunuza HTTP POST web kancaları gönderir. İki teslimat modeli vardır:

• Web kancası uç noktaları (önerilir): uç nokta başına gizli anahtarlar ve uç nokta başına olay abonelikleriyle birçok URL'yi /v1/developer/webhook-endpoints adresinden yönetin.
• Eski tek URL'li web kancası: organizasyon başına bir URL. /v1/webhook adresinden veya Organizasyon → Genel altında yönetilir. Geriye dönük uyumluluk için korunur.

Olaylar iki sınıfa ayrılır:

• Engelleyici olaylar, sunucunuzun devam eden aramayı şekillendiren yapılandırmayla yanıt vermesini bekler — gelen arama olayları (telephony.incoming / web.incoming). Yanıt vermek için en fazla 10 saniyeniz vardır; zaman aşımında statik olarak atanmış ajan aramayı yönetir.
• Engelleyici olmayan olaylar, üstel geri çekilmeyle yeniden denenen, gönder ve unut bildirimleridir — bkz. teslimat semantiği.

Her istek, X-ThunderPhone-Signature içinde bir HMAC-SHA256 imzası taşır. Bkz. İmza doğrulama.

Fonksiyon araçları#

Bir fonksiyon aracı, yapay zeka ajanınızın konuşma sırasında çağırabileceği bir HTTP uç noktasıdır. ThunderPhone'a OpenAI tarzı bir fonksiyon şeması ve uç nokta URL'si verirsiniz; ajan bunun ne zaman çağrılacağına karar verir, ThunderPhone imzalı HTTP isteğini kendi sunucularından gönderir ve sonucu ajana iletir.

Ajanlar ayrıca aramayı aktarma, tuş takımı (DTMF) girdisi gönderme, aramayı sonlandırma ve bekletmede bekleme gibi yerleşik arama yetenekleriyle gelir; bunları araç tanımları yerine sade istem satırlarıyla etkinleştirirsiniz.

Kontrol panelinde: oluşturucunun API bağlantıları bölümü (bkz. Bağlantılar).

API'de: /v1/integrations ve Fonksiyon Araçları spesifikasyonu.

Ekip ve roller#

Her organizasyonun iki rollü bir üye listesi vardır: Üyeler ajanları oluşturur ve işletir; Yöneticiler ayrıca ekibi ve faturalamayı yönetir. E-posta ile davet edin — davetlerin süresi 7 gün sonra dolar ve davetler iptal edilebilir; bir üye satırındaki ⋯ menüsü rolleri değiştirir veya bir kişiyi kaldırır. Tek oturum açma organizasyon genelinde yapılandırılabilir — bkz. SSO.

Kontrol panelinde: Organizasyon → Genel. Bkz. Ekibinizi davet edin.

API'de: /v1/members, /v1/invites.

Faturalama#

ThunderPhone ön ödemelidir. Her organizasyonun bir USD bakiyesi vardır; aramalar, ajanın dakika başına ücretinden bu bakiyeyi düşer (motor katmanı artı ek ücretler — oluşturucu, ayarları değiştirdikçe toplam ücreti canlı olarak gösterir ve seçili ek diller dakika başına 3¢ ekler). Bakiye sıfıra ulaştığında gelen aramalar reddedilir ve giden aramalar 402 Payment Required döndürür.

Manuel olarak bakiye yükleyin veya bakiye eşiği, yenileme tutarı ve isteğe bağlı aylık harcama limitiyle otomatik bakiye yüklemeyi etkinleştirin — böylece bir arama asla cümle ortasında kesilmez.

Kontrol panelinde: Organizasyon → Faturalama Ayarları ve Faturalama Geçmişi. Bakiye ekleme ve otomatik bakiye yüklemeyi açma rehberine ve tam fiyatlandırma referansına bakın.

API'de: /v1/billing.

Uygulama içi yardımcı pilot#

Kontrol paneli yerleşik bir yardımcı pilot sunar — ona "X'i nasıl yaparım" diye sorun; bu dokümanlardan yanıt verir, gerçek denetimleri öne çıkaran tıklama adımıyla rehberler sunar ve rehberli turlardan herhangi birini yeniden oynatabilir. Bu sayfanın bahsettiği bir denetimi bulmanın en hızlı yoludur. Bkz. Uygulama içi yardımcı pilota sorun.

Bir araya getirme#