Yardım Merkezi
Chat API

Bot Talk API

Son güncelleme:

Bot Talk API

Bot Talk API, kendi uygulamanızdan (özel uygulamalar, dahili araçlar veya kendinizin oluşturduğu otomasyonlar) belirli bir chatbot ile iletişim kurmaya yarayan bir REST API'dir. Botun API sekmesinde bir API anahtarı oluşturur, ardından botun yanıtlarını tek bir yanıt olarak veya SSE üzerinden aktarılan bir akış şeklinde almak için bu anahtarı Bearer token'ı olarak kullanarak sohbet uç noktasını çağırırsınız.

Başlarken

  1. Chatbot'unuzu seçin ve bot sayfasının üst kısmındaki API sekmesine gidin (Select Bot > API [Bot Seçin > API]).

Bot Talk API sekmesi

  1. Create API Key (API Anahtarı Oluştur) butonuna tıklayın.

API sekmesi vurgulanmış; Create API Key sayfa içeriğinde yer alıyor

Butonun yanındaki sayaç, kaç anahtarın etkin olduğunu gösterir ("1 of 5 API keys active" [5 API anahtarından 1'i etkin]). View API Documentation (API Belgelerini Görüntüle) bağlantısı bu referans kılavuzunu açar ve Quick Start (Hızlı Başlangıç) curl kod parçacığı çalıştırılmaya hazır bir örnek sunar.

  1. Create API Key (API Anahtarı Oluştur) penceresinde anahtara bir ad verin, isteğe bağlı olarak bir IP beyaz listesi ve istek sınırı (rate limit) belirleyin, sahip olacağı izinleri seçin ve ardından Create (Oluştur) butonuna tıklayın.

Create API Key penceresi

  1. Başarılı işlem penceresinden anahtarın tamamını kopyalayın. Düz metin yalnızca bir kez gösterilir.

Anahtar ck_abcdefghijklmnopqrstuvwxyz012345 şeklinde görünür. Her anahtar yalnızca ilgili bota aittir; bu sayede anahtarla yapılan her istek doğrudan o botla iletişim kurar - bot doğrudan anahtarla tanımlanır ve URL'de hiçbir zaman yer almaz.

  1. Sunucunuzdan, anahtarınız ve kısa bir test mesajı ile aşağıdaki curl örneğini çalıştırın. Dönen conversationId değerini kaydedin ve ardından bir sonraki mesaj için tekrar kullanın. Yanıtı ve konuşmayı botun Chatlogs (Sohbet Kayıtları) sekmesinden kontrol edin.

ck_ anahtarlarını web sitesi JavaScript dosyalarında veya mobil uygulama paketlerinde değil, kendi sunucunuzda tutun. Conversations (Sohbetler) izni, bu botun tüm ziyaretçilerle gerçekleştirdiği kayıtlı konuşmalara erişim sağlar; bu nedenle uygulamanız bu verileri döndürmeden önce her son kullanıcının ilgili verilere erişim yetkisini kontrol etmelidir. Bir anahtarı kullanımdan kaldırmak için API sekmesindeki Revoke (İptal Et) veya Delete (Sil) seçeneklerini kullanın; iki işlem de anahtarın düz metnini tekrar göstermez.

Başlamadan önce chatbot'unuzu oluşturup eğitin ve hesabınızın API erişimi içerdiğinden ve mesaj kredisine sahip olduğundan emin olun.

Temel URL

https://api.chatlab.com/aichat

Bu makaledeki tüm uç noktalar bu temel URL'ye görelidir.

Anahtar izinleri

Her anahtar, Create API Key iletişim kutusundaki geçiş anahtarlarıyla ayarlanan bu izinlerden birini veya her ikisini taşır:

  • Chat (send messages and receive responses) - /v1/chat ve /v1/chat/stream uç noktalarına izin verir.
  • Conversation history (list and read past conversations) - /v1/conversations uç noktalarına izin verir.

API sekmesi, her anahtara verilen izinleri Chat ve Conversations rozetleri olarak gösterir.

Kimlik doğrulama

Her istekte anahtarı Authorization üstbilgisinde gönderin:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Authorization: Bearer ... üstbilgisi bulunmayan istekler 401 missing_api_key döndürür. Bilinmeyen anahtarlar 401 invalid_api_key; iptal edilen anahtarlar ise 401 revoked_api_key döndürür. Aynı IP'den bir dakika içinde yapılan beş geçersiz deneme, 60 dakikalık bir engellemeyi tetikler.

Limitler

  • Bot başına en fazla 5 aktif Bot Talk anahtarı
  • Anahtar başına dakikada en fazla 60 istek (token kovası, kapasite 60, saniyede 1 token ile düzenli dolum). Oluşturma sırasında aşağı doğru yapılandırılabilir - daha düşük bir rateLimitPerMinute değeri ayarladığınızda üst sınır düşer, dolum hızı da buna göre ölçeklenir.
  • Maksimum mesaj uzunluğu 4.000 karakter
  • Anahtar başına eşzamanlı SSE akışları hesap limitlerinize tabidir

Uç noktalar

POST /v1/chat

Bota bir mesaj gönderin ve yanıtın tamamını tek bir JSON yanıtı olarak alın.

İstek gövdesi

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - zorunlu dize, en fazla 4000 karakter.
  • conversationId - isteğe bağlı UUID. Yeni bir konuşma başlatmak için bu alanı göndermeyin; mevcut bir konuşmaya ekleme yapmak için sunucunun daha önce döndürdüğü değeri yeniden kullanın.
  • metadata - {source, userName, userEmail, userPhone} kabul eden isteğe bağlı nesne. Şu anda burada yalnızca userEmail istemci tanımlayıcısını türetmek için kullanılır; kanal API olarak kaydedilir. Diğer meta veri alanlarının bir lead kaydına kaydedileceğine güvenmeyin.

Yanıt gövdesi (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role her zaman "assistant" değerindedir; message.content yanıtın tamamıdır.
  • model, bu çağrı için botun üzerinde çalıştığı model kimliğidir.
  • usage.creditsUsed şu anda tamamlanan bir tur için 2 artı bildirilen araç çağrısı başına bir adet raporlar. Bu yanıt sayacı model/bağlam kredi çarpanlarını içermez ve faturalandırma defteriniz olarak kullanılmamalıdır. Hesap tüketimi için Management API kullanımı bölümünü kullanın ve mesaj kredileri konusuna bakın.
  • actions, bu tur sırasında çalıştırılan araç yürütmelerini listeler. Şu anda yalnızca function_call girdileri yayınlanır (type, name, status: "completed" ile birlikte).

POST /v1/chat/stream

/v1/chat uç noktasının akış (streaming) varyantıdır. Server-Sent Events ile Content-Type: text/event-stream döndürür.

İstek gövdesi

POST /v1/chat ile aynı yapıdadır. Gövdedeki stream bayrağı zorunlu değildir - SSE'yi tetikleyen şey doğrudan bu yolun kullanılmasıdır.

Yanıt gövdesi (SSE olayları)

  • message.reset - geçerli yanıt için biriken metni atın ve deltaları yeniden toplamaya başlayın. Bu durum, oluşturma işlemi yeniden başladığında meydana gelebilir; her iki sürümün de eklenmesi yinelenen veya geçersiz kılınmış bir yanıt gösterir.
  • message.delta - içerik parçası { "content": "..." }. Token'lar geldikçe bunlardan birden fazlası akar.
  • action - araç yürütme { "type", "name", "status": "executing" }. Bot bir işlev çağrısını tetiklediğinde yayınlanır.
  • message.done - conversationId, model, usage ve (varsa) tamamlanmış actions listesini içeren sonlandırıcı olay.
  • error - oluşturma başarısız olursa gönderilir; akış sonrasında sonlanır.

Uzun süren oluşturma işlemleri sırasında her 15 saniyede bir keep-alive SSE yorumları (:keepalive) gönderilir. Sunucu tarafı zaman aşımları: ilk token için 30 saniye, akış başına toplam 120 saniye.

Curl örneği

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Anahtarınıza bağlı bot için tüm kaynaklardaki (widget, WhatsApp, API vb.) konuşmaları listeleyin.

Sorgu parametreleri

  • limit - 1-100, varsayılan 20. Aralık dışındaki değerler sınırlanır.
  • cursor - önceki sayfada nextCursor içinde döndürülen opak değer. İlk sayfa için bu parametreyi göndermeyin.

Yanıt gövdesi (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • lastMessagePreview, bir ... soneki ile 100 karaktere kısaltılır.
  • nextCursor son sayfada null değerini alır; sonrakini getirmek için bunu cursor olarak iletin.

GET /v1/conversations/{conversation_id}

Bu uç nokta tarafından sunulan saklanan konuşma mesajları.

Yanıt gövdesi (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Yalnızca user ve assistant rolleri döndürülür; dahili system ve araç mesajları filtrelenir. Konuşma anahtarınıza bağlı bota ait değilse 404 not_found_error döndürür.

Bot yapılandırmasını incelemek için bir Management anahtarı ile GET /v1/management/bots/{bot_id} Management API uç noktasını kullanın.

İstek limiti üstbilgileri

İstek limiti aşamasına ulaşan (yani kimlik doğrulaması ve IP beyaz listesini geçen) yanıtlar şunları içerir:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - bu çağrıya fiilen uygulanan anahtar başına üst sınır (varsayılan olarak 60 veya daha düşükse yapılandırdığınız rateLimitPerMinute).
  • X-RateLimit-Remaining - bu çağrının hemen ardından kovada kalan token'lar.
  • X-RateLimit-Reset - bir sonraki token'ın kullanılabilir hale geleceği Unix epoch saniyesi (tam bir kova sıfırlaması değil; kova sürekli dolar). Kova dolu olduğunda bu geçerli zamandır.

429 rate_limit_exceeded yanıtlarında, en az bir token kullanılabilir hale gelene kadar tam saniye cinsinden ifade edilen Retry-After da ayarlanır.

Kimlik doğrulama öncesi hatalar (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ve 403 ip_not_whitelisted, X-RateLimit-* üstbilgilerini taşımaz - sınırlayıcıya yalnızca kimlik doğrulama ve IP kontrolleri başarılı olduktan sonra başvurulur.

Hata formatı

Tüm hatalar tek bir ortak yapıyı paylaşır:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Sık karşılaşılan HTTP kodları:

  • 400 invalid_request_error - hatalı biçimlendirilmiş girdi (invalid_parameter)
  • 415 invalid_request_error - desteklenmeyen içerik türü (unsupported_media_type)
  • 401 authentication_error - eksik anahtar (missing_api_key), bilinmeyen anahtar (invalid_api_key) veya iptal edilmiş anahtar (revoked_api_key)
  • 402 quota_exceeded_error - mesaj kredisi tükendi
  • 403 permission_error - IP engellendi (ip_blocked), IP anahtarın izin verilenler listesinde (whitelist) değil (ip_not_whitelisted) veya anahtar türü bu uç noktaya izin vermiyor (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - konuşma bu bota ait değil
  • 405 invalid_request_error (method_not_allowed) - URL üzerinde yanlış HTTP fiili
  • 429 rate_limit_error - çok fazla istek (rate_limit_exceeded) veya çok fazla eşzamanlı akış (concurrent_streams_exceeded)
  • 500 api_error - dahili hata

İlgili konular

Hesap düzeyindeki işlemler için (bot oluşturma, bot güncelleme, kullanım alma), Management API sayfasına bakın.

Tüm makalelerde arayınTemsilciye sorun