Центр помощи
Chat API

Chat API

Последнее обновление:

Обзор Chat API

Эта функция доступна только в некоторых тарифных планах. Она позволяет программно управлять виджетом чата и регистрировать колбэки для событий чата.

Ищете REST API? В этой статье рассматривается браузерный JavaScript API виджета (window.aichatbotApi) для страниц со встроенным виджетом ChatLab. Информацию о REST API для взаимодействия типа сервер-сервер, используемом для общения с ботами из вашего бэкенда или программного управления ими, можно найти в статьях Bot Talk API и Management API.

Начало работы

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

Разместите следующий код перед тегом скрипта 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, описанный в разделе "Начало работы".

Колбэки

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

Устаревшие колбэки событий (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. Язык, не поддерживаемый ботом, игнорируется.

Переключение языка не завершает диалог и не очищает историю сообщений.

Связанные статьи

Поиск по всем статьямСпросить агента