Yardım Merkezi
Chat API

Chat API

Son güncelleme:

Chat API genel bakış

Widget API, sohbet widget'ını programatik olarak kontrol etmenizi ve sohbet etkinlikleri için geri çağırmalar (callbacks) kaydetmenizi sağlar.

REST API mi arıyorsunuz? Bu makale, ChatLab widget'ının yerleştirildiği sayfalar için tarayıcı içi JavaScript widget API'sini (window.aichatbotApi) ele almaktadır. Botlarla arka ucunuzdan (backend) konuşmak veya botları programatik olarak yönetmek için kullanılan sunucudan sunucuya REST API hakkında bilgi edinmek için Bot Talk API ve Management API makalelerine bakın.

Başlarken

Chatbot API'si sayfanız yüklendiğinde hemen kullanılamaz - öncelikle betiğin yüklenmesi ve başlatılması gerekir. API'ye güvenli bir şekilde erişmek için bir önyükleme (bootstrap) mekanizması olarak window.aichatbotCallback.onSessionActivated kullanmalısınız.

YOUR_API_KEY olarak Deploy (Yayına al) bölümündeki herkese açık widget anahtarını kullanın; asla gizli bir ck_ veya mk_ anahtarı kullanmayın. Sağlayıcı kimliğini (provider ID) ve betik ana bilgisayarını (script host) kendi Deploy kod parçacığınızdan alın. Geri çağırma (callback) kurulumunu bu betik etiketinin önüne yerleştirin:

<script>
let registeredChatbot;
window.aichatbotCallback = {
    onSessionActivated() {
        var chatbot = window.aichatbotApi.getChatbotApi('YOUR_API_KEY');

        if (registeredChatbot === chatbot) return;
        registeredChatbot = chatbot;

        chatbot.addCallback('onUserMessage', function(message) {
            console.log('User said:', message);
        });

        chatbot.addCallback('onChatbotMessage', function(message) {
            console.log('Bot replied:', message);
        });

        // Send only when your application intends to start a real chat:
        // chatbot.sendMessage('Hello from the API!');
    }
};
</script>
<script>window.aichatbotApiKey="YOUR_API_KEY";</script>
<script src="https://script.chatlab.com/aichatbot.js" defer></script>

onSessionActivated, geri yüklenen oturumlar da dahil olmak üzere bir oturum hazır hale geldiğinde tetiklenir. Yayına alma ve karşılama ekranı ayarlarına bağlı olarak bu, mutlaka widget'ın ilk açılış tıklaması olmak zorunda değildir. Yeniden tetiklenebilir; yinelenen işleyicileri önlemek için geri çağırmaları API nesnesi başına bir kez kaydedin. İçinde, API nesnesinin var olduğu ve oturumun etkin olduğu garanti edilir; böylece sendMessage(), updateClientContext() işlevlerini güvenle çağırabilir ve olay geri çağırmalarını kaydedebilirsiniz.

Önemli: Sayfa betiğinizde beklemeden doğrudan window.aichatbotApi.getChatbotApi() çağırmayın - ChatLab betiği yüklenip başlatılana kadar API nesnesi mevcut değildir.

İpucu: Yalnızca widget'ı denetlemeniz gerekiyorsa (göster/gizle/aç-kapat) ve etkin bir oturuma ihtiyacınız yoksa bunun yerine aichatbotReady DOM olayını dinleyin:

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);
    chatbot.showChat();
});

Yöntemler

Yöntem Açıklama
showChat() Sohbet widget'ını açar
hideChat() Sohbet widget'ını kapatır
toggleChat() Widget görünürlüğünü açıp kapatır
sendMessage(text) Programatik olarak bir mesaj gönderir
updateClientContext(data) Kullanıcı bağlamını günceller (aşağıya bakın)
setLanguage(code) Widget'ı bir dile geçirir (yalnızca çok dilli botlar, aşağıya bakın)
getLanguage() Widget'ın o anda kullandığı dili döndürür
getAvailableLanguages() Botun sunduğu dillerin listesini döndürür
addCallback(name, fn) Bir etkinlik geri çağırma işlevi kaydeder

Not: sendMessage ve updateClientContext etkin bir oturum gerektirir. Başlarken bölümünde gösterilen onSessionActivated başlatma modelini kullanın.

Geri çağırma işlevleri (callbacks)

onSessionActivated işleyicinizin içinde olay geri çağırmalarını (callbacks) kaydedin (bkz. Başlarken):

chatbot.addCallback('onUserMessage', function(message) {
    console.log('User said:', message);
});

chatbot.addCallback('onChatbotMessage', function(message) {
    console.log('Bot replied:', message);
});

chatbot.addCallback('onProductClick', function(productIdOrLink) {
    console.log('Product clicked:', productIdOrLink);
});

chatbot.addCallback('onLeadCollectionFormSubmit', function(data) {
    console.log('Lead captured:', data.email);
});

chatbot.addCallback('onContactFormSubmit', function(data) {
    console.log('Support request from:', data.email);
});

chatbot.addCallback('onLiveChatFormSubmit', function(data) {
    console.log('Live chat started:', data.name);
});

Kullanılabilir geri çağırma işlevleri

Callback Veri Açıklama
onSessionActivated - Sohbet oturumu hazır
onUserMessage string Kullanıcı bir mesaj gönderdi
onChatbotMessage string Bot bir mesajla yanıt verdi
onProductClick Oluşturulan karttan ürün/bağlantı yükü (payload) Kullanıcı bir ürün bağlantısına tıkladı; kart türünüz için payload verisini inceleyin
onLeadCollectionFormSubmit {email, phone, name} Potansiyel müşteri toplama (lead) formu gönderildi
onContactFormSubmit {email, message} İletişim/destek formu gönderildi
onLiveChatFormSubmit {name, email} Canlı sohbet formu gönderildi; bir operatörün katıldığını kanıtlamaz
onCustomFormSubmit {formId, values} Özel form gönderildi; yüklenen dosya verileri bu callback'e dahil edilmez

Form geri çağırmaları, tarayıcı tarafında bir gönderim olduğunu bildirir; verinin veritabanına kalıcı olarak kaydedildiğini veya başarıyla iletildiğini doğrulamaz. Arka uç tarafından onaylanmış işlemler için Webhooks kullanın. Callback payload verileri kişisel veri içerebilir; bunları analiz araçlarına veya herkese açık günlüklere (logs) doğrudan ve topluca iletmeyin.

Eski olay geri çağırmaları (Legacy Event Callbacks)

window.aichatbotCallback nesnesi, doğrudan özellikler olarak onUserMessage ve onChatbotMessage seçeneklerini de destekler. Global nesneyi değiştirmeden modüler dinleyiciler eklemek için addCallback() kullanın:

window.aichatbotCallback = {
    onUserMessage(message) { ... },
    onChatbotMessage(message) { ... }
};

Not: window.aichatbotCallback.onSessionActivated kullanımdan kaldırılmamıştır - Chat API'yi başlatmak için önerilen önyükleme (bootstrap) mekanizmasıdır (bkz. Başlarken).

Iframe ile yayına alma

Iframe ile yayına alırken chatbot ile iletişim kurmak için postMessage kullanın:

Komut gönderme

// Give the ChatLab iframe from Deploy this unique id.
const chatbotIframe = document.getElementById('chatlab-frame');
const chatbotOrigin = new URL(chatbotIframe.src, window.location.href).origin;
// Run show/hide/language commands after the iframe loads.
// Wait for onSessionActivated before sendMessage or updateClientContext.

// Show chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, chatbotOrigin);

// Hide chat
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, chatbotOrigin);

// Send message
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, chatbotOrigin);

// Update client context
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, chatbotOrigin);

// Switch language (multi-language bots only)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, chatbotOrigin);

Geri çağırmaları (callback) alma

window.addEventListener('message', (event) => {
    if (event.origin !== chatbotOrigin || event.source !== chatbotIframe.contentWindow) return;
    if (event.data?.type !== 'aichatbot-callback') return;

    const { apiKey, callback, data } = event.data;

    switch (callback) {
        case 'onSessionActivated':
            console.log('Session ready');
            break;
        case 'onUserMessage':
            console.log('User said:', data);
            break;
        case 'onChatbotMessage':
            console.log('Bot replied:', data);
            break;
        case 'onProductClick':
            console.log('Product clicked:', data);
            break;
        case 'onLeadCollectionFormSubmit':
            console.log('Lead captured:', data);
            break;
        case 'onContactFormSubmit':
            console.log('Contact form:', data);
            break;
        case 'onLiveChatFormSubmit':
            console.log('Live chat started:', data);
            break;
    }
});

İstemci bağlamını güncelleme

updateClientContext fonksiyonu, etkin bir oturum sırasında istemci bağlamını güncellemenizi sağlar:

chatbot.updateClientContext({
    clientId: "unique-client-identifier",     // Required
    clientName: "John",                       // Optional
    clientEmail: "john@doe.com",              // Optional
    clientPhone: "555-444-333",               // Optional
    clientSecurityToken: "your-token",        // Optional
    clientHostContext: {                      // Optional
        param1: "value1",
        param2: "value2"
    }
});

Parametreler:

  • clientId (zorunlu): İstemci için benzersiz tanımlayıcı
  • clientName, clientEmail, clientPhone (isteğe bağlı): Konuşmalarda gösterilen istemci ayrıntıları
  • clientSecurityToken (isteğe bağlı): Özel entegrasyonunuz için bağlam olarak iletilen bir token. Kendi API'niz bunun gerçekliğini, son kullanma zamanını ve sağladığı erişim yetkilerini doğrulamalıdır.
  • clientHostContext (isteğe bağlı): Özel API eylemlerinde erişilebilen ek bağlam parametreleri

Tarayıcı tarafından sağlanan kimlikler ve bağlam, kimlik kanıtı değildir. Sayfa JavaScript'ine hesap genelindeki gizli anahtarları koymayın ve yalnızca sağlanan bir clientId veya e-posta bir kayıtla eşleşiyor diye erişim izni vermeyin.

API çağrılarında kullanım:

Bağlam nitelikleri, API parametresi "Context" türü olarak yapılandırılarak API fonksiyon çağrılarında kullanılabilir:

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • client önekiyle başlayan özel ana bilgisayar bağlamı parametreleri, ör. clientparam1, clientparam2

Dil

Bu yöntemler yalnızca çok dilli chatbot'larda çalışır. Tek dilli bir botta widget'ın geçiş yapabileceği bir dil katmanı yoktur, bu nedenle setLanguage() hiçbir işlem yapmaz ve getAvailableLanguages() yalnızca botun kendi dilini döndürür. Önce Settings > Languages (Ayarlar > Diller) bölümünden çoklu dil desteğini açın - bkz. Çok dilli chatbot'lar.

Sayfanız birkaç dilde mevcut olduğunda ve sohbetin ziyaretçinin tarayıcısının ayarlı olduğu dilde değil de okuduğu dilde açılmasını istediğinizde setLanguage() işlevini kullanın:

window.addEventListener('aichatbotReady', function(e) {
    var chatbot = window.aichatbotApi.getChatbotApi(e.detail.apiKey);

    chatbot.setLanguage(document.documentElement.lang);  // e.g. "de"

    console.log(chatbot.getLanguage());            // "de"
    console.log(chatbot.getAvailableLanguages());   // ["en", "de", "fr", ...]
});

Sayfa dilini betik yüklenmeden önce de belirtebilirsiniz; bu, yanlış dilin kısa bir anlığına görünmesini engeller:

<script>window.aichatbotLanguage = "de";</script>

Hangi dil önceliklidir. Widget dili şu sırayla belirler:

  1. Ziyaretçinin widget'ın kendi dil menüsünden bizzat seçtiği dil.
  2. setLanguage() veya window.aichatbotLanguage üzerinden gelen sayfa dili.
  3. Ziyaretçinin tarayıcı dili.
  4. Chatbot'un varsayılan temel dili.

Ziyaretçinin kendi seçimi sonraki ziyaretler için hatırlanır, ancak sayfa dili değiştiğinde geçerliliğini yitirir - böylece dil seçiciniz her zaman eski bir seçime göre öncelik kazanır. Kodlar ISO 639-1 biçimindedir (en, de, pl); de-AT gibi bölgesel bir kod de diline geri döner. Botun sunmadığı bir dil yok sayılır.

Dilin değiştirilmesi konuşmayı sonlandırmaz veya konuşma dökümünü temizlemez.

İlgili makaleler

Tüm makalelerde arayınTemsilciye sorun