Как да получа достъп до ChatLab Chat API?

Задайте window.aichatbotCallback.onSessionActivated преди зареждането на тага script. Вътре в този callback използвайте window.aichatbotApi.getChatbotApi(apiKey), за да получите обекта на API и да регистрирате слушатели на събития.

Какви callbacks са налични в Chat API?

Наличните callbacks включват onSessionActivated, onUserMessage, onChatbotMessage, onProductClick, onLeadCollectionFormSubmit, onContactFormSubmit и onLiveChatFormSubmit.

Как да използвам Chat API при внедряване чрез iframe?

Използвайте postMessage за изпращане на команди към iframe и addEventListener('message') за получаване на callbacks. Командите включват showChat, hideChat, sendMessage и updateClientContext.

Мога ли да променя езика на чат уиджета от моята страница?

Да, при многоезични чатботове. Извикайте setLanguage('de') върху обекта на API или задайте window.aichatbotLanguage преди скриптът да се зареди. При едноезични ботове методът не прави нищо.

За какво се използва updateClientContext?

updateClientContext Ви позволява да предавате потребителска информация (ID, име, имейл, телефон) и персонализирани параметри към чатбота по време на активна сесия, които могат да се използват при извиквания на API функции.

Chat API - ChatLab Помощен център

Общ преглед на Chat API

API на уиджета Ви позволява да управлявате чат уиджета програмно и да регистрирате функции за обратно извикване (callbacks) за събития в чата.

Търсите REST API? Тази статия разглежда JavaScript API на уиджета в браузъра (window.aichatbotApi) за страници, в които е вграден уиджетът на ChatLab. За REST API от тип сървър-към-сървър, използвано за разговори с ботове от Вашия бекенд или за програмно управление на ботове, вижте статиите за Bot Talk API и Management API.

Първи стъпки

API на чатбота не е налично веднага при зареждане на страницата Ви - скриптът трябва първо да се зареди и инициализира. Трябва да използвате window.aichatbotCallback.onSessionActivated като механизъм за първоначално зареждане (bootstrap), за да получите безопасен достъп до API.

Използвайте публичния ключ на уиджета от Deploy (Внедряване) като YOUR_API_KEY, никога таен ключ ck_ или mk_. Запазете идентификатора на доставчика и хоста на скрипта от Вашия собствен код за внедряване (Deploy snippet). Поставете настройката на callback функцията преди този таг за скрипт:

<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 се задейства, когато дадена сесия стане налична, включително при възстановени сесии. В зависимост от настройките за внедряване и началния екран (welcome-screen), това не е непременно първото кликване за отваряне на уиджета. Може да се задейства повторно; регистрирайте callback функциите еднократно за всеки API обект, за да избегнете дублиращи се обработчици (handlers). В рамките на тази функция е гарантирано, че API обектът съществува и сесията е активна, така че можете безопасно да извиквате sendMessage(), updateClientContext() и да регистрирате callback функции за събития.

Важно: Не извиквайте window.aichatbotApi.getChatbotApi() директно в скрипта на страницата си, без да изчакате - API обектът не съществува, докато скриптът на ChatLab не се зареди и инициализира.

Съвет: Ако е необходимо само да управлявате уиджета (показване/скриване/превключване) и не се нуждаете от активна сесия, вместо това слушайте за DOM събитието aichatbotReady:

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

Методи

Метод	Описание
`showChat()`	Отваряне на уиджета за чат
`hideChat()`	Затваряне на уиджета за чат
`toggleChat()`	Превключване на видимостта на уиджета
`sendMessage(text)`	Програмно изпращане на съобщение
`updateClientContext(data)`	Актуализиране на потребителския контекст (вижте по-долу)
`setLanguage(code)`	Превключване на уиджета към даден език (само за многоезични ботове, вижте по-долу)
`getLanguage()`	Връща езика, който уиджетът използва в момента
`getAvailableLanguages()`	Връща списъка с езици, които ботът предлага
`addCallback(name, fn)`	Регистриране на callback за събитие

Забележка: sendMessage и updateClientContext изискват активна сесия. Използвайте модела за инициализация с onSessionActivated, показан в раздела „Първи стъпки“.

Callbacks

Регистрирайте callbacks за събития вътре във Вашия onSessionActivated хендлър (вижте Първи стъпки):

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);
});

Налични Callbacks

Callback	Данни	Описание
`onSessionActivated`	-	Чат сесията е готова
`onUserMessage`	`string`	Потребителят изпрати съобщение
`onChatbotMessage`	`string`	Ботът отговори със съобщение
`onProductClick`	Payload за продукт/връзка от рендерираната карта	Потребителят кликна върху продуктова връзка; проверете payload за Вашия тип карта
`onLeadCollectionFormSubmit`	`{email, phone, name}`	Формулярът за събиране на лийдове беше изпратен
`onContactFormSubmit`	`{email, message}`	Формулярът за контакт/поддръжка беше изпратен
`onLiveChatFormSubmit`	`{name, email}`	Формулярът за чат на живо беше изпратен; не е доказателство, че оператор се е присъединил
`onCustomFormSubmit`	`{formId, values}`	Персонализираният формуляр беше изпратен; данните за качените файлове не са включени в този callback

Callbacks за формуляри отчитат изпращане от страна на браузъра, а не потвърдено записване или успешна доставка. За потвърдена от бекенда обработка използвайте Webhooks. Данните (payloads) в callbacks могат да съдържат лични данни; не ги препращайте изцяло към аналитични инструменти или публични логове.

Остарели callbacks за събития

Обектът window.aichatbotCallback поддържа също onUserMessage и onChatbotMessage като директни свойства. Използвайте addCallback() за модулни listeners, без да заменяте глобалния обект:

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

Забележка: window.aichatbotCallback.onSessionActivated не е остарял - това е препоръчителният bootstrap механизъм за инициализиране на Chat API (вижте Първи стъпки).

Внедряване чрез iframe

Когато използвате внедряване чрез iframe, използвайте postMessage за комуникация с чатбота:

Изпращане на команди

// 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);

Получаване на callbacks

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;
    }
});

Актуализиране на клиентския контекст

Функцията updateClientContext позволява актуализиране на клиентския контекст по време на активна сесия:

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"
    }
});

Параметри:

clientId (задължително): Уникален идентификатор на клиента
clientName, clientEmail, clientPhone (незадължително): Данни за клиента, показвани в разговорите
clientSecurityToken (незадължително): Токен, предаван като контекст за Вашата персонализирана интеграция. Вашето собствено API трябва да валидира неговата автентичност, изтичане на валидността и оторизация.
clientHostContext (незадължително): Допълнителни контекстни параметри, достъпни в персонализирани API действия

Предоставените от браузъра идентификатори и контекст не са доказателство за самоличност. Не поставяйте тайни за целия акаунт в JavaScript кода на страницата и не предоставяйте достъп единствено въз основа на това, че подаден clientId или имейл съвпада със запис.

Употреба в API извиквания:

Контекстните атрибути могат да се използват в API извиквания на функции, като конфигурирате API параметъра от тип "Context":

clientName, clientEmail, clientPhone, clientSecurityToken
Персонализирани параметри на хост контекста с префикс client, напр. clientparam1, clientparam2

Език

Тези методи работят само при многоезични чатботове. При едноезичен бот уиджетът няма езиков слой за превключване, така че setLanguage() не прави нищо, а getAvailableLanguages() връща само собствения език на бота. Първо включете многоезичната поддръжка в Settings > Languages (Настройки > Езици) - вижте Многоезични чатботове.

Използвайте setLanguage(), когато страницата Ви съществува на няколко езика и искате чатът да се отваря на този, който посетителят чете, вместо на зададения в неговия браузър:

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", ...]
});

Можете също да заявите езика на страницата преди зареждането на скрипта, което предотвратява краткото премигване на грешния език:

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

Кой език има предимство. Уиджетът определя езика в следния ред:

Език, избран лично от посетителя в езиковото меню на самия уиджет.
Езикът на страницата, зададен чрез setLanguage() или window.aichatbotLanguage.
Езикът на браузъра на посетителя.
Основният език на чатбота.

Личният избор на посетителя се запомня за бъдещи посещения, но спира да се прилага веднага щом езикът на страницата се промени - така Вашият превключвател на езика винаги има предимство пред остарял избор. Кодовете са по ISO 639-1 (en, de, pl); регионален код като de-AT се свежда обратно до de. Език, който ботът не предлага, се игнорира.

Превключването на езика не прекратява разговора и не изтрива хронологията му.

Chat API