Центр допомоги
Chat API

Chat API

Останнє оновлення:

Огляд Chat API

Ця функція доступна лише в окремих тарифних планах. Вона дозволяє програмно керувати віджетом чату та реєструвати зворотні виклики (callbacks) для подій чату.

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

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

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

Розмістіть цей код перед тегом скрипту 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) Зареєструвати зворотний виклик події

Примітка: для методів 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 string (ідентифікатор товару або посилання) Користувач клікнув на товар (потрібно ввімкнути Offer Cards)
onLeadCollectionFormSubmit {email, phone, name} Форму збору лідів надіслано
onContactFormSubmit {email, message} Контактну форму/форму підтримки надіслано
onLiveChatFormSubmit {name, email} Форму чату наживо надіслано

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

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

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

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

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

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
  • Спеціальні параметри контексту хосту з префіксом 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. Якщо бот не підтримує зазначену мову, вона ігнорується.

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

Пов'язані статті

Шукати серед усіх статейЗапитати агента