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 belirteci 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.

Create API Key butonu vurgulanmış API sekmesi

Butonun yanındaki sayaç kaç anahtarın aktif olduğunu gösterir ("1 of 5 API keys active" [5 API anahtarından 1'i aktif]). View API Documentation (API Dokümantasyonunu Görüntüle) bağlantısı bu kılavuzu 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) iletişim kutusunda anahtara bir ad verin, isteğe bağlı olarak bir IP beyaz listesi ve bir istek limiti (rate limit) belirleyin, sahip olacağı izinleri seçin ve ardından Create (Oluştur) butonuna tıklayın.

Create API Key iletişim kutusu

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

Bir anahtar ck_abcdefghijklmnopqrstuvwxyz012345 şeklinde görünür. Her anahtar yalnızca o bota aittir, bu nedenle anahtarla yapılan her istek o botla konuşur - bot anahtar tarafından tanımlanır ve URL'de asla görünmez.

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 (belirteç kovası, kapasite 60, saniyede 1 belirteç 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 4.000 karakter.
  • conversationId - isteğe bağlı UUID. Yeni bir konuşma için boş bırakın; var olan bir konuşmaya ekleme yapmak için sunucunun daha önce döndürdüğü değeri yeniden kullanın.
  • metadata - isteğe bağlı nesne: {source, userName, userEmail, userPhone}. userEmail ayrıca dahili müşteri kimliğini türetmek için de kullanılır.

Yanıt gövdesi (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "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, kullanıcı mesajı + bot yanıtını (genellikle 2) ve ayrıca yürütülen her araç çağrısı başına bir ekstra krediyi hesaba katar.
  • actions, bu tur sırasında yürütülen araç işlemlerini listeler. Şu anda yalnızca function_call girdileri yayınlanır (type, name, status: "completed" ile).

POST /v1/chat/stream

/v1/chat uç noktasının akışlı varyantı. 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ğı gerekli değildir - bu yolun kullanılması SSE'yi tetikleyen şeydir.

Yanıt gövdesi (SSE olayları)

  • message.delta - içerik parçası { "content": "..." }. Belirteçler geldikçe bunlardan birden fazlası aktarılır.
  • 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) tamamlanan actions listesini içeren sonlandırıcı olay.
  • error - üretim başarısız olursa gönderilir; ardından akış sonlanır.

Uzun süren üretimler sırasında her 15 saniyede bir bağlantıyı canlı tutma SSE yorumları (:keepalive) gönderilir. Sunucu tarafı zaman aşımları: ilk belirteç 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

Tüm kaynaklar (widget, WhatsApp, API vb.) genelinde anahtarınıza bağlı botun konuşmalarını 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 boş bırakın.

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, sonuna ... eklenerek 100 karaktere kısaltılır.
  • nextCursor, son sayfada null değerindedir; bir sonrakini getirmek için bunu cursor olarak iletin.

GET /v1/conversations/{conversation_id}

Tam konuşma geçmişi.

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 belirteçler.
  • X-RateLimit-Reset - bir sonraki belirtecin 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 belirteç boşalana 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 kapsayıcıyı paylaşır:

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

Yaygın HTTP kodları:

  • 400 invalid_request_error - hatalı biçimlendirilmiş girdi (kodlar: invalid_parameter, 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 beyaz listesinde 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 eylemi
  • 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