Özel API entegrasyonları, chatbot'unuzun ERP, depo, CRM veya başka bir servisten canlı bilgi istemesini sağlar. Randevu oluşturma gibi değişiklikler de yapabilirler. Bir entegrasyon temel URL'yi (base URL) saklar; her işlem (operation) çağrılabilir bir isteği tanımlar. Ardından seçilen işlemleri chatbot'a AI actions (yapay zeka eylemleri) olarak bağlarsınız.
Başlamadan Önce
Hesabınızın Özel API entegrasyonlarını (Custom API integrations) kapsayıp kapsamadığını kontrol edin. Uç noktanın URL'sine, HTTP yöntemine, parametre adlarına ve türlerine, kimlik doğrulama gereksinimlerine ve örnek bir yanıta ihtiyacınız vardır. Uç nokta, ChatLab'in sunucularından erişilebilir olmalıdır; bilgisayarınızdaki localhost canlı ortam uç noktası değildir.
Kurulum için HTTPS ve bir test hizmeti veya test kayıtları kullanın. Test isteği uç noktayı gerçekten çağırır, bu nedenle POST, PATCH veya DELETE harici verileri değiştirebilir. İşlemleri mümkün olduğunca tekrarlanabilir ve güvenli hale getirin.
1. Bir Entegrasyon Oluşturun
- Ana gezinme menüsünden Custom Integrations (Özel Entegrasyonlar) bölümünü açın.
- + Define API Integration (+ API Entegrasyonu Tanımla) seçeneğine tıklayın.
- API name (API adı) ve API Base URL (API Temel URL'si) alanlarını girin, örneğin
https://api.example.com. - Create API Integration (API Entegrasyonu Oluştur) butonuna tıklayın.
- Liste kaydında önce View (Görüntüle), ardından + Define API Operation (+ API İşlemi Tanımla) butonuna tıklayın.
2. İşlemi Tanımlayın
İşleme tanınabilir bir etiket ve getProductDetails gibi makine tarafından okunabilen bir İşlem adı (Operation name) verin. İşlem adı için yalnızca harfleri ve sayıları kullanın; boşluk veya alt çizgi kullanmayın. İşlemin ne yaptığını ve chatbot'un bunu ne zaman kullanması gerektiğini açıklayın.
Göreli URI'yi girin, örneğin /v1/products/@productId@. Temel URL ve URI, istek adresini oluşturur.
Mevcut bazı ekran görüntüleri daha eski örnek adları veya süslü parantezli yer tutucuları gösterebilir. Aşağıdaki güncel sözdizimini izleyin: getProductDetails gibi işlem adları ve @ ile çevrelenmiş parametre yer tutucuları.
Yol ve Sorgu Parametreleri
productId tanımlamak için Yol değişkeni ekle (Add path variable) seçeneğine tıklayın. Veri türünü ve değer kaynağını ayarlayın, ardından URI'ye @productId@ ekleyin. Yol değişkenleri zorunludur ve kaydetmeden veya test etmeden önce tanımlanan her yol değişkeni URI içinde yer almalıdır.
URL'nin soru işaretinden sonrasına ait olan limit veya language gibi parametreler için Sorgu parametresi ekle (Add query parameter) seçeneğini kullanın. API'niz tarafından beklenen adı, türünü, açıklamasını ve değer kaynağını girin.
Kullanılabilir değer kaynakları şunlardır:
- Kullanıcı veya chatbot tarafından sağlanan (Provided by user or chatbot): model, konuşmadan bir değer sağlar. Beklenen biçimi açıklayın ve zorunlu değerleri uygun şekilde işaretleyin.
- Sabit (Constant): işlemde yapılandırılmış, örneğin sabit bir hesap tanımlayıcısı veya kısıtlı bir API kimlik bilgisi gibi bir değer.
- Rastgele değer (Random value): otomatik olarak oluşturulan bir değer.
- İstemci bağlamı (Client context): hesabınız için mevcut olduğunda ana web sitesi tarafından iletilen bir değer. Bkz. Chat API.
Skalar türler string, integer, double ve boolean içerir. Gövde parametreleri ayrıca dize ve tamsayı dizilerini (array) destekler.
3. Metodu ve Gövdeyi (Body) Yapılandırın
Uç noktanıza (endpoint) uyacak şekilde GET, POST, PUT, PATCH veya DELETE seçeneğini belirleyin. GET dışındaki yöntemler için düzenleyici, raw (ham) veya form-data istek içeriği sunar.
Ham bir JSON gövdesi için gövde parametrelerini tanımlayın ve bunların @name@ yer tutucularını şablona ekleyin. Uç noktanızın gerektirdiği uygun Content-Type başlığını ekleyin. Örneğin, dize (string) türündeki name ve dize dizisi (string-array) türündeki tags parametreleriyle:
{
"name": "@name@",
"tags": @tags@
}
Bu bir şablondur; yer tutucular değerleriyle değiştirilene kadar doğrudan kullanılabilir bir JSON değildir. Dizi yer tutucuları tırnak içine alınmamalıdır. Ham gövde düzenleyicisi uygulandığında, tanımlanan her gövde parametresi şablonda kullanılmalıdır. Tırnak işaretleri veya özel karakterler içeren metinler de dahil olmak üzere, test sırasında oluşturulan isteği kontrol edin.
4. Kimlik Doğrulama Başlıklarını Ekleyin
API tarafından beklenen başlıkları tanımlamak için Add header (Başlık ekle) seçeneğini kullanın. Bir bearer token için başlık adı olarak Authorization, değer kaynağı olarak Constant (Sabit) ve değer olarak Bearer YOUR_RESTRICTED_TOKEN kullanın.
Gizli anahtarları ve token'ları prompt'lardan ve URL'lerden uzak tutun. Modele giriş token'ları döndüren ve bunları gizlemek için talimatlara güvenen işlemlerden kaçının. Kendi kimlik doğrulamasını yöneten ve yalnızca izin verilen işlemi dışa aktaran sunucu taraflı bir entegrasyon uç noktasını tercih edin.
5. İsteği Kaydetme ve Test Etme
- İşlem düzenleyicisinde Save changes (Değişiklikleri kaydet) butonuna tıklayın. Normal chatbot Settings (Ayarlar) bölümünden farklı olarak bu düzenleyicide açık bir kaydet butonu bulunur.
- Test API Operation (API İşlemini Test Et) butonuna tıklayın. Değişiklikler kaydedilmediği sürece bu buton devre dışıdır.
- Temsili parametre değerleri girin. Dizi (array) test girdileri için virgülle ayrılmış değerler kullanın.
- Testi yalnızca okuma veya değiştirme yetkiniz olan veriler üzerinde çalıştırın.
- Sonuçlarda gösterilen durum kodunu (status code), yanıt gövdesini (response body), istek URL'sini, başlıkları (headers), gövdeyi (body) ve tüm uyarıları inceleyin.
- Hataları düzeltin, kaydedin ve gerektiğinde tekrarlayın.
Kimlik doğrulama bilgilerini (credentials) içeren test çıktılarını paylaşmayın. Mümkün olduğunda odaklanmış, sayfalanmış veriler döndürün: Büyük yanıtlar modele ulaşmadan önce kesilebilir.
6. İşlemi bir chatbota bağlayın
Chatbotunuzu açın, ardından Settings > Actions (Ayarlar > Eylemler) bölümüne gidin. Bir eylem eklemek için artı düğmesini kullanın, özel API'ler altından işleminizi bulun ve bağlayın veya etkinleştirin. Yalnızca hesap düzeyinde bir entegrasyon oluşturmak, her işlemi her chatbot için kullanılabilir hale getirmez.
Eylemin talimatlarını ve mevcut güvenlik ayarlarını inceleyin, ardından kaydedildi durumunu bekleyin. Eylem düzenleyici için AI actions sayfasına bakın.
7. Ne Zaman Kullanılacağını Açıklayın
Settings > Role & Behavior (Ayarlar > Rol ve Davranış) bölümünü açın.
Özel rol talimatları kullanıyorsanız Custom Role Definition (Özel Rol Tanımı) seçeneğini belirleyin ve net bir kural ekleyin, örneğin: "Ziyaretçi bir ürünün stokta olup olmadığını sorduğunda, ürün kimliğiyle getProductDetails işlevini çağırın. Dönen stok durumunu bildirin. Sorgulama başarısız olursa, stok durumunun kontrol edilemediğini açıklayın."
Chatbot'un diğer faydalı talimatlarını koruyun. Kaydedildi durumunu bekleyin, ardından gerçekçi soruları, eksik parametreleri, hataları ve yetkisiz istekleri test etmek için Overview (Genel Bakış) önizlemesini kullanın. Önizleme konuşmaları gerçek işlemleri tetikleyebilir.
Yapay zekanın işlevi çağırması garanti değildir veya çağrı mutlaka tek seferle sınırlı kalmayabilir. Chatbot'unuz için seçilen modelle test edin; yalnızca bir model adının doğru araç kullanımını garanti ettiğini varsaymayın.
Güvenlik ve Sorun Giderme
Uç noktanız, hassas bilgileri döndürmeden veya bir değişiklik yapmadan önce isteklerin kimliğini doğrulamalı ve her kullanıcının erişimini yetkilendirmelidir. Tarayıcı tarafından sağlanan bir istemci kimliği (client ID), e-posta, sipariş numarası veya bağlam alanı tek başına yeterli kimlik kanıtı değildir. İstemci bağlamı üzerinden kullanıcı başına bir token iletiyorsanız sunucunuz bunu doğrulamalıdır.
Eksiksiz bir müşteri profili yerine yalnızca sipariş durumu gibi chatbot'un ihtiyaç duyduğu alanları döndürün. Prompt talimatları ifadeleri yönlendirebilir ancak modele iletilen hassas verilerin gizli kalacağını garanti edemez.
İstek test düzenleyicide başarılı oluyor ancak bir görüşmede başarısız oluyorsa ekli eylemi, eylemin etkin durumunu, talimatları, gerekli parametreleri ve mevcut bağlamı kontrol edin. Her ikisi de başarısız oluyorsa URL'yi, HTTP yöntemini, kimlik doğrulamasını, işlenen gövdeyi ve uç noktanızın günlüklerini inceleyin. Önceki isteğin başarılı olup olmadığını bilmeden bir yazma işlemini tekrar tekrar denemekten kaçının.