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

Chat API

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

Обзор Chat API

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

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

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

API чат-бота недоступен сразу при загрузке страницы - скрипт должен сначала загрузиться и инициализироваться. В качестве механизма начальной загрузки (bootstrap) необходимо использовать window.aichatbotCallback.onSessionActivated, чтобы безопасно получить доступ к 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);
});

Доступные callbacks

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

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

Устаревшие callbacks событий

Объект 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);

Получение 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>

Какой язык имеет приоритет. Виджет определяет язык в следующем порядке:

  1. Язык, который посетитель выбрал самостоятельно в языковом меню самого виджета.
  2. Язык страницы, переданный из setLanguage() или window.aichatbotLanguage.
  3. Язык браузера посетителя.
  4. Основной язык чат-бота.

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

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

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

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