Chat API

Огляд Chat API

API віджета дозволяє програмно керувати віджетом чату та реєструвати зворотні виклики (callbacks) для подій чату.

Шукаєте REST API? У цій статті описано JavaScript API віджета у браузері (window.aichatbotApi) для сторінок, де вбудовано віджет ChatLab. Інформацію про серверний REST API (server-to-server), який використовується для спілкування з ботами з вашого бекенду або для програмного керування ботами, див. у статтях про Bot Talk API та Management API.

Початок роботи

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

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

<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 спрацьовує, коли сесія стає доступною, включно з відновленими сесіями. Залежно від налаштувань розгортання та екрана привітання, це не обов'язково перший клік для відкриття віджета. Вона може спрацьовувати повторно; реєструйте зворотні виклики один раз для кожного об'єкта API, щоб уникнути дублювання обробників. Усередині гарантується існування об'єкта 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)	Зареєструвати зворотний виклик події

Примітка: методи 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);
});

Доступні зворотні виклики

Зворотний виклик	Дані	Опис
onSessionActivated	-	Сесія чату готова
onUserMessage	string	Користувач надіслав повідомлення
onChatbotMessage	string	Бот відповів повідомленням
onProductClick	Дані продукту/посилання з відрендереної картки	Користувач натиснув на посилання товару; перевірте передані дані для вашого типу картки
onLeadCollectionFormSubmit	{email, phone, name}	Форму збору лідів надіслано
onContactFormSubmit	{email, message}	Контактну форму / форму підтримки надіслано
onLiveChatFormSubmit	{name, email}	Форму Live Chat надіслано, не є підтвердженням підключення оператора
onCustomFormSubmit	{formId, values}	Користувацьку форму надіслано; дані завантажених файлів не входять до цього виклику

Зворотні виклики форм повідомляють про відправлення на стороні браузера, а не про підтверджене збереження чи успішну доставку. Для обробки з підтвердженням на бекенді використовуйте Webhooks. Корисні дані зворотних викликів можуть містити персональні дані; не передавайте їх повністю в аналітику чи публічні журнали.

Застарілі виклики подій (Legacy)

Об'єкт window.aichatbotCallback також підтримує onUserMessage та onChatbotMessage як прямі властивості. Використовуйте addCallback() для модульних слухачів без заміни глобального об'єкта:

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

Примітка: window.aichatbotCallback.onSessionActivated не є застарілим - це рекомендований механізм для ініціалізації 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);

Отримання зворотних викликів

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 або email збігається із записом у системі.

Використання у викликах 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>

Яка мова має пріоритет. Віджет визначає мову в такому порядку:

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

Власний вибір відвідувача запам'ятовується для наступних візитів, але перестає діяти, щойно змінюється мова сторінки - тому ваш перемикач мов завжди має перевагу над застарілим вибором. Коди відповідають стандарту ISO 639-1 (en, de, pl); для регіональних кодів, таких як de-AT, застосовується резервний варіант de. Мова, яку бот не підтримує, ігнорується.

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

Схожі статті

• Багатомовні чатботи
• Додавання чатбота на ваш вебсайт
• Bot Talk API
• Management API