Genel bakış

Quickchat AI, AI Temsilcinizin yapılandırmasına, Bilgi Tabanına, Konuşmalarına, AI Eylemlerine ve diğer kaynaklarına programatik erişim için bir REST API sunar.

İsteğe bağlı örnek kontrolleri

• Dağıtım yöntemlerini karşılaştırın. Belirttiğiniz kanalları, web sitesi erişimini ve gerekli özellikleri Quickchat AI kurulum seçenekleriyle karşılaştırın. Bu araç web sitenizi veya hesabınızı incelemez.

• Örnek bir MCP bağlantısını kontrol edin. Yalnızca Cloudflare belgeleri veya Microsoft Learn uç noktasında bağlantıyı başlatın ve araçları listeleyin. Giriş yapılmaz ve araç çalıştırılmaz.

Kimlik doğrulama

Tüm API uç noktaları Bearer belirteciyle kimlik doğrulama kullanır. Her isteğin Authorization üstbilgisine API belirtecinizi ekleyin:

Authorization: Bearer <API_TOKEN>

Belirteçler Quickchat Kontrol Panelinde Harici Uygulamalar > API altında oluşturulur. Her belirteç scenario_id değerinizi içeren bir JWT olduğundan ek bir tanımlayıcı üstbilgisine gerek yoktur.

• Belirteç geçerliliği: oluşturulduğu tarihten itibaren 52 hafta
• Belirteçler kontrol panelinden istediğiniz zaman iptal edilebilir
• Her belirteç tek bir AI Temsilcisiyle (senaryoyla) sınırlıdır
• Belirteç oluşturmak için Business planı veya üzeri gerekir. Daha düşük planlarda seçenek devre dışıdır ve uç nokta 402 Payment Required döndürür

Not

Gerçek zamanlı Chat uç noktası (POST https://app.quickchat.ai/chat) bu API’nin geri kalanıyla aynı Bearer belirtecini kabul eder, ancak /v1/api/ temel yolunun dışında bulunur ve istek gövdesinde scenario_id gerektirir. Tam başvuru için Sohbet sayfasına bakın.

Belirteç kapsamları

API belirteçleri iki kapsamdan biriyle oluşturulur:

Kapsam	Erişim düzeyi	Açıklama
read_all	Salt okunur	Tüm kaynakları okuyabilir; oluşturamaz, güncelleyemez veya silemez
write_all	Okuma + Yazma	Yazma işlemleri dahil tüm uç noktalara tam erişim

• Belirteçlere kontrol panelinde Harici Uygulamalar > API altında oluşturulurken kapsam atanır
• write_all kapsamı, tüm read_all izinlerini otomatik içerir
• Yazma uç noktasında read_all belirteci kullanmak, "Insufficient token scope. Required: write_all" mesajıyla 403 döndürür

İpucu

İzleme, analiz ve salt okunur entegrasyonlar için read_all belirteçleri kullanın. write_all belirteçlerini yalnızca entegrasyonunuzun kaynak oluşturması veya değiştirmesi gerektiğinde kullanın.

Uç nokta grubuna göre kapsam gereksinimleri:

Uç nokta grubu	Okuma işlemleri	Yazma işlemleri
Chatbot Ayarları	read_all	write_all
Bilgi Tabanı Ayarları	read_all	write_all
Makaleler	read_all	write_all
Makale Dil URL’leri	read_all	write_all
Etiketler	read_all	Yok
Dosya Yükleme	Yok	write_all
Dış İçerik İçe Aktarma	Yok	write_all
Intercom Bilgi Tabanı	read_all	write_all
Widget Yapılandırması	read_all	write_all
Konuşmalar	read_all	Yok
Konuşma Meta Verileri	read_all	write_all
Devir Yapılandırması	read_all	write_all
Konuşma Değerlendirmesi	read_all	write_all
AI Eylemleri	read_all	write_all

Temel URL

Uç nokta grubu	Temel URL
Bilgi Tabanı, AI Eylemleri, Dosya Yükleme, İçe Aktarma, Chatbot Ayarları, Widget, Devir, Konuşma Değerlendirmesi	https://app.quickchat.ai/v1/api/
Konuşmalar	https://app.quickchat.ai/v1/api_core/
Gerçek Zamanlı Sohbet	https://app.quickchat.ai/chat

İstek sınırları

İstek sınırları belirteç ve uç nokta başına uygulanır.

Katman	Sınır	Uygulandığı işlemler
READ	120 istek/dk	GET ve listeleme işlemleri
WRITE	60 istek/dk	POST, PATCH, PUT, DELETE
HEAVY	20 istek/dk	Dosya yükleme, içe aktarma, tarama

İstek sınırı aşıldığında API, HTTP 429 Too Many Requests döndürür.

Webhook’lar

Quickchat AI dışarıya webhook göndermez. Bir olaya abone olarak mesaj geldiğinde, konuşma devredildiğinde veya kapandığında uç noktanıza POST göndermemizi sağlayamazsınız.

Mevcut alternatifler farklı amaçlara hizmet eder:

• AI Eylemleri konuşma sırasında API’nizi çağırır. API Eylemleri AI karar verir, İlk yanıttan önce ve Meta veriler eşleştiğinde modlarını sunar. Otomatik modlar, belgelenen koşullar altında konuşma başına bir kez çağrı dener; her mesaja veya devre abonelik değildir. Potansiyel müşteri kaydetmek ya da gerekli veriler hazır olduğunda sisteminizi bilgilendirmek gibi işler için kullanın.
• Google Sheets Eylemi çalıştığında bir satır ekler. Her mesajı veya devri otomatik kaydetmez.
• Konuşmalar API’sini düzenli sorgulama, mesajlar ve kayıtlı devir işaretleri dahil saklanan konuşmaları ve olaylarını alır. Sayfalamaya ve yukarıdaki READ istek sınırına uyun. Düzenli sorgulama gecikme yaratır; sorgular arasındaki konuşma durumunu karşılaştırmak ara değişiklikleri kaçırabilir. Bunun her devir veya atama geçişinin eksiksiz geçmişini sağladığını varsaymayın.

API erişimi Business planı gerektirir; Planlar ve sınırlar sayfasına bakın.

Sayfalama

Liste uç noktaları sorgu parametreleriyle sayfalamayı destekler:

Parametre	Açıklama
limit tamsayı	Sayfa başına öğe sayısı
offset tamsayı	Atlanacak öğe sayısı

Sayfalanmış yanıtlar şu yapıyı izler:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Hata işleme

Tüm hatalar aşağıdaki biçimde JSON olarak döndürülür:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Durum	Kod	Açıklama
400	BAD_REQUEST	Geçersiz girdi veya eksik zorunlu alanlar
401	PERMISSION_DENIED	Geçersiz, süresi dolmuş veya iptal edilmiş belirteç
402	PAYMENT_REQUIRED	Etkin abonelik gerekli
403	PERMISSION_DENIED	Belirteç, bu işlem için gerekli kapsama sahip değil
404	NOT_FOUND	Kaynak bulunamadı
409	CONFLICT	Çakışan işlem (örneğin eşzamanlı değişiklik)
422	VALIDATION_ERROR	İstek gövdesi şema doğrulamasından geçemedi
429	TOO_MANY_REQUESTS	İstek sınırı aşıldı
500	UNKNOWN	Dahili sunucu hatası
503	SERVICE_UNAVAILABLE	Geçici olarak kullanılamıyor

---