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

Chat API

Последна актуализация:

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

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

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

Първи стъпки

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

Поставете този код преди скриптовия таг на ChatLab:

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

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

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

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

Важно: Не извиквайте 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

Регистрирайте функциите за обратно извикване на събития във Вашия обработчик 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 string (ID на продукт или връзка) Потребителят кликна върху продукт (изисква включени Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Формулярът за събиране на лийдове беше изпратен
onContactFormSubmit {email, message} Формулярът за контакт/поддръжка беше изпратен
onLiveChatFormSubmit {name, email} Формулярът за чат на живо беше изпратен

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

Обектът window.aichatbotCallback също така поддържа onUserMessage и onChatbotMessage като директни свойства. Този формат е остарял - използвайте addCallback() вместо него за достъп до всички видове callbacks:

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

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

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

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

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

const chatbotIframe = document.querySelector('iframe');

// Показване на чата
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'showChat'
}, '*');

// Скриване на чата
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'hideChat'
}, '*');

// Изпращане на съобщение
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'sendMessage',
    payload: 'Hello!'
}, '*');

// Актуализиране на клиентския контекст
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'updateClientContext',
    payload: { clientId: 'user123', clientName: 'John' }
}, '*');

// Превключване на езика (само за многоезични ботове)
chatbotIframe.contentWindow.postMessage({
    type: 'aichatbot',
    action: 'setLanguage',
    payload: 'de'
}, '*');

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

window.addEventListener('message', (event) => {
    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",     // Задължително
    clientName: "John",                       // По избор
    clientEmail: "john@doe.com",              // По избор
    clientPhone: "555-444-333",               // По избор
    clientSecurityToken: "your-token",        // По избор
    clientHostContext: {                      // По избор
        param1: "value1",
        param2: "value2"
    }
});

Параметри:

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

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

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

  • clientName, clientEmail, clientPhone, clientSecurityToken
  • Персонализирани параметри на host контекста с префикс 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);  // напр. "de"

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

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

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

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

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

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

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

Свързани статии

Търсене във всички статииПопитайте асистента