Yardım Merkezi
Chat API

Management API

Son güncelleme:

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 sahibi 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

Management anahtarları herhangi 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 bu anahtarlar kasıtlı olarak Bot Talk anahtarlarından ayrı tutulur.

Base URL

https://api.chatlab.com/aichat

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

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 (Management Anahtarı Oluştur) butonuna tıklayın, bir ad verin, isteğe bağlı olarak IP beyaz listesi ve istek sınırlandırması (rate limit) belirleyin, ardından gönderin.
  3. Başarılı işlem modalından anahtarın tamamını kopyalayın. Düz metin yalnızca bir kez gösterilir.

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/* adresine bir ck_ anahtarı göndermek de aynı hatayı döndürür.

Limitler

  • Kullanıcı başına en fazla 5 aktif Management API anahtarı
  • Anahtar başına dakikada en fazla 10 istek (belirteç kovası / token bucket, 10 kapasiteli, 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 Management anahtarı aşağıdaki üç iznin herhangi bir alt kümesini taşır. Oluşturma sırasında en az birinin seçilmesi zorunludur; aksi takdirde istek 400 invalid_request_error ile reddedilir. Gerekli izne sahip olmayan bir anahtarla 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 kullanıcı 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ındaki Bot Settings (Bot Ayarları) kenar çubuğunda bulunan bir alt sekmeyle eşleşir; böylece JSON anahtarları ile görünen sekmeler birebir örtüşür: API üzerinden consent.humanSupportRequirePolicyAccept değerini değiştirirseniz, yönetici uygulamasındaki Consent & Privacy (Onay ve Gizlilik) sekmesinde aynı düğmenin durum değiştirdiğini görürsünüz.

  • role - bot karakteri, 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 sorular içeriği + dinamik takip soruları (Chat Conversation sekmesi)
  • chatMemory - sohbet hafızası düğmesi, özet prompt'ları, bağlam ayırma (Summaries & Memory sekmesi)
  • appearance - renkler, metinler, boyutlar, özel CSS, karşılama ekranı, önerilen soru stilleri, otomatik açılma davranışı, insan yazımı simülasyonu, altbilgi markdown içeriği (Appearance sekmesi)
  • humanSupport - insan iletişim formu (Human Contact Form sekmesi)
  • leadCollection - potansiyel müşteri toplama formu (Lead Collection sekmesi)
  • liveChat - canlı desteğe aktarma (Live Chat sekmesi)
  • consent - dört gizlilik politikası onay düğmesinin tümü ve onay ekranı metni (Consent & Privacy sekmesi)
  • whiteLabel - logoyu gizleme, özel logo bağlantısı, özel alan adı barındırma (Whitelabel sekmesi)
  • security - izin verilen alan adları, spam filtresi, sohbet hız limitleri (Security sekmesi)
  • voice - sesli girdi 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 dili işleme (Languages sekmesi)
  • advanced - LLM modeli, sıcaklık (temperature), bağlam boyutu, bot mesaj sınırı, dahili yerel ayar, Offer Cards (Model & Advanced sekmesi)

Yalnızca name en üst düzeyde yer alır; çünkü herhangi bir sekmeye ait olmaktan ziyade doğrudan botu tanımlar.

Bot Settings kenar çubuğunda şu anda 15 alt sekme bulunur ve bunlardan 13'ü yukarıdaki bölümlerle eşleşir. Karşılık gelen bir bölümü olmayan iki alt sekme Flow ve Actions sekmeleridir - her ikisi 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 mevcuttur - yeni bot için yeni üretilen Bot Talk API anahtarı.

Paylaşılan yapı içindeki iki alan salt okunurdur - yanıtta döndürülür, POST/PATCH sırasında göndermeye çalışırsanız yoksayılır:

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

Her iki URL de geçerli isteğin şema + ana bilgisayar + bağlam yolunu kullanır; bu nedenle White Label özel alan adında, kökü bu alan adı olacak şekilde dönerler (ör. https://api.acme.com/aichat/content/...).

PATCH sırasında bir bölümü atlamak için null gönderin; bir bölüm içindeki tek bir alanı atlamak için o alana null gönderin. Alan düzeyindeki null, kayıtlı bir değeri asla silmez - yalnızca "dokunma" anlamına gelir.

Rol ve prompt oluşturma

LLM'nin gerçekte aldığı sistem prompt'u, role.role değerine bağlı olarak iki yoldan biriyle oluşturulur. Hangi dalda olduğunuzu bilmek, hangi alanların önemli olduğunu ve hangilerinin depolandığı halde yoksayıldığını anlamanızı sağlar.

A Dalı - 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 yoksayar (değer bot üzerinde yine de saklanır, sadece kullanılmaz). Şablon şunları içerir:

  • role.role - rol etiketi (ör. "Customer Support") ve otomatik olarak eklenen role özel talimatlar
  • name - bot adı, açılış cümlesine eklenir
  • role.language - "Auto Detect", botu kullanıcının dilini takip edecek şekilde ayarlar; diğer tüm değerler (ör. "English", "Polish") "Output in {language}, unless user uses another language" haline gelir
  • role.responseLength - bir hedef kelime sayısıyla eşleştirilir: Concise ≈ 50 kelime, Normal ≈ 100, Detailed ≈ 200
  • role.websiteAddress - isteğe bağlı; boş olmadığında "for the users of the website {url}" olarak eklenir
  • role.companyDescription - isteğe bağlı; boş olmadığında rol talimatlarından önce ek bir paragraf olarak başa eklenir

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

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

Arka uç, tüm sistem prompt'u olarak role.rawPrompt değerini harfi harfine kullanır. responseLength, language, websiteAddress, companyDescription saklanır ancak prompt'a eklenmez - bunlardan herhangi birinin botun davranışına yansımasını istiyorsanız bunları rawPrompt metninize kendiniz dahil etmelisiniz. Role özel güvenlik sınırları ve tonlama talimatları da eklenmez; tüm prompt'un kontrolü sizdedir.

CUSTOM seçeneğini yalnızca şablon güdümlü prompt kullanım durumunuza uymadığında kullanın (ör. çok sektöre özel bir karaktere, kendi güvenlik kısıtlamalarınıza veya standart dışı bir çıktı formatına ihtiyacınız varsa).

Enum / sabit kümeli alanlar

Bazı alanlar yalnızca sabit bir dize değerleri kümesini kabul eder. Listenin dışındaki herhangi bir değerin gönderilmesi 400 validation_failed hatası ve error.param içinde alan yolu ile reddedilir. Değerler büyük/küçük harfe duyarlıdır.

  • 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ı, ör. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi ve ~80 diğer dil. Değer olduğu gibi 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 bozuk bir talimat üretir. Oluşturma sırasında belirtilmediğinde varsayılan olarak Auto Detect değerini alır.
  • advanced.model - aşağıdaki "Yapay zeka metin modelleri" bölümüne bakın; seçilebilir küme hesap limitlerinize tabidir ve hesabınızın kullanamayacağı herhangi bir değer 400 invalid_parameter hatası döndürür
  • advanced.chatContextSize - 8000, 16000, 32000. Hesap limitlerinize tabidir; daha yüksek değerler sessizce sınırlandırılır
  • chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
  • chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
  • appearance.chatAlignment - left, right
  • appearance.minimizedDisplayMode - icon, minified
  • appearance.chatMessageLinkTarget - _blank, _self
  • leadCollection.requireBeforeNewConversation - boolean düğmesi. true, kullanıcıyı bir konuşma başlatmadan ö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 dize veya sayılar gibi görünen ancak aslında bilinmesi gereken belirli yapılara, aralıklara veya yönetici arayüzü özelliklerine sahip alanlar.

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

  • chatMemory.summariesToKnowledgeRatio - tam sayı yüzdesi, 10-90 aralığında 10luk adımlarla. Sohbet bağlamının ne kadarının istemci geçmiş özetlerine ne kadarının diğer kısımlara (bilgi tabanı, geçerli konuşma, talimatlar) ayrılacağını kontrol eder. Varsayılan 50. 10-90 dışındaki değerler 400 validation_failed ile reddedilir. Yalnızca chatMemory.enabled=true VE chatMemory.summaryConversationsEnabled=true olduğunda geçerlidir.

  • liveChat.schedule - iletim sırasında iç içe bir JSON nesnesi değil, dize olarak kodlanmış JSON'dur. Sunucu ham dizeyi olduğu gibi saklar; yönetici arayüzü çalışma saatleri düzenleyicisini oluştururken bunu istemci tarafında ayrıştırır. Ayrıştırıldıktan sonra dize, hafta içi gün başına bir giriş ve bir timezone anahtarı olarak yapılandırılır:

    • her hafta içi anahtarı (monday-sunday), 24 saatlik formatta {enabled: boolean, from: "H:MM", to: "H:MM"} ile eşleşir
    • timezone, bir IANA bölge adıdır (ör. "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\"}"

    Belirtilen saatlerin dışında, ziyaretçiye liveChat.outOfHoursMessage gösterilir ve canlı desteğe aktarma devre dışı bırakılır. İç 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örüntüleme hatası olarak ortaya çıkar. Göndermeden önce yapıyı kendi tarafınızda doğrulayın.

  • conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - conversation.conversationRatingEnabled=true olduğunda her yapay zeka yanıtının yanındaki 👍 / 👎 butonlarında gösterilen kısa etiketler. Varsayılan metin "I like the response" / "I don't like the response" şeklindedir. Son kullanıcılara görünür.

  • whiteLabel.hideRoboAssistLogo - hesap limitlerinize tabi White Label özelliği. Alt kısımdaki "Powered by ChatLab" satırını gizler. Hesabınız White Label özelliğini içermiyorsa değer saklanır ancak yoksayılır ve altbilgi her zaman görüntülenir.

  • whiteLabel.whitelabelLogoLink - hesap limitlerinize tabi White Label özelliği. hideRoboAssistLogo=true olduğunda ve whitelabel_logo multipart parçası 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 baloncukları arasındaki duraklama süresi. Varsayılan 5.

  • appearance.autoOpenChatDelaySeconds - saniye, tam sayı. autoOpenChat=true ve autoOpenChatDelay=true olduğunda widget'ın otomatik olarak açılmasından önceki gecikme süresi.

  • 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 çok daha fazlası. Yalnızca iki harfli bir kod ("en") veya BCP-47 ("en-US") göndermek izin verilenler listesinde yer almaz. Varsayılan en_US. Bu, botun konuşma çıktısı dilinden (role.language) farklı olarak widget çerçevesindeki tarih/sayı biçimlendirmesi için kullanılan yerel ayardır.

  • security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - tam sayılar (JSON sayısı olarak gönderin, ör. "30" değil 30). 0, IP başına istek sınırlandırmasını devre dışı bırakır. Sıfırdan farklı olduğunda widget, ziyaretçiye security.talkMessagesRateLimitHitMessage mesajını göstermeden önce saniye cinsinden süre başına N mesaj kuralını uygular.

  • advanced.botMessagesLimit - tam sayı (JSON sayısı, ör. 1000). 0, "sınır yok" anlamına gelir; aksi takdirde 1000'in katı olmalıdır (1000, 2000, 10000, ...). 100 veya 1500 gibi değerler 400 validation_failed ile reddedilir. Ardından ayrıca hesap limitinize göre sessizce sınırlandırılır.

Yapay zeka metin modelleri (advanced.model)

Tam API değerini gönderin (soldaki ters tırnak içindeki sütun). Yönetici arayüzündeki görünen ad parantez içindedir. Hesap limitleriniz hangi alt kümenin seçilebileceğini belirler; hesabınızın kullanamayacağı bir modelin gönderilmesi 400 invalid_parameter döndürür. Yeni botlar için varsayılan model 5-MINIdir.

  • 4-O-MINI (GPT 4-o mini)
  • 4-O (GPT 4-o)
  • 4.1-MINI (GPT 4.1-mini)
  • 4.1 (GPT 4.1)
  • 5-MINI (GPT 5-mini)
  • 5 (GPT 5)
  • 5.1 (GPT 5.1)
  • 5.4-MINI (GPT 5.4-mini)
  • 5.4 (GPT 5.4)
  • 5.5 (GPT 5.5)
  • GEMINI 2.5 PRO (Gemini 2.5 Pro)
  • GEMINI 3 Flash (Gemini 3 Flash)
  • GEMINI 3.5 Flash (Gemini 3.5 Flash)
  • GEMINI 3.7 Flash (Gemini 3.7 Flash)
  • GEMINI 3.8 Flash (Gemini 3.8 Flash)
  • GEMINI 3.1 Flash-Lite (Gemini 3.1 Flash-Lite)
  • GEMINI 3 PRO (Gemini 3 Pro)

Alan referansı (tam istek şeması)

Türü, kısıtlaması ve tek satırlık açıklamasıyla birlikte iletilen her alan. 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 kullanılır (multipart ikili içerik hariç; her yanıtta salt okunur meta bloğu ve yalnızca oluşturma yanıtında apiKey eklenir).

Üst düzey

Field Type Constraint Description
name string max 150, required on create 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

Field Type Constraint Description
role string (enum) CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM Persona ön ayarı; prompt şablonunu seçer (bkz. "Role and prompt construction")
language string full English language name (English, Polish, ...) or Auto Detect Prompt şablonuna aktarılan birincil dil
responseLength string ∈ {Concise, Normal, Detailed} İstenen AI yanıt uzunluğu
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 prompt'u - yalnızca role=CUSTOM olduğunda birebir kullanılır

§ conversation

Field Type Constraint Description
welcomeMessage string Açılışta ziyaretçiye gösterilen ilk mesaj
queryRefinementEnabled boolean Doğruysa, RAG alımından önce ziyaretçinin sorusunu netleştirir
conversationContinuityEnabled boolean Doğruysa, geri dönen ziyaretçiler son konuşmalarına devam eder
conversationRatingEnabled boolean Doğruysa, bot mesajlarında başparmak yukarı/aşağı değerlendirmesini gösterir
positiveRatingTooltip string Olumlu değerlendirme butonundaki ipucu metni
negativeRatingTooltip string Olumsuz değerlendirme butonundaki ipucu metni
suggestedQuestions string Yeni satırla ayrılmış önerilen sorular / konuşma başlatıcılar
dynamicSuggestedFollowups boolean Doğruysa, AI her yanıttan sonra takip önerileri sunar
dynamicFollowupsAutoIcons boolean Doğruysa, AI dinamik takip önerileri için otomatik olarak emoji simgeleri seçer

§ chatMemory

Field Type Constraint Description
enabled boolean Sohbet geçmişi özelliği için ana açma/kapatma düğmesi
summaryConversationsEnabled boolean Konuşma başına özetleri kalıcı olarak kaydeder
conversationSummaryPrompt string Her konuşmayı özetlemek için kullanılan özel prompt
conversationSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Varsayılan mı yoksa özel özet prompt'unun mu kullanılacağı
clientSummaryPrompt string Müşteriyi konuşmalar genelinde özetlemek için kullanılan özel prompt
clientSummaryPromptType string (enum) ∈ {DEFAULT, CUSTOM} Varsayılan ve özel müşteri profili prompt'u karşılaştırması
summariesToKnowledgeRatio int 10-90, step 10 Sohbet bağlam penceresinin özetlere ve RAG bilgisine ayrılan yüzdesi

§ appearance

Field Type Constraint Description
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 bilgi başlık rengi
subtitleColor string (hex) Sohbet üst bilgi 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 "Konuşmayı sıfırla" butonundaki ipucu metni
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ındaki alt gölge
customCss string Widget iframe'ine enjekte edilen ham CSS
chatMessageLinkTarget string (enum) ∈ {_blank, _self} Bot mesajlarındaki bağlantıların nasıl açılacağı
minimizedDisplayMode string (enum) ∈ {icon, minified} Simge durumuna küçültülmüş görünüm: başlatıcı simgesi veya kompakt gönderici çubuğu
chatDesktopWidthPx int Masaüstü widget genişliği
chatDesktopHeightPx int Masaüstü widget yüksekliği
chatMobileSizePercent int Görünüm alanının yüzdesi olarak mobil widget boyutu
messageFontSize int Mesaj metni yazı tipi boyutu (px)
showChatbotBubblesDesktop boolean Masaüstünde kayan dikkat çekici balonları gösterir
showChatbotBubblesMobile boolean Mobilde kayan dikkat çekici balonları gösterir
chatbotBubblesDelaySeconds int Dikkat çekici 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 Hoş Geldiniz Ekranını gösterir
welcomeScreenQuestionsLabel string Hoş geldiniz ekranındaki önerilen soruların üzerindeki etiket
welcomeScreenHideHumanContactForm boolean Hoş Geldiniz Ekranı gösterilirken başlıktaki temsilci iletişim formu eylemini gizler. Ziyaretçinin ilk mesajından sonra yeniden görünür. 2026-09-02 tarihinden önce oluşturulan botlar için varsayılan değer true şeklindedir
welcomeScreenHideLiveChat boolean Hoş Geldiniz Ekranı gösterilirken başlıktaki canlı sohbet eylemini gizler. Ziyaretçinin ilk mesajından sonra yeniden görünür. 2026-09-02 tarihinden önce oluşturulan botlar için varsayılan değer true şeklindedir
headerActionsLayout string DROPDOWN Canlı sohbetin ve temsilci iletişim formunun sohbet başlığında nasıl sunulacağı: ICONS (her biri için ayrı simge) veya DROPDOWN (başlık menüsünde gruplandırılmış). 2026-09-02 tarihinden önce oluşturulan botlar için varsayılan değer ICONS şeklindedir
stackSuggestedQuestions boolean Önerilen soruları (yan yana yerine) dikey olarak sıralar
suggestedQuestionsFontSize int Önerilen soru butonlarının yazı tipi boyutu (px)
suggestedQuestionsTextColor string (hex) Önerilen soru butonlarının metin rengi
suggestedQuestionsBackgroundColor string (hex) Önerilen soru butonlarının arka plan rengi
autoOpenChat boolean Masaüstünde sohbeti otomatik açar
autoOpenChatOnMobiles boolean Mobilde sohbeti otomatik açar
autoOpenChatDelay boolean Otomatik açılmadan önce bir gecikme kullanır
autoOpenChatDelaySeconds int Otomatik açılma gecikmesi (saniye)
simulateHumanTyping boolean Bot yanıtını yazıyor animasyonlu balonlara böler
simulateHumanTypingDelay int 0-200 Mesaj balonları arasındaki gecikme (saniye)
footerMarkdown string max 255 Sohbetin altında gösterilen özel alt bilgi markdown'ı
avatarUrl string read-only 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 - yalnızca URL iletilir.

§ humanSupport

Field Type Constraint Description
enabled boolean İnsan Desteği akışı açma/kapatma düğmesi
email string required (create-strict) when enabled=true İ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, konuşma dökümünü e-posta gövdesine dahil eder
customFormId long id of an existing custom form Yerleşik iletişim formunu özel bir formla değiştirir. null, yerleşik formu korur
customFormMapping string JSON-encoded string Özel form alanlarını insan desteği e-posta alanlarıyla eşler

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

§ leadCollection

Field Type Constraint Description
enabled boolean Potansiyel müşteri formu açma/kapatma düğmesi
nameEnabled boolean İsim bilgisini toplar
nameLabel string İsim giriş alanındaki etiket
emailEnabled boolean E-posta bilgisini toplar
emailLabel string required (create-strict) when enabled=true AND emailEnabled=true E-posta giriş alanındaki etiket
phoneEnabled boolean Telefon bilgisini toplar
phoneLabel string required (create-strict) when enabled=true AND phoneEnabled=true Telefon giriş alanındaki etiket
leaveDetailsMessage string required (create-strict) when enabled=true Ziyaretçiyi iletişim bilgilerini bırakmaya teşvik eden mesaj
thankYouMessage string required (create-strict) when enabled=true 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 potansiyel müşteri toplandığında sahibine e-posta gönderir
emailNotificationAddress string Bildirim alıcısı (varsayılan olarak hesap e-postasıdır)
emailWithConversationContent boolean Doğruysa, konuşma dökümünü bildirime dahil eder

Alanlar arası oluşturma zorunluluğu kuralı: enabled=true, emailEnabled veya phoneEnabled alanlarından en az birini gerektirir. requirePolicyAccept burada değil, consent.leadCollectionRequirePolicyAccept altındadır.

| customFormId | long | id of an existing custom form | Yerleşik potansiyel müşteri formunu özel bir formla değiştirir. null, yerleşik formu korur | | customFormMapping | string | JSON-encoded string | Özel form alanlarını isim / e-posta / telefon alanlarıyla eşler |

§ liveChat

Field Type Constraint Description
enabled boolean Live Chat (Canlı Sohbet) özelliği açma/kapatma düğmesi
infoMessage string Aktarım öncesi bilgilendirici 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ının etiketi
emailLabel string Canlı sohbet ön formundaki e-posta giriş alanının etiketi
schedule string JSON-encoded string (weekday toggles + from/to + timezone) Canlı sohbet çalışma takvimi - tam yapı için "Structured fields and ranges" bölümüne bakın
outOfHoursMessage string Takvime göre mesai dışı olunduğunda gösterilen mesaj
closeModalMessage string "Canlı sohbet kapatılsın mı?" modal başlığı
closeModalConfirmLabel string Kapatma modalındaki onay butonu etiketi
closeModalCancelLabel string Kapatma modalındaki iptal butonu etiketi
closeModalTooltipText string Sohbeti kapatma ögesindeki ipucu metni
operatorHasJoinedLabel string Bir operatör katıldığında gösterilen etiket
operatorDidNotJoinInTimeLabel string Zaman aşımı süresi içinde hiçbir operatör katılmadığında gösterilen etiket
waitingForOperatorToJoinLabel string Operatör beklenirken gösterilen etiket
waitingForOperatorSeconds int Bir operatörün yanıt vermesi için zaman aşımı süresi (saniye)
redirectToHumanSupportForm boolean Doğruysa, hiçbir operatör yanıt vermediğinde Human Support formuna yönlendirir
missedEmailEnabled boolean default true Bir canlı sohbet isteği yanıtsız kaldığında bot sahibine e-posta gönderir. Eski botlarda ayarlanmamış olarak bırakılmıştır, bu da etkin olarak değerlendirilir

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

§ consent

Field Type Constraint Description
newConversationRequirePolicyAccept boolean Yeni bir konuşma başlatmadan ö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 Potansiyel müşteri 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 Konuşma 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

Field Type Constraint Description
hideRoboAssistLogo boolean white-label capability; subject to account limits Alt bilgideki varsayılan ChatLab logosunu gizler
whitelabelLogoLink string white-label capability; subject to account limits Özel alt bilgi logosunun yönlendirdiği URL
assignToCustomDomain boolean gated by CUSTOM_DOMAIN feature Sohbeti yapılandırılmış özel alana bağlar
whitelabelLogoUrl string read-only 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 - yalnızca URL iletilir.

§ security

Field Type Constraint Description
allowedDomains string Widget'ın yerleştirilmesine izin verilen alan adları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 or WHITELIST Ülke listelerinin nasıl yorumlandığı. Listelerin kendisi yalnızca yöneticiye özel kalır
talkMessagesRateLimit int >= 0; 0 disables İstek sınırı penceresinde izin verilen maksimum kullanıcı mesajı
talkMessagesRateLimitDurationSeconds int >= 0 İstek sınırı pencere uzunluğu (saniye)
talkMessagesRateLimitHitMessage string İstek sınırına ulaşıldığında ziyaretçiye gösterilen mesaj

§ voice

Field Type Constraint Description
inputEnabled boolean Ziyaretçinin mesajları dikte etmesine izin verir (konuşmayı metne dönüştürme)
conversationEnabled boolean requires the voice feature on the plan Tam sesli konuşmaları etkinleştirir
voiceId string provider-specific voice id (e.g. alloy) Hangi sentetik sesin konuşacağı
model string e.g. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-* Ses modeli. Dakika başına ücretlendirilir, ücretler modele göre değişir
turnDetection string provider-specific Sıra alma modu
audioPrompt string Yalnızca sesli turlar için kullanılan ek sistem prompt'u
welcomeMessage string Sesli açılış cümlesi
language string language code Birincil ses dili
additionalLanguages string comma-separated language codes Sesli temsilcinin kabul ettiği ek diller
maxDurationSeconds int Tek bir sesli konuşma için kesin üst sınır
maxDurationMessage string Sınıra ulaşıldığında gösterilen mesaj

§ multilingual

Field Type Constraint Description
enabled boolean Çoklu dil modu açma/kapatma düğmesi
mode string AUTODETECT or a fixed-list mode Botun yanıt dilini nasıl seçeceği
baseLanguage string language code Botun kendi metinlerinin yazıldığı dil
languages string comma-separated language codes Ziyaretçiye sunulan diller
knowledgeLanguageMode string Diğer dillerdeki bilgilere nasıl davranılacağı
knowledgeLanguageFallback string language code Eşleşme bulunamadığında kullanılan dil

§ advanced

Field Type Constraint Description
model string subject to account limits; see "AI text models" above LLM tanımlayıcısı (ör. 5-MINI)
temperature decimal 0.0-1.0 Örnekleme sıcaklığı (kullanıcı arayüzündeki kaydırıcıyla eşleşir)
chatContextSize int ∈ {8000, 16000, 32000}; silently clamped to your account limit Sohbet geçmişi için belirteç (token) penceresi
botMessagesLimit long 0 or multiple of 1000 (e.g. 1000, 2000, 10000) Konuşma başına maksimum bot yanıtı (0 = sınır yok)
internalLocale string locale code in ll_CC form Widget arayüz etiketleri için yerel ayar (role.language alanından farklıdır)
productsViewEnabled boolean Doğruysa, sohbet içinde e-ticaret Offer Cards (Teklif Kartları) ögelerini gösterir
includeProductsInKnowledgeBase boolean Doğruysa, ürün kataloğunu bilgi bankası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 sunulmayan birkaç alanı içerir:

  • Flow (Akış) sekmesi - görsel Conversation Flow (Konuşma Akışı) düzenleyicisi (aşamalar ve geçişler). Management API aracılığıyla sunulmaz.
  • Actions (Eylemler) 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 sunulmaz. Ancak, var olan bir formu leadCollection.customFormId ve humanSupport.customFormId aracılığıyla bir bota bağlayabilirsiniz.
  • Özel sohbet açma / kapatma simgeleri - customLauncherIconVisible, openChatIcon, closeChatIcon. API yalnızca ana avatar ve whitelabel_logo multipart parçalarını sunar.
  • IP ve ülke listeleri - girişlerin kendisi yalnızca yöneticiye özeldir. Yalnızca yorumlama modu security.countryFilterMode aracılığıyla sunulur.

Uç Noktalar

POST /v1/management/bots

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

Mod A - düz JSON (aynı istekte bir 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 aracılığıyla yüklenebilir

Mod B - multipart/form-data (aynı istekte 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 arayüzü sihirbazının belirleyeceği varsayılan değerlere döner.

Tam istek gövdesi

Bu, her bölümün doldurulduğu azami data JSON içeriğidir. Yalnızca ilgilendiğiniz bölümleri gönderin; diğer 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-MINI",
    "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 bir tam sayı (yüzde, 10luk adımlarla)
  • appearance.launcherBottomMargin, appearance.launcherSideMargin - 0 ile 500 arasında
  • appearance.footerMarkdown - en fazla 255 karakter
  • humanSupport.enabled=true, humanSupport.email alanının ayarlanmış olmasını gerektirir
  • leadCollection.enabled=true, leadCollection.emailEnabled veya leadCollection.phoneEnabled değerlerinden en az birinin true olmasını gerektirir; hangi kanal açıksa onun etiketi ile birlikte leaveDetailsMessage ve thankYouMessage alanları da zorunludur
  • Üst sınırı olan alanlar (advanced.chatContextSize, advanced.botMessagesLimit vb.) sessizce hesap sınırlarınıza kırpılır

Sunucudaki değeri null olan alanlar JSON gövdesinden çıkarılır - ağ üzerinden yalnızca null olmayan değerlere sahip alanlar iletilir.

Tam yanıt gövdesi (201)

İstek ile aynı yapıda olup en üst düzeyde salt okunur meta bloğu ve tek seferlik apiKey eklenmiştir. Salt okunur dosya URL'leri (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl), ilgili multipart parçaları yüklendiğinde 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-MINI",
    "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; yeni bota bağlı, yeni üretilmiş Bot Talk anahtarıdır. Düz metin yalnızca bir kez gösterilir ve daha sonra API'den alınamaz; bunu hemen kendi tarafınızda kaydedin.

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_..."

Tam yanıt gövdesi (200)

Tek seferlik apiKey hariç, POST yanıtı ile aynı yapıdadır. meta bloğu dahil edilmiştir. 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 aynı şema + ana bilgisayar + bağlam yolu köküne dayalı, tam nitelikli salt okunur URL'ler (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) olarak sunulur. Baytları doğrudan bu URL'lere GET isteği atarak alın; herhangi bir dosyayı değiştirmek için PATCH işleminde multipart avatar / whitelabel_logo parçası aracılığıyla yeni bir dosya yükleyin. Bir istek gövdesinde gönderilmeleri halinde bu URL alanları yoksayı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-MINI",
    "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 süreçtir: 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 - POST gövdesinde bırakmak bir sorun yaratmaz (sunucu bunu yok sayar), ancak kaldırmak amacınızı netleştirir ve yükün temiz kalmasını sağlar. Klonun kaynaktan ayırt edilebilmesi için isteğe bağlı olarak name alanını 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ğerini ve yeni oluşturulmuş bir apiKey (klon için Bot Talk anahtarı) değerini içerir. Düz metin halindeki apiKey yalnızca bu oluşturma yanıtında döndürülür - yanıt gövdesini kapatmadan önce kopyalayın; daha sonra tekrar alınamaz.

İki önemli nokta:

  • Dosyalar klonlanmaz. appearance.avatarUrl ve whiteLabel.whitelabelLogoUrl 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 anındaki POST isteğinde (Mod B) ya da ardından gelen bir PATCH isteğinde yapabilirsiniz.
  • Bot Talk anahtarları klonlanmaz. Her botun kendine ait bir Bot Talk anahtarı havuzu vardır. Oluşturma POST isteği tarafından döndürülen tek apiKey, otomatik olarak üretilen 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 yer alan bölümler / alanlar değiştirilir; dahil edilmeyen (veya null olarak gönderilen) hiçbir şeye dokunulmaz. Gönderilen bir bölüm içindeki her alan için kısmi güncelleme kuralları geçerlidir.

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

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

  • Content-Type: application/json
  • İstek gövdesi doğrudan yama JSON'ıdır (data sarmalayıcısı yoktur)

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

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

PATCH üzerinde her üç parça da isteğe bağlıdır, ancak çağrının bir anlam ifade etmesi için en az birinin bulunması gerekir.

Tam istek gövdesi (tüm alanlar)

POST /v1/management/bots tarafından kabul edilen herhangi bir alan burada da gönderilebilir. Aşağıdaki örnek tüm alanları içerir; uygulamada yalnızca değiştirmek istediğiniz anahtarları gönderirsiniz (aşağıdaki "Minimum kısmi güncelleme" bölümüne bakın) - dahil edilmeyen (veya null olarak gönderilen) her anahtar, kayıtlı değeri olduğu gibi bırakı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
  }
}

Minimum kısmi güncelleme

Yalnızca değiştirmek istediğiniz anahtarları göndererek tek bir alana PATCH uygulayın; geri kalan 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ştirirken):

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 olmadan):

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ıya sahiptir - yama uygulandıktan sonraki meta bloğu da dahil olmak üzere botun tam yapılandırmasıdır. 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 (tüm alanlar) yaması uygulandıktan sonraki yanıtı gösterir - değiştirilen alanlar yeni değerleri yansıtır, dokunulmayan alanlar korunur ve meta.updatedAt güncellenir.

{
  "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 hesabın mevcut abonelik kullanımını okuyun.

Yanıt gövdesi (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}
  • subscriptionType, hesabın mevcut planının küçük harfli tanımlayıcısıdır (örneğin örnekteki standard). 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 ele alın.
  • messages.used / limit / remaining, geçerli faturalandırma dönemi mesaj kredileridir.
  • bots.used / limit / remaining, hesabınızın bot sınırına göre etkin botları sayar.

İstek sınırlandırma başlıkları

İstek sınırlandırma (rate limit) aşamasına ulaşan yanıtlar (yani kimlik doğrulama ve IP beyaz listesi kontrollerini geçenler) ş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 değeri).
  • X-RateLimit-Remaining - bu çağrının hemen ardından havuzda kalan token sayısı.
  • X-RateLimit-Reset - bir sonraki token'ın kullanılabilir hale geleceği Unix epoch saniye değeri (tüm havuzun sıfırlanması değil; havuz sürekli olarak yeniden dolar). Havuz dolu olduğunda bu değer geçerli zamandır.

429 rate_limit_exceeded yanıtlarında, en az bir token boşa çıkana kadar geçecek tam saniye cinsinden ifade edilen Retry-After başlığı da ayarlanır.

Kimlik doğrulama öncesi hatalar (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ve 403 ip_not_whitelisted hataları X-RateLimit-* başlıklarını taşımaz - istek sınırlandırı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 sorunlu bölümün kolayca fark edilebilmesi için hata mesajının başına ilgili 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 geçersiz 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 bkz. Bot Talk API.

Tüm makalelerde arayınTemsilciye sorun