Yapılandırılmış Çıktılar — JSON Veri Toplama Rehberi

Genel Bakış

Yapılandırılmış çıktılar, AI Agent’ın görüşme sonunda belirli bir formatta veri döndürmesini sağlar. Bu özellik sayesinde, görüşme sırasında toplanan bilgileri otomatik olarak JSON formatında alabilir ve CRM, veritabanı veya diğer sistemlere aktarabilirsiniz.

Kullanım Senaryoları

Randevu Alma

Müşteri adı, telefon, tercih edilen tarih/saat
Otomatik takvim entegrasyonu
SMS/E-posta onayı

Anket ve Form Doldurma

Müşteri memnuniyet anketi
Ürün/hizmet geri bildirimi
Demografik bilgi toplama

Sipariş Alma

Ürün adı, miktar, fiyat
Teslimat adresi
Ödeme tercihi

Lead Kalifikasyonu

Bütçe bilgisi
Satın alma zamanlaması
Karar verici bilgisi

JSON Schema Nedir?

JSON Schema: Veri yapısını tanımlayan bir format. Agent’ın hangi bilgileri toplaması gerektiğini belirtir. Örnek Schema:

{
  "type": "object",
  "properties": {
    "customerName": {
      "type": "string",
      "description": "Müşterinin tam adı"
    },
    "appointmentDate": {
      "type": "string",
      "format": "date",
      "description": "Randevu tarihi (YYYY-MM-DD)"
    },
    "phoneNumber": {
      "type": "string",
      "pattern": "^[0-9]{10}$",
      "description": "Telefon numarası"
    }
  },
  "required": ["customerName", "appointmentDate"]
}

Yapılandırılmış Çıktı Oluşturma

Agent'ı açın

Agent’lar listesinden agent’a girin. Arama Sonrası bölümündeki Yapılandırılmış Çıktılar satırını seçin.

Şema oluşturun

Agent’ta henüz şema yoksa Şema Oluştur düğmesine basın, ardından İlk Alanı Ekle ile ilk alanı açın. Sonraki alanlar için Alan Ekle’yi kullanın.

Alanları doldurun

Her alan için şunları girin:

Alan	Ne yazılır
Alan Anahtarı	Alanın kısa, boşluksuz adı. Örn. `callback_date`
Alan Adı	Ekranda görünecek ad. Örn. Geri Arama Tarihi
Veri Tipi	String (metin), Integer (tam sayı) ya da Boolean (evet/hayır)
Zorunlu	Bu bilginin her görüşmede çıkarılması gerekiyorsa işaretleyin
Alan Açıklaması	Bu alanda hangi bilginin çıkarılacağını açıklayın. En fazla 500 karakter; sayaç alanın üstünde görünür

String tipindeki alanlarda iki ek seçenek vardır:

Regex Deseni: Değerin uyması gereken desen. Örn. ^[0-9]+$
İzin Verilen Değerler: Alanın yalnızca belirli değerlerden birini döndürmesini istiyorsanız Değer Ekle ile seçenekleri girin. Örn. Nakit

Kaydedin

Kaydet’e basın. Bundan sonraki her görüşme bittiğinde tanımladığınız alanlar konuşmadan otomatik çıkarılır.

Sınırlar

Sınır	Değer
Alan sayısı	En az 1, en fazla 20 alan
Alan anahtarı	En fazla 50 karakter; aynı şemada iki alan aynı anahtarı kullanamaz
Alan adı	En fazla 100 karakter
Alan açıklaması	En fazla 500 karakter
Seçenek değeri	Her biri en fazla 50 karakter

Alan Anahtarı, Alan Adı ve Alan Açıklaması her alanda zorunludur. Biri boşsa ya da bir sınır aşılırsa şema kaydedilmez; 20 alana ulaşınca Alan Ekle düğmesi devre dışı kalır.

Hazır Template’ler

Randevu Alma
Sipariş Alma
Anket

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "phone": {"type": "string"},
    "date": {"type": "string", "format": "date"},
    "time": {"type": "string"}
  },
  "required": ["name", "phone", "date"]
}

{
  "type": "object",
  "properties": {
    "productName": {"type": "string"},
    "quantity": {"type": "number", "minimum": 1},
    "totalPrice": {"type": "number"},
    "deliveryAddress": {"type": "string"}
  },
  "required": ["productName", "quantity"]
}

{
  "type": "object",
  "properties": {
    "satisfaction": {"type": "number", "minimum": 1, "maximum": 5},
    "feedback": {"type": "string"},
    "wouldRecommend": {"type": "boolean"}
  },
  "required": ["satisfaction"]
}

Agent promptuna structured output ile ilgili talimat eklemeyi unutmayın. Örnek: “Görüşme sonunda müşteri adı, telefon numarası ve randevu tarihini topla.”

Veri Tipleri

String (Metin)

{
  "type": "string",
  "description": "Açıklama",
  "minLength": 2,
  "maxLength": 100,
  "pattern": "^[A-Za-z ]+$"
}

Kullanım: İsim, adres, açıklama

Number (Sayı)

{
  "type": "number",
  "description": "Açıklama",
  "minimum": 0,
  "maximum": 100
}

Kullanım: Miktar, fiyat, yaş, puan

Boolean (Evet/Hayır)

{
  "type": "boolean",
  "description": "Açıklama"
}

Kullanım: Onay, tercih, durum

Date (Tarih)

{
  "type": "string",
  "format": "date",
  "description": "YYYY-MM-DD formatında"
}

Array (Liste)

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 1,
  "maxItems": 10
}

Kullanım: Ürün listesi, tercih listesi

Zorunlu Alanlar

Required Kullanımı

{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "email": {"type": "string"},
    "phone": {"type": "string"}
  },
  "required": ["name", "email"]
}

Anlamı: name ve email mutlaka doldurulmalı, phone opsiyonel.

Agent Davranışı:

Zorunlu alanları mutlaka sorar
Opsiyonel alanları konuşma akışına göre sorar
Zorunlu alan eksikse görüşmeyi tamamlamaz

Çıktıyı Görüntüleme

Görüşme Detayı

Görüşme Kayıtlarına Gidin

Çağrı İzleme > Görüşme Kayıtları

Görüşme Seçin

İlgili görüşmeye tıklayın

Structured Output Sekmesi

Toplanan veriler JSON formatında gösterilir

Örnek Görüntüleme:

{
  "name": "Ahmet Yılmaz",
  "phone": "+905551234567",
  "appointmentDate": "2024-03-15",
  "appointmentTime": "14:00"
}

Export ve Kullanım

JSON Download

Download JSON butonu ile dosya indirin

Copy

Copy butonu ile panoya kopyalayın

Entegrasyon

Webhook ile otomatik gönderim veya API ile çekme

İleri Düzey Schema Özellikleri

Enum (Sabit Değerler)

{
  "type": "string",
  "enum": ["Küçük", "Orta", "Büyük"],
  "description": "Beden seçimi"
}

Agent sadece bu 3 değerden birini seçebilir.

Pattern (Regex)

{
  "type": "string",
  "pattern": "^[0-9]{10}$",
  "description": "10 haneli telefon numarası"
}

Telefon numarası formatını zorlar.

Conditional Schema

{
  "type": "object",
  "properties": {
    "hasDiscount": {"type": "boolean"},
    "discountCode": {"type": "string"}
  },
  "if": {
    "properties": {"hasDiscount": {"const": true}}
  },
  "then": {
    "required": ["discountCode"]
  }
}

hasDiscount true ise discountCode zorunlu olur.

Webhook Entegrasyonu

Otomatik Gönderim

Görüşme bittiğinde structured output otomatik olarak webhook’a gönderilebilir.

Webhook Ayarları

Ayarlar > Webhook bölümüne gidin

Webhook URL Girin

Webhook URL’inizi girin

Include Structured Output

Include Structured Output seçeneğini aktif edin

Kaydet

Ayarları kaydedin

Gönderilen Veri:

{
  "callId": "call_xyz123",
  "status": "ended",
  "structuredOutput": {
    "name": "Ahmet Yılmaz",
    "phone": "+905551234567"
  }
}

İpuçları ve En İyi Uygulamalar

Schema Tasarımı

✅ Sadece gerekli alanları ekleyin
✅ Açıklayıcı description kullanın
✅ Uygun validation (min, max, pattern) ekleyin
✅ Zorunlu alanları minimize edin
❌ Çok karmaşık schema oluşturmayın
❌ Gereksiz nested object kullanmayın

Prompt ile Uyum

Agent promptu ile schema uyumlu olmalı. Promptta hangi bilgilerin toplanacağı belirtilmeli. Kötü Örnek:

Müşteriye şu soruları sor:
Adınız?
Telefonunuz?
Randevu tarihi?

İyi Örnek:

Müşteriyle doğal bir randevu konuşması yap.
Görüşme sırasında adını, telefon numarasını ve
tercih ettiği randevu tarihini öğren.

Gerçek Dünya Örnekleri

Restoran Rezervasyon

Schema:

{
  "type": "object",
  "properties": {
    "name": {"type": "string", "description": "Müşteri adı"},
    "phone": {"type": "string", "pattern": "^[0-9]{10}$"},
    "guests": {"type": "integer", "minimum": 1, "maximum": 20},
    "date": {"type": "string", "format": "date"},
    "time": {"type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]$"},
    "specialRequests": {"type": "string"}
  },
  "required": ["name", "phone", "guests", "date", "time"]
}

E-ticaret Sipariş

Schema:

{
  "type": "object",
  "properties": {
    "products": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "quantity": {"type": "integer", "minimum": 1}
        }
      }
    },
    "deliveryAddress": {
      "type": "object",
      "properties": {
        "street": {"type": "string"},
        "city": {"type": "string"},
        "zipCode": {"type": "string"}
      }
    },
    "paymentMethod": {"type": "string", "enum": ["Kredi Kartı", "Kapıda Ödeme"]}
  },
  "required": ["products", "deliveryAddress", "paymentMethod"]
}

Müşteri Memnuniyeti Anketi

Schema:

{
  "type": "object",
  "properties": {
    "overallSatisfaction": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "description": "1-5 arası genel memnuniyet"
    },
    "productQuality": {"type": "integer", "minimum": 1, "maximum": 5},
    "customerService": {"type": "integer", "minimum": 1, "maximum": 5},
    "wouldRecommend": {"type": "boolean"},
    "suggestions": {"type": "string"}
  },
  "required": ["overallSatisfaction", "wouldRecommend"]
}

Sorun Giderme

Schema Validation Hatası

Sebep: JSON syntax hatasıÇözüm:

JSON validator kullanın (jsonlint.com)
Virgül, parantez kontrolü yapın
String değerleri çift tırnak içinde olmalı

Agent Veri Toplamıyor

Sebep: Prompt ile schema uyumsuzÇözüm:

Promptu güncelleyin
Schema’daki alanları prompt ile eşleştirin
Test görüşmesi yapın

Structured Output Boş Geliyor

Sebepler:

Müşteri bilgi vermedi
Agent soruları sormadı
Görüşme erken sonlandı

Çözüm:

Prompt’u daha direktif yapın
Agent’ı zorunlu alanları mutlaka sormaya yönlendirin
Görüşme akışını gözden geçirin

Webhook'a Gönderilmiyor

Çözüm:

Webhook URL’i doğru mu kontrol edin
“Include Structured Output” aktif mi?
Webhook endpoint’i çalışıyor mu test edin
Webhook loglarını inceleyin

Sık Sorulan Sorular

Structured output zorunlu mu?

Hayır, opsiyoneldir. Ancak veri toplama ihtiyacınız varsa kullanmanız önerilir.

Kaç alan ekleyebilirim?

Bir şemada en fazla 20 alan tanımlayabilirsiniz. Her alanın açıklaması en fazla 500 karakter olabilir. Yalnızca gerçekten kullanacağınız bilgileri alan olarak ekleyin.

Agent schema'ya uymayan veri girerse ne olur?

Validation hatası oluşur ve veri kaydedilmez. Agent tekrar deneyebilir.

Structured output ücretlendirilir mi?

Hayır, ek ücret yok. Normal çağrı maliyeti geçerlidir.

Mevcut agent'a sonradan ekleyebilir miyim?

Evet, istediğiniz zaman ekleyebilir veya çıkarabilirsiniz.

Birden fazla schema kullanabilir miyim?

Bir agent’ta tek bir schema kullanılabilir. Farklı senaryolar için farklı agent’lar oluşturun.

​Genel Bakış

​Kullanım Senaryoları

Randevu Alma

Anket ve Form Doldurma

Sipariş Alma

Lead Kalifikasyonu

​JSON Schema Nedir?

​Yapılandırılmış Çıktı Oluşturma

​Sınırlar

​Hazır Template’ler

​Veri Tipleri

​String (Metin)

​Number (Sayı)

​Boolean (Evet/Hayır)

​Date (Tarih)

​Array (Liste)

​Zorunlu Alanlar

​Required Kullanımı

​Çıktıyı Görüntüleme

​Görüşme Detayı

​Export ve Kullanım

JSON Download

Copy

Entegrasyon

​İleri Düzey Schema Özellikleri

​Enum (Sabit Değerler)

​Pattern (Regex)

​Conditional Schema

​Webhook Entegrasyonu

​Otomatik Gönderim

​İpuçları ve En İyi Uygulamalar

​Schema Tasarımı

​Prompt ile Uyum

​Gerçek Dünya Örnekleri

​Sorun Giderme

​Sık Sorulan Sorular

​İlgili Makaleler

AI Agent Oluşturma

Gelişmiş Yapılandırma

Genel Bakış

Kullanım Senaryoları

JSON Schema Nedir?

Yapılandırılmış Çıktı Oluşturma

Sınırlar

Hazır Template’ler

Veri Tipleri

String (Metin)

Number (Sayı)

Boolean (Evet/Hayır)

Date (Tarih)

Array (Liste)

Zorunlu Alanlar

Required Kullanımı

Çıktıyı Görüntüleme

Görüşme Detayı

Export ve Kullanım

İleri Düzey Schema Özellikleri

Enum (Sabit Değerler)

Pattern (Regex)

Conditional Schema

Webhook Entegrasyonu

Otomatik Gönderim

İpuçları ve En İyi Uygulamalar

Schema Tasarımı

Prompt ile Uyum

Gerçek Dünya Örnekleri

Sorun Giderme

Sık Sorulan Sorular

İlgili Makaleler