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 Düzenleme

AI Agent’lar sayfasına gidin
Düzenlemek istediğiniz agent’ı seçin
Düzenle butonuna tıklayın
Gelişmiş Ayarlar sekmesine geçin

Schema Tanımlama

Structured Output bölümü:

Etkinleştir switch’ini açın
Schema Editor açılır
JSON schema’nızı girin veya Template kullanın

Template Seçimi

Platform hazır template’ler sunar. İhtiyacınıza uygun olanı seçin veya özelleştirin.

Schema Doğrulama

Validate butonuna tıklayın:

✅ “Schema is valid” - Yeşil onay işareti
❌ Hata mesajı - Satır numarası ve düzeltme önerileri

Prompt Güncellemesi

Agent promptuna structured output ile ilgili talimat ekleyin.

Kaydetme

Test Et butonuyla test edin, sonra Kaydet

Yapılandırılmış çıktı ayarları — JSON şema tanımı ve alan yapılandırması

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?

Teknik limit yok, ancak 5-10 alan ideal. Çok fazla alan agent’ı yavaşlatır.

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

​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

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