Management API

Management API genel bakış

Management API, sohbet mesajı göndermeyi içermeyen arka ofis işlemleri içindir:

• POST /v1/management/bots ile programatik olarak bir bot oluşturma
• GET /v1/management/bots/{bot_id} ile sahip olduğunuz belirli bir botu okuma
• PATCH /v1/management/bots/{bot_id} ile belirli bir botu güncelleme
• GET /v1/usage ile abonelik kullanımını okuma

Yönetim anahtarları belirli bir bota değil, doğrudan hesabınıza bağlıdır. Güvenliği ihlal edilmiş bir sohbet anahtarının botlarınızı değiştirememesi veya faturalandırma verilerinizi okuyamaması için Bot Talk anahtarlarından kasten ayrı tutulurlar.

Base URL

https://api.chatlab.com/aichat

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

Başlarken

1. Yönetici uygulamasını açın ve Account Settings > Management API (Hesap Ayarları > Management API) bölümüne gidin.
2. Create Management Key (Yönetim Anahtarı Oluştur) seçeneğine tıklayın, anahtara bir ad verin, isteğe bağlı olarak IP beyaz listesi ve istek sınırı (rate limit) belirleyin, ardından formu gönderin.
3. Yalnızca entegrasyonunuzun ihtiyaç duyduğu izinleri seçin ve başarı modalından anahtarın tamamını kopyalayın. Düz metin yalnızca bir kez gösterilir.
4. Anahtarı tarayıcı kodunda veya herkese açık bir depoda değil, sunucunuzda saklayın. Erişimi doğrulamak için usage izniyle GET /v1/usage gibi salt okunur bir istek gönderin.
5. Kullanılmayan veya güvenliği ihlal edilmiş anahtarları Management API sayfasından iptal edin.

Anahtar mk_abcdefghijklmnopqrstuvwxyz012345 şeklinde görünür. mk_ öneki, onu Bot Talk anahtarlarından (ck_) ayırır.

Kimlik doğrulama

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

/v1/chat (veya başka bir Bot Talk uç noktasına) bir mk_ anahtarı göndermek 403 key_type_not_allowed hatası döndürür. /v1/management/* uç noktasına bir ck_ anahtarı göndermek de aynı hatayı verir.

Sınırlar

• Kullanıcı başına en fazla 5 aktif Management API anahtarı
• Anahtar başına dakikada en fazla 10 istek (belirteç kovası / token bucket, 10 kapasite, yaklaşık her 6 saniyede 1 belirteç şeklinde düzenli dolum). Oluşturma sırasında daha düşük bir değere ayarlanabilir - daha düşük bir rateLimitPerMinute belirlerseniz üst sınır düşer ve dolum hızı da buna göre ölçeklenir.

İzinler

Her Yönetim anahtarı aşağıdaki üç iznin herhangi bir alt kümesini taşır. Oluşturma sırasında en az bir izin seçilmelidir; aksi takdirde istek 400 invalid_request_error ile reddedilir. Gerekli izne sahip olmayan bir anahtarla bir uç noktayı çağırmak 403 insufficient_permissions hatası döndürür.

• bot_read - GET /v1/management/bots/{bot_id} için gereklidir
• bot_management - POST /v1/management/bots ve PATCH /v1/management/bots/{bot_id} için gereklidir
• usage - GET /v1/usage için gereklidir

Gövde yapısı: yönetici arayüzü sekmelerini yansıtan iç içe bölümler

POST ve PATCH, 13 bölüme ayrılmış bir JSON gövdesi kabul eder. Her bölüm, yönetici uygulamasının Bot Settings (Bot Ayarları) kenar çubuğundaki bir alt sekmeyle eşleşir, böylece JSON anahtarları ile görünür sekmeler birbiriyle örtüşür: consent.humanSupportRequirePolicyAccept değerini API üzerinden değiştirirseniz, yönetici uygulamasındaki Consent & Privacy (Onay ve Gizlilik) sekmesinde aynı düğmenin değiştiğini görürsünüz.

• role - bot kimliği, ham prompt, yanıt uzunluğu, dil, web sitesi / şirket bağlamı (Role & Behavior sekmesi)
• conversation - karşılama mesajı, sorgu iyileştirme, konuşma sürekliliği, puanlama düğmesi + ipuçları, önerilen soru içerikleri + dinamik devam soruları (Chat Conversation sekmesi)
• chatMemory - sohbet hafızası düğmesi, özet prompt'ları, bağlam dağılımı (Summaries & Memory sekmesi)
• appearance - renkler, metinler, boyutlar, özel CSS, karşılama ekranı, önerilen soru stilleri, otomatik açılma davranışı, insan yazıyor simülasyonu, altbilgi markdown'ı (Appearance sekmesi)
• humanSupport - insanla iletişim formu (Human Contact Form sekmesi)
• leadCollection - potansiyel müşteri yakalama formu (Lead Collection sekmesi)
• liveChat - canlı sohbete aktarma (Live Chat sekmesi)
• consent - dört gizlilik politikası onay düğmesinin tümü ve onay ekranı metni (Consent & Privacy sekmesi)
• whiteLabel - logo gizleme, özel logo bağlantısı, özel alan adı barındırma (Whitelabel sekmesi)
• security - izin verilen alan adları, spam filtresi, konuşma hızı sınırları (Security sekmesi)
• voice - sesli giriş ve sesli konuşmalar: model, ses, diller, prompt, süre sınırı (Voice Conversation sekmesi)
• multilingual - çok dilli mod, temel dil, sunulan diller, bilgi tabanı dili yönetimi (Languages sekmesi)
• advanced - LLM modeli, sıcaklık (temperature), bağlam boyutu, bot mesaj sınırı, dahili yerel ayar (locale), Offer Cards (Model & Advanced sekmesi)

Yazılabilir ayarlar arasında yalnızca name en üst düzeyde yer alır, çünkü belirli bir sekmeye ait olmak yerine botu tanımlar.

Bot Settings kenar çubuğunda şu anda 16 alt sekme bulunmaktadır ve bunlardan 13'ü yukarıdaki bölümlerle eşleşir. Karşılık gelen bir bölümü olmayan üç alt sekme Flow, Actions ve Forms sekmeleridir; bunların üçü de aşağıda "API kapsamı dışındakiler" başlığı altında ele alınmıştır. Eşleşen 13 sekme şunlardır: Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation ve Languages.

İstek gövdesi ve yanıt gövdesi aynı yapıyı paylaşır. Yanıt iki ek alan içerir:

• meta - salt okunur: bot kimliği ve zaman damgaları. Bir GET yanıtını geçerli bir POST gövdesine dönüştürmek için bu alanı çıkarın.
• apiKey - yalnızca oluşturma sırasında bulunur - yeni bot için yeni üretilmiş Bot Talk API anahtarı.

Paylaşılan yapı içindeki iki alan salt okunurdur - yanıtta döndürülür, POST/PATCH isteklerinde gönderirseniz yok sayılır:

• appearance.avatarUrl - bot avatar görselinin tam nitelikli herkese açık URL'si (örneğin https://api.chatlab.com/aichat/content/avatar_xyz.png). Baytları indirmek için doğrudan bu adrese GET isteği yapın. Değiştirmek için çok parçalı (multipart) avatar parçası üzerinden yeni bir dosya yükleyin (bkz. PATCH).
• whiteLabel.whitelabelLogoUrl - White Label başlık logosunun tam nitelikli herkese açık URL'si. avatarUrl ile aynı mantıkta çalışır. Değiştirmek için çok parçalı (multipart) whitelabel_logo parçası üzerinden yeni bir dosya yükleyin (bkz. PATCH).

Her iki URL de geçerli isteğin şema + ana makine (host) + bağlam yolunu kullanır; bu nedenle White Label özel alan adlarında bu alan adını temel alarak dönerler (örneğin https://api.acme.com/aichat/content/...).

PATCH isteğinde bir bölümü atlamak için o bölüme null gönderin; bir bölüm içindeki tek bir alanı atlamak için ilgili alana null gönderin. Alan düzeyindeki null değeri saklanan bir değeri asla temizlemez - yalnızca "dokunma" anlamına gelir.

Rol ve prompt oluşturma

LLM'in gerçekte aldığı sistem prompt'u, role.role değerine bağlı olarak iki yoldan biriyle oluşturulur. Hangi kolda olduğunuzu bilmek, hangi alanların önemli olduğunu ve hangilerinin depolanıp yok sayıldığını anlamanızı sağlar.

Kol A - role.role değeri CUSTOMER_SUPPORT, SALES veya LEAD_COLLECTION_AGENT olduğunda (şablon güdümlü)

Arka uç, prompt'u yerleşik bir şablondan birleştirir ve role.rawPrompt değerini tamamen yok sayar (değer yine de bot üzerinde saklanır, sadece kullanılmaz). Şablon şunları içerir:

• role.role - rol etiketi (örneğin "Customer Support") ve otomatik olarak eklenen role özgü talimatlar
• name - açılış cümlesine eklenen bot adı
• role.language - "Auto Detect", botu kullanıcının dilini takip edecek şekilde ayarlar; diğer herhangi bir değer (örneğin "English", "Polish"), "Kullanıcı başka bir dil kullanmadığı sürece yanıtları {language} dilinde ver" şekline dönüşür
• role.responseLength - hedeflenen bir kelime sayısıyla eşleştirilir: Concise ≈ 50 kelime, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - isteğe bağlı; boş olmadığında, "{url} web sitesi kullanıcıları için" şeklinde eklenir
• role.companyDescription - isteğe bağlı; boş olmadığında, rol talimatlarından önce fazladan bir paragraf olarak başa eklenir

Çoğu bot için önerilen yol budur - role göre ayarlanmış davranışlara ve güvenlik sınırlarına doğrudan sahip olursunuz.

Kol B - role.role değeri CUSTOM olduğunda (çağıran tarafından sağlanan prompt)

Arka uç, role.rawPrompt değerini rol prompt'u olarak kullanır ve platformun sabit yanıt uzunluğu kılavuzunu sonuna ekler. Bu, role.responseLength alanından ayrıdır: isteğe bağlı Concise/Normal/Detailed ayarı CUSTOM bir rol için eklenmez. Benzer şekilde, language, websiteAddress ve companyDescription saklanır ancak bu rol prompt'una enjekte edilmez. İstenen herhangi bir dili, hedef yanıt uzunluğunu veya şirket bağlamını rawPrompt içine kendiniz dahil edin. Çalışma zamanında ek talimatlar ve bilgi tabanından getirilen bağlam da sağlanabilir, bu nedenle rawPrompt modele giden girdinin tamamı değildir. Önceden tanımlanmış rolün üslup talimatları eklenmez, ancak CUSTOM seçeneğini belirlemek tüm platform talimatlarını ortadan kaldırmaz.

CUSTOM seçeneğini yalnızca şablon güdümlü prompt kullanım durumunuza uymadığında kullanın (örneğin, çok sektöre özgü bir kimliğe, kendi güvenlik kısıtlamalarınıza veya standart dışı bir çıktı biçimine ihtiyacınız olduğunda).

Sabit listeli / kapalı küme alanları (Enum)

Enum ve kısıtlanmış alanlar, geçersiz değerleri 400 invalid_parameter ile reddeder. Diğer alanlar, kullanıcı arayüzü sabit bir liste sunsa bile düz dize (string) biçimindedir. Desteklenmeyen her dizenin reddedileceğini varsaymak yerine, belgelenen yazımı kullanın ve yükünüzü doğrulayın.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - yönetici açılır menüsündeki tam İngilizce dil adı; örneğin Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi ve yaklaşık 80 diğer dil. Değer aynen saklanır ve prompt şablonuna yerleştirilir; bu nedenle iki harfli ISO kodları (en, pl) ve liste dışı diğer değerler API tarafından reddedilmez ancak "Output in en, unless..." gibi hatalı bir talimat üretir. Oluşturma sırasında belirtilmediğinde varsayılan olarak Auto Detect olur.
• advanced.model - aşağıdaki "Yapay zeka metin modelleri" bölümüne bakın. Bu bir dizedir, istek şemasında doğrulanan bir sabit listeli değer (enum) değildir; rastgele bir model adı yerine desteklenen bir değer kullanın.
• advanced.chatContextSize - arayüzle eşleşecek şekilde 8000, 16000 veya 32000 kullanın. Hesabın maksimum sınırının üzerindeki değerler sessizce sınırlandırılır; DTO bu üç değerli kümeyi zorunlu kılmaz.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - boole (boolean) düğmesi. true, kullanıcıyı sohbete başlamadan önce potansiyel müşteri formunu doldurmaya zorlar; false, formun ne zaman gösterileceğine yapay zekanın karar vermesine izin verir (varsayılan).

Yapılandırılmış alanlar ve aralıklar

Basit dizeler veya sayılar gibi görünen ancak bilmenizde fayda olan belirli yapılara, aralıklara veya yönetici arayüzü özelliklerine sahip alanlar.

• advanced.temperature - kabul edilen aralık, yönetici arayüzündeki kaydırıcıyla eşleşecek şekilde 0.0 ile 1.0 arasıdır. Bu aralığın dışındaki değerler 400 invalid_parameter ile reddedilir.

• chatMemory.summariesToKnowledgeRatio - tam sayı yüzdesi, 10-90; arayüz 10'luk adımlar kullanır, ancak API aralıktaki tüm tam sayıları kabul eder. Varsayılan 50'dir. Bellek etkinleştirildiğinde ve bağlam 8k'dan büyük olduğunda, model bağlamının tamamını değil, prompt/son konuşma için ayrılan payın ardından kalan bilgi ve bellek bütçesini böler. 8k bağlamda bu ayar ile herhangi bir özet bütçesi ayrılmaz.

• liveChat.schedule - iletim sırasında iç içe bir JSON nesnesi değil, dize olarak kodlanmış JSON (JSON encoded as a string) biçimindedir. Sunucu ham dizeyi aynen saklar; yönetici arayüzü çalışma planı düzenleyicisini oluştururken bunu istemci tarafında ayrıştırır. Ayrıştırıldıktan sonra dize, haftanın her günü için bir giriş ve bir timezone anahtarı içerecek şekilde biçimlenir:

  • her gün anahtarı (monday-sunday), 24 saatlik zaman diliminde {enabled: boolean, from: "H:MM", to: "H:MM"} yapısına eşlenir
  • timezone, bir IANA bölge adıdır (örneğin "Europe/Warsaw", "America/New_York")

  Örnek değer (dıştaki tırnak işaretlerine ve kaçış karakterli iç tırnak işaretlerine dikkat edin - bu, iç içe bir nesne değil, tek bir dize alanıdır):

  "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}"
  

  Listelenen saatlerin dışında, ziyaretçiye liveChat.outOfHoursMessage gösterilir ve canlı sohbete aktarma engellenir. İç yapı doğrulaması yalnızca yönetici arayüzünde istemci tarafında çalışır - bozuk JSON veya tanınmayan anahtarlar API tarafından yalnızca bir dize olarak kabul edilir ve daha sonra bir kullanıcı botu yönetici panelinde açtığında bir görselleştirme hatası olarak ortaya çıkar. Göndermeden önce kendi tarafınızda yapıyı doğrulayın.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - conversation.conversationRatingEnabled=true olduğunda 👍 / 👎 konuşma puanlama kontrollerinde gösterilen kısa etiketler. Varsayılan metin "I like the response" / "I don't like the response" şeklindedir. Son kullanıcılar tarafından görülebilir.

• whiteLabel.hideRoboAssistLogo - hesap limitlerinize tabi White Label özelliği. Altbilgideki "Powered by ChatLab" satırını gizler. Hesabınız White Label özelliğini içermiyorsa, değer saklanır ancak yok sayılır ve altbilgi her zaman gösterilir.

• whiteLabel.whitelabelLogoLink - hesap limitlerinize tabi White Label özelliği. hideRoboAssistLogo=true olduğunda ve whitelabel_logo çok parçalı (multipart) alanı aracılığıyla özel bir logo dosyası yüklendiğinde özel logonun tıklama hedefi URL'si.

• appearance.simulateHumanTypingDelay - saniye (milisaniye değil), 0-200 arası tam sayı. simulateHumanTyping=true olduğunda ardışık bot mesaj balonları arasındaki duraklama süresi. Varsayılan 5.

• appearance.autoOpenChatDelaySeconds - saniye, tam sayı. autoOpenChat=true ve autoOpenChatDelay=true olduğunda pencere bileşeninin otomatik olarak açılmasından önceki gecikme.

• advanced.internalLocale - ll_CC biçiminde IETF yerel ayar bölge kodu (alt çizgi ile, kısa çizgili ll-CC DEĞİL). Kabul edilen değerler yaklaşık 95 yerel ayardan oluşan sabit bir listeden gelir: en_US, pl_PL, de_DE, fr_FR, es_ES, it_IT, pt_PT, nl_NL, ru_RU, zh_CN, zh_TW, ja_JP, ko_KR, ar_SA, hi_IN, tr_TR, cs_CZ, da_DK, fi_FI, sv_SE, no_NO, el_GR, he_IL ve daha fazlası. Tek başına iki harfli bir kod ("en") veya BCP-47 ("en-US") göndermek izin verilenler listesinde yer almaz. Varsayılan en_US. Bu, role.language (botun konuşma çıktısı dili) alanından farklı olarak, pencere bileşeni arayüzündeki tarih/sayı biçimlendirmesi için kullanılan yerel ayardır.

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - tam sayılar (JSON sayısı olarak gönderin, örneğin "30" değil 30). Oturum tabanlı bu sınırı devre dışı bırakmak için mesaj sınırını 0 olarak ayarlayın. Etkinleştirirken pozitif bir süre belirtin. Arka uç, ziyaretçiye security.talkMessagesRateLimitHitMessage mesajını göstermeden önce saniye cinsinden süre başına oturum başına N mesaj sınırını uygular.

• advanced.botMessagesLimit - tam sayı (JSON sayısı, örneğin 1000). 0, hesap kredi bütçesi geçerli olmaya devam ederken bot başına ek bir sınır olmadığı anlamına gelir; aksi takdirde 1.000'in katı olmalıdır (1000, 2000, 10000, ...). 100 veya 1500 gibi değerler 400 invalid_parameter ile reddedilir. Bu, konuşma başına mesaj sayısı değil, aylık bot kredi sınırıdır. Eşleyici bu değeri hesap bütçesine göre sınırlandırmaz; hesabın bütçesi gerçek kullanımı kısıtlamaya devam eder.

Yapay zeka metin modelleri (advanced.model)

Settings > Model & Advanced (Ayarlar > Model ve Gelişmiş) bölümünde istediğiniz modelle yapılandırılmış bir botu okurken advanced.model içinde dönen tam model tanımlayıcısını kullanın. Geçerli oluşturma varsayılanı 5.6-LUNA modelidir. Tanımlayıcılar büyük/küçük harfe duyarlıdır ve görünen adlardan farklıdır; örneğin 5.6-LUNA, GPT 5.6-luna olarak gösterilir.

Model kataloğu zamanla değişir. İstek şeması bir dize kabul ediyor diye rastgele bir dizenin veya bir sağlayıcının herkese açık model kimliğinin desteklendiği sonucunu çıkarmayın. Chatbot'u yayına almadan önce kaydedilen yapılandırmayı tekrar okuyun ve ortaya çıkan botu test edin.

Alan referansı (tam istek şeması)

Desteklenen bölümler ve alanlar, türleri ve önemli kısıtlamalarıyla birlikte aşağıda listelenmiştir. PATCH semantiği: atlanan (veya null olarak gönderilen) herhangi bir alan, kayıtlı değeri değiştirmeden bırakır. Aynı yapı yanıt için de geçerlidir (multipart ikili içerik hariç; her yanıtta salt okunur meta bloğu ve yalnızca oluşturma yanıtında apiKey eklenir).

En üst düzey

Alan	Tür	Kısıtlama	Açıklama
name	string	maks 150, oluşturmada zorunlu	Botun görünen adı
role	object		Bkz. § role
conversation	object		Bkz. § conversation
chatMemory	object		Bkz. § chatMemory
appearance	object		Bkz. § appearance
humanSupport	object		Bkz. § humanSupport
leadCollection	object		Bkz. § leadCollection
liveChat	object		Bkz. § liveChat
consent	object		Bkz. § consent
whiteLabel	object		Bkz. § whiteLabel
security	object		Bkz. § security
advanced	object		Bkz. § advanced

Yalnızca yanıtta bulunan eklemeler:

• meta: { id, createdAt, updatedAt } - salt okunur.
• apiKey - string, yalnızca POST /v1/management/bots yanıtında bulunur - yeni bot için yeni oluşturulmuş Bot Talk anahtarıdır, tam olarak bir kez döndürülür.

§ role

Alan	Tür	Kısıtlama	Açıklama
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Persona ön ayarı; prompt şablonunu seçer (bkz. "Rol ve prompt yapısı")
language	string	tam İngilizce dil adı (English, Polish, ...) veya Auto Detect	Prompt şablonuna aktarılan birincil dil
responseLength	string	∈ {Concise, Normal, Detailed}	İstenen AI yanıt ayrıntı düzeyi
websiteAddress	string		Prompt bağlamı için kullanılan web sitesi
companyDescription	string		Prompt bağlamı için kullanılan şirket açıklaması
rawPrompt	string		Özel sistem promptu - yalnızca role=CUSTOM olduğunda harfi harfine kullanılır

§ conversation

Alan	Tür	Kısıtlama	Açıklama
welcomeMessage	string		Açılışta ziyaretçiye gösterilen ilk mesaj
queryRefinementEnabled	boolean		Doğruysa, RAG getirme işleminden önce ziyaretçinin sorusunu netleştirir
conversationContinuityEnabled	boolean		Doğruysa, geri dönen ziyaretçiler son görüşmelerine devam eder
conversationRatingEnabled	boolean		Doğruysa, olumlu/olumsuz görüşme değerlendirme kontrollerini gösterir
positiveRatingTooltip	string		Olumlu değerlendirme düğmesindeki araç ipucu
negativeRatingTooltip	string		Olumsuz değerlendirme düğmesindeki araç ipucu
suggestedQuestions	string		Satır sonuyla ayrılmış önerilen sorular / sohbet başlatıcılar
dynamicSuggestedFollowups	boolean		Doğruysa, AI her yanıttan sonra takip önerileri sunar
positiveRatingMessage	string		Olumlu geri bildirimden sonra gösterilen mesaj
negativeRatingMessage	string		Olumsuz geri bildirimden sonra gösterilen mesaj
hideSuggestedQuestionsAfterFirstUse	boolean		İlk kullanımdan sonra statik önerileri gizler
dynamicFollowupsAutoIcons	boolean		Doğruysa, AI dinamik takip önerileri için otomatik olarak emoji simgeleri seçer

§ chatMemory

Alan	Tür	Kısıtlama	Açıklama
enabled	boolean		Sohbet hafızası özelliği için ana açma/kapatma anahtarı
summaryConversationsEnabled	boolean		Görüşme başına özetleri kaydeder
conversationSummaryPrompt	string		Her görüşmeyi özetlemek için kullanılan özel prompt
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Varsayılan mı yoksa özel özet promptunun mu kullanılacağı
clientSummaryPrompt	string		Müşteriyi görüşmeler genelinde özetlemek için kullanılan özel prompt
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Varsayılan ile özel müşteri profili promptu karşılaştırması
summariesToKnowledgeRatio	int	10-90 (Arayüz adımı 10)	8k üzerindeki bağlamlarda özetlere ayrılan mevcut bilgi/hafıza bütçesinin yüzdesi (%)

§ appearance

Alan	Tür	Kısıtlama	Açıklama
launcherLabelLine1	string	maks 60	Başlatıcı metninin ilk satırı
launcherLabelLine2	string	maks 60	Başlatıcı metninin ikinci satırı
launcherTextColor	string		Başlatıcı metin rengi
launcherDismissEnabled	boolean		Başlatıcının kapatılmasına izin verir
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Widget yazı tipi ailesi
chatDrawerEnabled	boolean		Çekmece (drawer) görünümünü etkinleştirir
launcherColor	string (hex)		Başlatıcı (sohbet simgesi) arka plan rengi
headerColor	string (hex)		Sohbet başlığı arka plan rengi
titleColor	string (hex)		Sohbet üst bilgisi başlık rengi
subtitleColor	string (hex)		Sohbet üst bilgisi alt başlık rengi
clientMessageBubbleColor	string (hex)		Ziyaretçi mesaj balonu rengi
clientMessageTextColor	string (hex)		Ziyaretçi mesaj metni rengi
responseMessageBubbleColor	string (hex)		Bot yanıt balonu rengi
responseMessageTextColor	string (hex)		Bot yanıt metni rengi
chatSubheader	string		Sohbet başlığının altında gösterilen slogan
senderPlaceholder	string		Mesaj giriş alanındaki yer tutucu metin
resetConversationTooltip	string		"Sohbeti sıfırla" düğmesindeki araç ipucu
chatAlignment	string (enum)	∈ {left, right}	Sohbetin ekranın hangi tarafına sabitleneceği
launcherBottomMargin	int	0-500	Başlatıcının alt kenardan uzaklığı (px)
launcherSideMargin	int	0-500	Başlatıcının yan kenardan uzaklığı (px)
displayShadow	boolean		Widget altında alt gölge
customCss	string		Widget iframe'ine eklenen ham CSS
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Bot mesajlarındaki bağlantıların nasıl açılacağı
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Simge durumuna küçültülmüş durum: başlatıcı simgesi, kompakt gönderici çubuğu veya hap (pill)
chatDesktopWidthPx	int		Masaüstü widget genişliği
chatDesktopHeightPx	int		Masaüstü widget yüksekliği
chatMobileSizePercent	int		Görünüm alanı yüzdesi (%) olarak mobil widget boyutu
messageFontSize	int		Mesaj metni yazı tipi boyutu (px)
showChatbotBubblesDesktop	boolean		Masaüstünde kayan ön izleme balonlarını gösterir
showChatbotBubblesMobile	boolean		Mobilde kayan ön izleme balonlarını gösterir
chatbotBubblesDelaySeconds	int		Ön izleme balonları görünmeden önceki gecikme (saniye)
launcherIconFullSize	boolean		Özel başlatıcı simgesini içe gömülü yerine kenardan kenara işler
welcomeScreenEnabled	boolean		Doğrudan sohbete geçmek yerine Welcome Screen (Karşılama Ekranı) gösterir
welcomeScreenQuestionsLabel	string		Karşılama ekranında önerilen soruların üzerindeki etiket
welcomeScreenHideHumanContactForm	boolean		Welcome Screen gösterilirken üst bilgideki insan iletişim formu eylemini gizler. Ziyaretçinin ilk mesajından sonra yeniden görünür. 2026-09-02 tarihinden önce oluşturulan botlar varsayılan olarak true değerini alır
welcomeScreenHideLiveChat	boolean		Welcome Screen gösterilirken üst bilgideki canlı sohbet eylemini gizler. Ziyaretçinin ilk mesajından sonra yeniden görünür. 2026-09-02 tarihinden önce oluşturulan botlar varsayılan olarak true değerini alır
headerActionsLayout	string	ICONS veya DROPDOWN	Canlı sohbet ve insan iletişim formunun sohbet üst bilgisinde nasıl sunulacağı: ICONS (her biri için ayrı bir simge) veya DROPDOWN (üst bilgi menüsünde gruplandırılmış). 2026-09-02 tarihinden önce oluşturulan botlar varsayılan olarak ICONS değerini alır
stackSuggestedQuestions	boolean		Önerilen soruları dikey olarak sıralar (yan yana yerine)
suggestedQuestionsFontSize	int		Önerilen soru butonlarının yazı tipi boyutu (px)
suggestedQuestionsTextColor	string (hex)		Önerilen soru butonu metin rengi
suggestedQuestionsBackgroundColor	string (hex)		Önerilen soru butonu arka plan rengi
autoOpenChat	boolean		Sohbeti masaüstünde otomatik olarak açar
autoOpenChatOnMobiles	boolean		Sohbeti mobilde otomatik olarak açar
autoOpenChatDelay	boolean		Otomatik açılmadan önce gecikme kullanır
autoOpenChatDelaySeconds	int		Otomatik açılma gecikmesi (saniye)
simulateHumanTyping	boolean		Bot yanıtını yazma animasyonuyla balonlara böler
simulateHumanTypingDelay	int	0-200	Balon mesajları arasındaki gecikme (saniye)
footerMarkdown	string	maks 255	Sohbetin altında gösterilen özel alt bilgi markdown'ı
avatarUrl	string	salt okunur	Avatarın tam nitelikli genel URL'si; değiştirmek için multipart avatar parçası üzerinden yükleyin

POST/PATCH üzerinde multipart: avatar (dosya parçası). GET / yanıt gövdeleri dosya içeriğini atlar - aktarım sırasında yalnızca URL yer alır.

§ humanSupport

Alan	Tür	Kısıtlama	Açıklama
enabled	boolean		Human Support (İnsan Desteği) akışı açma/kapatma anahtarı
email	string	enabled=true olduğunda zorunlu (oluşturmada katı)	İnsan desteği e-postalarını alan adres
dialogMessage	string		Formun üzerinde gösterilen teşvik mesajı
thankYouMessage	string		Gönderimden sonra gösterilen onay mesajı
emailMessageSubjectTemplate	string		Temsilciye gönderilen e-posta için konu şablonu
emailMessageContentTemplate	string		Temsilciye gönderilen e-posta için gövde şablonu
emailPlaceholder	string		E-posta giriş alanındaki yer tutucu
messagePlaceholder	string		Mesaj metin alanındaki yer tutucu
emailWithConversationContent	boolean		Doğruysa, e-posta gövdesine görüşme dökümünü dahil eder
customFormId	long	mevcut bir özel formun kimliği	Yerleşik iletişim formunu özel bir formla değiştirir. Oluşturma sırasında atlanırsa yerleşik form kullanılır; PATCH işleminde null, mevcut seçimi değiştirmeden bırakır
customFormMapping	string	JSON kodlu dize	Özel form alanlarını insan desteği e-posta alanlarıyla eşler

requirePolicyAccept burada değil, consent.humanSupportRequirePolicyAccept altındadır.

§ leadCollection

Alan	Tür	Kısıtlama	Açıklama
enabled	boolean		Müşteri adayı (lead) formu açma/kapatma anahtarı
nameEnabled	boolean		İsim toplar
nameLabel	string		İsim giriş alanındaki etiket
emailEnabled	boolean		E-posta toplar
emailLabel	string	enabled=true VE emailEnabled=true olduğunda zorunlu (oluşturmada katı)	E-posta giriş alanındaki etiket
phoneEnabled	boolean		Telefon toplar
phoneLabel	string	enabled=true VE phoneEnabled=true olduğunda zorunlu (oluşturmada katı)	Telefon giriş alanındaki etiket
leaveDetailsMessage	string	enabled=true olduğunda zorunlu (oluşturmada katı)	Ziyaretçiyi iletişim bilgilerini bırakmaya teşvik eden mesaj
thankYouMessage	string	enabled=true olduğunda zorunlu (oluşturmada katı)	Gönderimden sonra gösterilen onay mesajı
requireBeforeNewConversation	boolean		true ise sohbet başlamadan önce form gönderilmelidir; false ise formun ne zaman gösterileceğine AI karar verir
emailNotificationEnabled	boolean		Her müşteri adayı toplandığında hesap sahibine e-posta gönderir
emailNotificationAddress	string		Bildirim alıcısı (varsayılan olarak hesap e-postasıdır)
emailWithConversationContent	boolean		Doğruysa, bildirime görüşme dökümünü dahil eder

| customFormId | long | mevcut bir özel formun kimliği | Yerleşik müşteri adayı formunu özel bir formla değiştirir. Oluşturma sırasında atlanırsa yerleşik form kullanılır; PATCH işleminde null, mevcut seçimi değiştirmeden bırakır | | customFormMapping | string | JSON kodlu dize | Özel form alanlarını isim / e-posta / telefon ile eşler |

Alanlar arası oluşturmada katı kuralı: enabled=true olması durumunda emailEnabled veya phoneEnabled seçeneklerinden en az biri gereklidir. requirePolicyAccept burada değil, consent.leadCollectionRequirePolicyAccept altındadır.

§ liveChat

Alan	Tür	Kısıtlama	Açıklama
enabled	boolean		Live Chat (Canlı Sohbet) özellik anahtarı
infoMessage	string		Aktarım öncesi açıklama mesajı
startMessage	string		Canlı oturum başladığında gösterilen mesaj
endMessage	string		Canlı oturum sona erdiğinde gösterilen mesaj
nameLabel	string		Canlı sohbet ön formundaki isim giriş alanı etiketi
emailLabel	string		Canlı sohbet ön formundaki e-posta giriş alanı etiketi
schedule	string	JSON kodlu dize (haftanın günü anahtarları + from/to + timezone)	Canlı sohbet çalışma takvimi - tam yapı için bkz. "Yapılandırılmış alanlar ve aralıklar"
outOfHoursMessage	string		Çalışma saatleri dışında gösterilen mesaj
closeModalMessage	string		"Canlı sohbet kapatılsın mı?" modalının başlığı
closeModalConfirmLabel	string		Kapatma modalındaki onay düğmesi etiketi
closeModalCancelLabel	string		Kapatma modalındaki iptal düğmesi etiketi
closeModalTooltipText	string		Sohbeti kapatma ögesindeki araç ipucu
operatorHasJoinedLabel	string		Bir temsilci katıldığında gösterilen etiket
operatorDidNotJoinInTimeLabel	string		Zaman aşımı süresi içinde hiçbir temsilci katılmadığında gösterilen etiket
waitingForOperatorToJoinLabel	string		Temsilci beklenirken gösterilen etiket
waitingForOperatorSeconds	int		Bir temsilcinin yanıt vermesi için zaman aşımı süresi (saniye)
redirectToHumanSupportForm	boolean		Doğruysa, hiçbir temsilci yanıt vermediğinde Human Support formuna yönlendirir
requireAdminOnline	boolean		Durum ayarlarına göre uygun bir temsilci bulunmasını zorunlu kılar
presenceMode	string		Durum modu; arayüzde yapılandırılmış bir bottan alınan değeri kullanın
hideHumanSupportWhenLiveChatAvailable	boolean		Canlı sohbet kullanılabilir olduğunda iletişim formunu gizler
missedEmailEnabled	boolean	varsayılan true	Bir canlı sohbet isteği yanıtsız kaldığında bot sahibine e-posta gönderir. Eski botlarda ayarlanmamıştır, bu da etkin olarak yorumlanır

requirePolicyAccept burada değil, consent.liveChatRequirePolicyAccept altındadır.

§ consent

Alan	Tür	Kısıtlama	Açıklama
newConversationRequirePolicyAccept	boolean		Yeni bir sohbete başlamadan önce gizlilik politikası onayını zorunlu kılar
humanSupportRequirePolicyAccept	boolean		İnsan desteği formunu göndermeden önce gizlilik politikası onayını zorunlu kılar
leadCollectionRequirePolicyAccept	boolean		Müşteri adayı toplama formunu göndermeden önce gizlilik politikası onayını zorunlu kılar
liveChatRequirePolicyAccept	boolean		Canlı sohbet oturumu başlatmadan önce gizlilik politikası onayını zorunlu kılar
newConversationConsentDescription	string		Sohbet başlangıcındaki onay ekranı için giriş metni
privacyPolicyConsentCheckboxLabel	string		Onay onay kutusunun yanındaki etiket (genellikle gizlilik politikasına bir bağlantı içerir)

§ whiteLabel

Alan	Tür	Kısıtlama	Açıklama
hideRoboAssistLogo	boolean	White Label özelliği; hesap limitlerine tabidir	Alt bilgideki varsayılan ChatLab logosunu gizler
whitelabelLogoLink	string	White Label özelliği; hesap limitlerine tabidir	Özel alt bilgi logosunun yönlendirdiği URL
assignToCustomDomain	boolean	CUSTOM_DOMAIN özelliğiyle sınırlıdır	Sohbeti yapılandırılan özel etki alanında barındırır
whitelabelLogoUrl	string	salt okunur	White Label logosunun tam nitelikli genel URL'si; değiştirmek için multipart whitelabel_logo parçası üzerinden yükleyin

POST/PATCH üzerinde multipart: whitelabel_logo (dosya parçası). GET / yanıt gövdeleri dosya içeriğini atlar - aktarım sırasında yalnızca URL yer alır.

§ security

Alan	Tür	Kısıtlama	Açıklama
allowedDomains	string		Widget'ın yerleştirilmesine izin verilen etki alanlarının virgülle ayrılmış listesi (boş = beyaz liste yok)
spamFilterEnabled	boolean		Gelen mesajlarda bot başına spam filtresini etkinleştirir
countryFilterMode	string	BLACKLIST veya WHITELIST	Ülke listelerinin nasıl yorumlanacağı. Listelerin kendisi yalnızca yöneticilere özeldir
talkMessagesRateLimit	int	>= 0; 0 devre dışı bırakır	İstek sınırı penceresinde izin verilen maksimum kullanıcı mesajı sayısı
talkMessagesRateLimitDurationSeconds	int	>= 0	İstek sınırı penceresi süresi (saniye)
talkMessagesRateLimitHitMessage	string		İstek sınırına ulaşıldığında ziyaretçiye gösterilen mesaj

§ voice

Alan	Tür	Kısıtlama	Açıklama
inputEnabled	boolean		Ziyaretçinin mesajları dikte etmesine izin verir (sesten metne)
conversationEnabled	boolean	planda ses özelliğinin bulunmasını gerektirir	Tam sesli görüşmeleri etkinleştirir
voiceId	string	sağlayıcıya özel ses kimliği (örn. alloy)	Hangi sentetik sesin konuşacağı
model	string	örn. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Ses modeli. Dakika başına ücretlendirilir, ücretler modele göre değişir
turnDetection	string	sağlayıcıya özel	Karşılıklı konuşma (turn-taking) modu
audioPrompt	string		Yalnızca sesli bölümler için kullanılan ek sistem promptu
welcomeMessage	string		Sesli açılış cümlesi
language	string	dil kodu	Birincil ses dili
additionalLanguages	string	virgülle ayrılmış dil kodları	Sesli asistanın kabul ettiği ek diller
maxDurationSeconds	int		Tek bir sesli görüşme için kesin üst sınır
maxDurationMessage	string		Üst sınıra ulaşıldığında gösterilen mesaj

§ multilingual

Alan	Tür	Kısıtlama	Açıklama
enabled	boolean		Çok dilli mod anahtarı
mode	string	AUTODETECT veya FIXED_LIST	Botun yanıt dilini nasıl seçeceği
baseLanguage	string	dil kodu	Botun kendi metinlerinin yazıldığı dil
languages	string	virgülle ayrılmış dil kodları	Ziyaretçiye sunulan diller
knowledgeLanguageMode	string	NONE, MAIN, veya DYNAMIC	Diğer dillerdeki bilgi tabanı içeriğinin nasıl ele alınacağı
knowledgeLanguageFallback	string	dil kodu	Eşleşme bulunamadığında kullanılan dil

§ advanced

Alan	Tür	Kısıtlama	Açıklama
model	string	hesap limitlerine tabidir; yukarıdaki "AI metin modelleri" bölümüne bakın	LLM tanımlayıcısı (örn. 5.6-LUNA)
temperature	decimal	0.0-1.0	Örnekleme sıcaklığı (arayüzdeki kaydırıcıyla eşleşir)
chatContextSize	int	∈ {8000, 16000, 32000}; sessizce hesap limitinize kırpılır	Talimatlar, geçmiş ve bilgi tabanı dahil yapılandırılmış bağlam bütçesi
botMessagesLimit	long	0 veya 1000'in katı (örn. 1000, 2000, 10000)	Aylık bot mesaj kredisi üst sınırı (0 = ek bot sınırı yok; hesap bütçesi geçerliliğini korur)
internalLocale	string	ll_CC biçiminde yerel ayar kodu	Widget arayüz etiketleri için yerel ayar (role.language alanından farklıdır)
productsViewEnabled	boolean		Doğruysa, e-ticaret Offer Cards (Teklif Kartları) ögelerini sohbet içinde gösterir
includeProductsInKnowledgeBase	boolean		Doğruysa, ürün kataloğunu bilgi tabanının bir parçası olarak dizine ekler

API kapsamı dışındakiler

Yönetici kullanıcı arayüzü, Management API'nin bu sürümünde kasıtlı olarak kullanıma sunulmayan birkaç alanı barındırır:

• Eğitim ve silme - bu uç noktalar tüm botları listelemez, eğitim veri kümelerini yönetmez veya botları silmez. Bu iş akışları için uygulamayı kullanın.
• Flow sekmesi - görsel Conversation Flow (Görüşme Akışı) düzenleyicisi (aşamalar ve geçişler). Management API aracılığıyla sunulmaz.
• Actions sekmesi - yönetilen e-ticaret / rezervasyon entegrasyonları, AI Search ve özel API işlevleri. Araç çağırma hiçbir zaman Management API'nin bir parçası olmamıştır.
• Özel form oluşturucunun kendisi - özel formlar oluşturma ve düzenleme özelliği sunulmaz. Ancak mevcut bir formu leadCollection.customFormId ve humanSupport.customFormId aracılığıyla bir bota bağlayabilirsiniz.
• Özel sohbeti aç / kapat simgeleri - customLauncherIconVisible, openChatIcon, closeChatIcon. API yalnızca ana avatar ve whitelabel_logo multipart parçalarını sunar.
• IP ve ülke listeleri - kayıtların kendisi yalnızca yöneticilere özeldir. Yalnızca yorumlama modu security.countryFilterMode aracılığıyla kullanıma sunulur.

Uç noktalar

POST /v1/management/bots

Yeni bir bot oluşturun. Eşdeğer iki Content-Type kabul edilir; hangisi daha kolaysa onu seçin.

Mod A - düz JSON (aynı istek içinde avatar / logo yüklemeniz gerekmediğinde önerilir):

• Content-Type: application/json
• İstek gövdesi doğrudan bot yapılandırma JSON'ıdır (data sarmalayıcısı yoktur)
• Dosyalar (avatar / logo) daha sonra Mod B kullanılarak ikinci bir PATCH ile yüklenebilir

Mod B - multipart/form-data (aynı istek içinde dosya yüklerken kullanın):

• Content-Type: multipart/form-data; boundary=...
• data JSON parçası (zorunlu, Content-Type: application/json) - yukarıda açıklanan iç içe yapıda bot yapılandırması
• avatar dosya parçası (isteğe bağlı) - bot avatar görseli
• whitelabel_logo dosya parçası (isteğe bağlı) - White Label logosu (yalnızca hesabınız White Label özelliğini içeriyorsa geçerlidir)

JSON içinde yalnızca name zorunludur; diğer tüm alanlar yönetici kullanıcı arayüzü sihirbazının ayarlayacağı varsayılan değerleri alır.

Örnek istek gövdesi

Bu, her bölümün doldurulduğu azami data JSON'ıdır. Yalnızca ilgilendiğiniz bölümleri gönderin; geri kalan her şey varsayılan değerleri alır.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Kendi hata mesajlarına sahip doğrulama kuralları:

• name - zorunlu, en fazla 150 karakter
• advanced.temperature - 0.0 ile 1.0 arasında
• chatMemory.summariesToKnowledgeRatio - 10 ile 90 arasında tam sayı (yüzde, 10 adımlı)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - 0 ile 500 arasında
• appearance.footerMarkdown - en fazla 255 karakter
• humanSupport.enabled=true için humanSupport.email değerinin tanımlanmış olması gerekir
• leadCollection.enabled=true için leadCollection.emailEnabled veya leadCollection.phoneEnabled değerlerinden en az birinin true olması gerekir; hangi kanal açıksa etiketiyle birlikte leaveDetailsMessage ve thankYouMessage alanları da zorunludur
• advanced.chatContextSize, hesabın desteklediği maksimum bağlam boyutuna göre sınırlandırılır. Diğer sayısal alanların otomatik olarak sınırlandırıldığını varsaymayın.

Sunucuda değeri null olan alanlar JSON gövdesine dahil edilmez - ağ üzerinden yalnızca null olmayan değerlere sahip alanlar taşınır.

Örnek yanıt gövdesi (201)

İstekle aynı yapıya ek olarak, en üst düzeyde salt okunur meta bloğu ve tek seferlik apiKey bulunur. İlgili multipart parçaları yüklendiğinde salt okunur dosya URL'leri (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) sunucu tarafından doldurulur.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

apiKey alanı yalnızca oluşturma sırasında görünür; bu alan yeni bota bağlı, yeni oluşturulmuş Bot Talk anahtarıdır. Düz metin bir kez gösterilir ve daha sonra API'den tekrar alınamaz; bu anahtarı kendi tarafınızda hemen saklayın.

Location yanıt başlığı, yeni botun URL'sini taşır (/v1/management/bots/{id}).

Curl örnekleri

Mod A - düz JSON (en basiti):

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}}'

Mod B - avatar içeren multipart:

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}};type=application/json' \
  -F 'avatar=@./avatar.png'

GET /v1/management/bots/{bot_id}

Sahip olduğunuz bir botun mevcut yapılandırmasını döndürün.

Curl örneği

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..."

Örnek yanıt gövdesi (200)

Tek seferlik apiKey hariç, POST yanıtıyla aynı yapıdadır. meta bloğu dahildir. Bot mevcut değilse veya hesabınıza ait değilse 404 not_found_error döndürür.

Mevcut avatar ve White Label logosu, bu isteğe yanıt veren şema + ana makine + bağlam yolu kökünde tam nitelikli salt okunur URL'ler (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) olarak sunulur. Doğrudan bu URL'lere GET isteği atarak baytları alın; her iki dosyayı da değiştirmek için PATCH işleminde multipart avatar / whitelabel_logo parçası aracılığıyla yeni bir dosya yükleyin. Bu URL alanları bir istek gövdesinde gönderilirse yok sayılır.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Bir botu klonlama

POST /v1/management/bots istek gövdesi ile GET /v1/management/bots/{bot_id} yanıt gövdesi aynı yapıya sahiptir; bu nedenle klonlama üç adımlı bir işlem hattıdır: kaynak botu GET ile alın, sunucu tarafından yönetilen kimlik alanlarını temizleyin, sonucu POST ile gönderin.

1. Kaynak botu GET ile alın.

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -o source-bot.json

2. En üst düzeydeki meta bloğunu temizleyin. meta nesnesi (id, createdAt, updatedAt) sunucu tarafından yönetilir ve salt okunurdur - bunu POST gövdesinde bırakmak bir zarara yol açmaz (sunucu bunu yok sayar), ancak kaldırmak amacınızı netleştirir ve veri yükünü temiz tutar. İsteğe bağlı olarak, klonun kaynaktan ayırt edilebilmesi için name değerini düzenleyin.

jq 'del(.meta) | .name = "Helpdesk Bot (clone)"' source-bot.json > clone-body.json

3. Klonu oluşturmak için temizlenmiş gövdeyi POST ile gönderin. Tüm gövde yapısı ve doğrulama kuralları için yukarıdaki POST /v1/management/bots referansına bakın.

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d @clone-body.json

Yanıt, yeni botun meta.id değerinin yanı sıra yeni oluşturulmuş bir apiKey (klon için Bot Talk anahtarı) içerir. Düz metin halindeki apiKey yalnızca bu oluşturma yanıtında döndürülür - yanıt gövdesini silmeden önce bunu kopyalayın; daha sonra tekrar alınamaz.

Bu işlem desteklenen ayarları kopyalar, tamamen eğitilmiş bir chatbotu değil. Eğitim içeriği, sohbet geçmişi, entegrasyonlar/eylemler, Flow ve form tanımları bu uç noktalar tarafından klonlanmaz. Bunları uygulamada ayrı olarak yapılandırın.

Ek uyarılar:

• Dosyalar klonlanmaz. appearance.avatarUrl ve whiteLabel.whitelabelLogoUrl alanları salt okunurdur ve kaynak botun dosyalarını işaret eder. Klonda aynı avatara veya white-label logosuna ihtiyacınız varsa, kaynak URL'lerden baytları indirin ve bunları multipart avatar / whitelabel_logo parçaları olarak yükleyin - bunu oluşturma POST işleminde (Mod B) ya da ardından gelen bir PATCH çağrısında yapabilirsiniz.
• Bot Talk anahtarları klonlanmaz. Her botun kendine ait bir Bot Talk anahtar havuzu vardır. Oluşturma POST işlemi tarafından döndürülen tek apiKey, otomatik olarak oluşturulan tek anahtardır; gerekirse botun API sekmesinden ek anahtarlar oluşturun.

PATCH /v1/management/bots/{bot_id}

Sahip olduğunuz bir botun bir veya daha fazla alanını güncelleyin. Yalnızca JSON içinde bulunan bölümler / alanlar değiştirilir; atlanan (veya null olarak gönderilen) her şey olduğu gibi bırakılır. Gönderilen bir bölüm içindeki her alan için kısmi güncelleme mantığı geçerlidir.

İki eşdeğer Content-Type kabul edilir (POST ile aynıdır):

Mod A - düz JSON (yalnızca ayarları güncellerken önerilir):

• Content-Type: application/json
• İstek gövdesi, yama JSON'ının kendisidir (data sarmalayıcısı yoktur)

Mod B - multipart/form-data (dosya yüklerken kullanın):

• data JSON parçası (isteğe bağlı) - yama verisi. Yalnızca alanları değiştirmek istiyorsanız gönderin. Yalnızca bir avatar veya logo yüklemek istiyorsanız tamamen atlayın.
• avatar dosya parçası (isteğe bağlı) - avatarı değiştirir
• whitelabel_logo dosya parçası (isteğe bağlı) - white-label logosunu değiştirir (yalnızca hesabınız white-label özelliğini içeriyorsa geçerlidir)

PATCH çağrısında üç parçanın tümü de isteğe bağlıdır, ancak çağrının anlamlı olması için en az birinin bulunması gerekir.

Örnek istek gövdesi (birden fazla bölüm)

POST /v1/management/bots tarafından kabul edilen herhangi bir alan burada da gönderilebilir. Aşağıdaki örnek desteklenen tüm alanları değil, birkaç bölümü göstermektedir; pratikte yalnızca değiştirmek istediğiniz anahtarları gönderirsiniz (aşağıdaki "En küçük kısmi güncelleme" bölümüne bakın) - atlanan (veya null olarak gönderilen) her anahtar, kayıtlı değerine dokunulmadan bırakılır.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

En küçük kısmi güncelleme

Tam olarak değiştirilmesini istediğiniz anahtarları göndererek tek bir alanı PATCH ile güncelleyin - diğer her şey korunur.

{
  "appearance": {
    "launcherColor": "#abcdef"
  }
}

Curl örnekleri

Mod A - düz JSON (en basiti):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance":{"launcherColor":"#abcdef"}}'

Mod B - multipart (avatar / logo değiştirilirken):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"appearance":{"launcherColor":"#abcdef"}};type=application/json' \
  -F 'avatar=@./new-avatar.png'

Mod B - yalnızca avatarı değiştirme (alan değişikliği yok):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'avatar=@./new-avatar.png'

Yanıt gövdesi (200)

GET /v1/management/bots/{bot_id} ile aynı yapıdadır - yama uygulandıktan sonra botun meta bloğu dahil tüm yapılandırmasını içerir. apiKey alanı bulunmaz. Bot mevcut değilse veya hesabınıza ait değilse 404 not_found_error döndürür.

Aşağıdaki örnek, GET örneğindeki bota yukarıdaki Tam istek gövdesi (birden fazla bölüm) yaması uygulandıktan sonraki yanıtı göstermektedir - değiştirilen alanlar yeni değerleri yansıtır, dokunulmayan alanlar korunur ve meta.updatedAt ilerler.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T12:45:08Z"
  }
}

GET /v1/usage

Management anahtarına sahip olan hesabın mevcut abonelik kullanımını okuyun.

Yanıt gövdesi (200)

{
  "subscriptionType": "your-plan-id",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType, hesabın geçerli planının küçük harfli tanımlayıcısıdır (your-plan-id açıklama amaçlı bir yer tutucudur). Planlar dinamik bir katalogdan gelir, bu nedenle planlar yeniden adlandırıldıkça veya eklendikçe tam tanımlayıcı kümesi zaman içinde değişebilir - bunu sabit bir enum olarak değil, opak bir dize olarak değerlendirin.
• messages.used / limit / remaining, mevcut takvim ayının mesaj kredileridir; abonelik yenileme gününde değil, ayın ilk gününde sıfırlanır. Bunlar ham yanıt sayıları değil, kredi ağırlıklıdır.
• bots.used / limit / remaining, duraklatılmış botlar dahil olmak üzere sahip olunan botları hesabınızın toplam bot sınırına göre sayar.

İstek sınırı üstbilgileri

İstek sınırı aşamasına ulaşan yanıtlar (yani kimlik doğrulama ve IP beyaz listesi kontrolleri başarılı olanlar) şunları içerir:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - bu çağrıya fiilen uygulanan anahtar başına üst sınır (varsayılan olarak 10 veya daha düşükse yapılandırdığınız rateLimitPerMinute).
• X-RateLimit-Remaining - bu çağrıdan hemen sonra kovada kalan belirteçler.
• X-RateLimit-Reset - bir sonraki belirtecin kullanılabilir hale geleceği Unix epoch saniyesi (kovanın tamamen sıfırlanması değil; kova sürekli olarak dolar). Kova dolduğunda bu değer geçerli zamandır.

429 rate_limit_exceeded yanıtlarında, en az bir belirteç açılana 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ı

Bot Talk API ile aynı zarf yapısı:

{
  "error": {
    "type": "permission_error",
    "code": "key_type_not_allowed",
    "message": "This endpoint requires a MANAGEMENT API key.",
    "param": null
  }
}

Doğrulama hataları code: "invalid_parameter" kullanır ve başarısız bölümün kolayca fark edilebilmesi için mesajın başına başarısız alan yolunu ekler:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "humanSupport.email Human support email is required when humanSupport.enabled=true"
  }
}

Enum / kapalı küme alanları için hatalı değerler (örneğin chatMemory.clientSummaryPromptType = "BOGUS"), alan yolunu, reddedilen değeri ve izin verilen değerlerin listesini içerir:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "chatMemory.clientSummaryPromptType 'BOGUS' is not a valid value. Allowed: CUSTOM, DEFAULT"
  }
}

İlgili konular

Görüşme uç noktaları ve SSE akışı için Bot Talk API sayfasına bakın.