Передача контекста клиента в AI-чат-бот для электронной коммерции
Позвольте странице авторизованного заказа передавать текущий ID заказа, убедитесь в его использовании коннектором, обновляйте его при переключении заказов и защитите продакшн-схему.
Чтобы безопасно передать контекст клиента в AI-чат-бот, позвольте странице выбирать текущую запись, сохраняя API с серверной авторизацией единственным источником истины.
Страница авторизованного пользователя в интернет-магазине уже знает, какого клиента и какой заказ он просматривает. Контекст сессии позволяет странице передавать ассистенту небольшой набор текущих значений, чтобы посетитель мог спросить “Where is my order?”, не вводя ID заказа повторно.
В этом руководстве используется вымышленный портал заказов Northstar, реальный виджет WebChatAgent и контролируемый HTTP-эндпоинт DummyJSON. Страница передает `order_id`; доступный только для чтения API Connector возвращает вымышленный статус и ориентировочную дату доставки (ETA). Реальные данные клиентов, отправлений, магазинов, платежных аккаунтов или учетных данных не используются.
Вы проверите три отдельных состояния: отсутствие контекста приводит к запросу ID, `A-1023` автоматически становится аргументом коннектора, а событие во время выполнения заменяет его на `A-2048`. Вы также сравните HTML-атрибут, глобальную переменную JavaScript, runtime-событие, интерфейсы WordPress и white-label псевдонимы.
Контекст браузера повышает удобство, но не является аутентификацией. Продакшн-схема ограничивает разрешенные домены и передает короткоживущий непрозрачный токен, который ваш API проверяет на стороне сервера перед возвратом минимально необходимого ответа.
Видеоплеер с защитой конфиденциальности (запуск в два клика)
AI-чат-бот для e-commerce: он знает заказ до того, как вы спросите
Передача контекста клиента и заказа в AI-чат-бот интернет-магазина, обновление данных на лету и безопасная интеграция через API Connector.
Плеер YouTube заблокирован до нажатия кнопки воспроизведения. Его загрузка подключает браузер к YouTube и может передавать технические данные в Google.
Открыть напрямую на YouTubeЧто вы узнаете по итогам руководства
- Проверенное базовое состояние без контекста
- Встраивание с `context-data`, передающее текущий заказ
- Реальный результат коннектора только для чтения для A-1023
- Замена в рантайме, использующая далее только A-2048
- Варианты реализации для JavaScript, WordPress и white label
- Чек-лист для продакшна на основе доменов, непрозрачных токенов и валидации на сервере
Перед началом работы
- Не предназначенный для продакшна ассистент WebChatAgent с доступом к API Connector
- Тестовая страница на английском языке в Light Mode на разрешенном домене
- Один тестовый mock-эндпоинт только для чтения с вымышленными данными
- Доступ к коду вставки виджета или размещению в WordPress
- Зафиксированные ожидания для базового уровня, исходного контекста и замененного контекста
- Для продакшна: бэкенд, способный генерировать и валидировать короткоживущие непрозрачные токены
Контекст страницы выбирает запись; API предоставляет достоверные данные
Страница со встроенным виджетом отправляет плоский набор пар «ключ-значение» с каждым запросом чата. Совпадающие ключи могут заполнять обязательные поля API Connector, но они не становятся постоянными знаниями. Коннектор по-прежнему выполняет прямой HTTP-запрос, и его ответ остается авторитетным источником статуса и ETA.
Событие `webchatagent:context` полностью заменяет текущую запись. Полная замена предотвращает скрытое сохранение старого ID заказа рядом с новым. Очищайте контекст пустым объектом или `null`, когда посетитель выходит из системы.
Относитесь к любому значению из браузера как к редактируемому пользовательскому вводу. Ограничения доменов определяют, где виджет может загружаться; подписанный короткоживущий или непрозрачный токен вместе с авторизацией на стороне сервера определяет, какую приватную запись разрешено вернуть.
01–08
Пошаговая настройка
Создайте один коннектор статуса заказа только для чтения
Ключ контекста и обязательное поле коннектора должны иметь абсолютно одинаковое имя.
Создайте коннектор у тестового ассистента TEST. Используйте метод GET и контролируемый эндпоинт `https://dummyjson.com/http/200/Order_{order_id}_is_in_transit_eta_August_8`. Добавьте одно обязательное поле Text с именем `order_id`; плейсхолдер и имя поля должны совпадать символ в символ.
Настройте вызов инструмента только для вопроса о статусе вымышленного заказа, укажите использовать точный текущий `order_id` из контекста посетителя и возвращать только ID заказа, нормализованный статус и ETA. Эндпоинт является публичным моком, а не интеграцией с магазином. Никогда не помещайте продакшн-токены или данные клиентов в промпт коннектора.
- Метод: только GET
- Обязательное поле: `order_id`
- Данные: вымышленный мок DummyJSON
Зафиксируйте базовое состояние без контекста
Ассистент должен запросить недостающий ID заказа и не должен придумывать статус.
Встройте виджет без `context-data`, откройте новый диалог и спросите в точности: “Where is my order?” Хотя на портале отображается A-1023, виджет не может читать произвольный текст страницы и должен запросить ID заказа.
Остановитесь, если в ответе уже фигурирует A-1023, статус «in transit» или дата «August 8». Это указывает на устаревшее состояние диалога, утечку данных из промпта или небезопасное угадывание. Очистите диалог и контекст браузера перед продолжением.
Передайте A-1023 с помощью атрибута context-data
Используйте плоскую небольшую запись, содержащую только значения, необходимые для текущей сессии.
Для страницы с серверным рендерингом добавьте `context-data="Customer=Jane Doe;order_id=A-1023;locale=en-US"` в тег `<web-chat-agent>`. Поддерживаются пары, разделенные точкой с запятой, и плоский JSON-объект; вложенные объекты не заменяют отдельный бэкенд-запрос.
Нормализованная запись допускает не более 20 ключей, до 64 символов на ключ, до 500 на значение и до 4,000 сериализованных символов всего. Используйте стабильные программные ключи, такие как `order_id`, избегайте конфиденциальных данных и делайте отображаемые метки (например, Customer) опциональными.
Убедитесь, что A-1023 доходит до коннектора
Тот же вопрос теперь возвращает статус без повторного запроса ID.
Начните новый диалог с включенным контекстом и повторите: “Where is my order?” Ассистент должен подставить A-1023 в качестве обязательного аргумента инструмента `order_id`, вызвать эндпоинт GET и ответить, что вымышленный заказ находится в пути («in transit») с ETA August 8.
Проверка объединяет три факта: код вставки содержит A-1023, URL коннектора содержит плейсхолдер `{order_id}`, а реальный mock-ответ содержит A-1023 и текст статуса. Контекст выбирает запись; ответ эндпоинта предоставляет статус.
Замените контекст после входа или перехода по страницам
Событие рантайма полностью заменяет запись прямо во время открытого виджета.
Когда посетитель переключается на заказ A-2048, отправьте событие `new CustomEvent('webchatagent:context', { detail: { Customer: 'Jane Doe', order_id: 'A-2048', locale: 'en-US' } })`. Делайте это только после того, как состояние страницы и авторизованная сессия синхронизированы на новой записи.
Замена происходит целиком: пропущенные ключи удаляются, а не сохраняются. При выходе из системы передайте пустой объект или `null`. Не объединяйте старые и новые значения клиента и заказа в коде приложения, если такое поведение явно не требуется и не протестировано.
Убедитесь, что далее используется только A-2048
Следующий вызов коннектора не должен повторно использовать старый ID заказа из истории чата.
Не закрывая виджет, спросите: “What is the status of the order now shown on this page?” Следующий ответ должен содержать A-2048 и статус из мока, без какого-либо упоминания A-1023.
Сохраните этот трехэтапный тест для регрессионного контроля: отсутствие контекста, исходный контекст и runtime-замена. Повторяйте его после любых изменений коннектора, системного промпта, модели, виджета или основного приложения. Фиксируйте вопрос, текущий контекст, аргумент инструмента, ответ эндпоинта и временную метку.
Выберите атрибут, глобальную переменную, событие или интеграцию с платформой
Все поддерживаемые точки входа приводятся к единому текущему контексту посетителя.
Используйте HTML-атрибут для серверных значений. Устанавливайте `window.webchatagentContext` до асинхронного скрипта виджета, если начальной сессией управляет JavaScript. Используйте `webchatagent:context` для входа, выхода, смены учетной записи, корзины, товара или маршрута после загрузки страницы.
В WordPress используйте фильтр `webchatagent_context_data` для централизованно формируемых значений или `[webchatagent_inline context-data="order_id=A-1023"]` для встроенного шорткода. Для White-label решений используйте `window.chatWidgetContext` и событие `chat-widget:context` с идентичной логикой полной замены.
Защитите получение данных в продакшне
Контекст браузера — это редактируемый пользовательский ввод, а не подтверждение личности клиента.
Ограничьте параметр `allowedDomains` только точными хостами продакшна и стейджинга. Не авторизуйте поиск заказа лишь на основании того, что контекст содержит имя клиента, email или номер заказа: посетитель может изменить любое из этих значений через DevTools.
Настройте бэкенд на выдачу короткоживущего непрозрачного токена для авторизованной сессии, передавайте в контексте только этот токен и позвольте коннектору вызывать read-эндпоинт с минимальными привилегиями. Эндпоинт проверяет токен, принадлежность клиенту, срок действия и запрошенные права на стороне сервера, после чего возвращает только ID заказа, статус и ETA. Отзывайте токен или завершайте его срок действия при выходе из системы.
Пример и результаты тестирования
Практический тест и верификация интерфейса
Каждое руководство содержит фиксированные входные параметры, ожидаемый результат и прозрачный отчет о локально проверенных шагах.
Практический пример: Передача контекста клиента в AI-чат-бот для отслеживания заказов
Этот тестовый сценарий был полностью выполнен на временном демонстрационном аккаунте.
Тестовые входные данные
Ask “Where is my order?” first without context and then with `order_id=A-1023`. In the same context-enabled widget, dispatch `webchatagent:context` with `order_id=A-2048` and ask for the order now shown.
Ожидаемый результат
Без контекста ассистент запрашивает ID заказа. С контекстом коннектор использует A-1023 и возвращает статус «in transit» с ETA August 8. После замены следующий ответ использует A-2048 и не упоминает A-1023.
Фактически проверенные результаты
Изолированный тест в English Light Mode успешно прошел все три состояния с использованием контролируемого мока DummyJSON. На базовом шаге был запрошен отсутствующий ID; исходный контекст вернул A-1023, статус «in transit» и «August 8»; runtime-замена вернула A-2048 без упоминания A-1023 в последнем ответе. Контракт коннектора требовал `order_id`, а итоговая очистка зафиксировала ровно 0 пользователей туториала.
Полезные советы
Обеспечение надежности настройки
Тестируйте ассистента на реалистичных примерах, фиксируйте базовые результаты и меняйте строго по одной настройке за раз. Это позволит наглядно видеть реальные улучшения.
Сохраняйте единые имена ключей на странице и в коннекторе
Используйте одно задокументированное программное имя, например `order_id`, во всех местах. Небольшая опечатка или изменение регистра сделают автоматическое заполнение поля невозможным.
Разделяйте удобство интерфейса и авторизацию
Контекст может указывать, на что именно смотрит посетитель. Только ваш бэкенд может определять, что авторизованному пользователю разрешено читать или изменять.
Очищайте контекст при выходе из системы
Отправляйте пустой объект или null до того, как следующий посетитель сможет воспользоваться виджетом, и открывайте новый диалог при смене учетной записи.
Что делать при возникновении проблем
Устранение неполадок
Систематически проверяйте статус сервиса, права доступа и тестовые данные перед тем, как менять модель или системный промпт.
Бот по-прежнему запрашивает ID заказа
Проверьте итоговый отрендеренный атрибут `context-data`, точное написание `order_id`, порядок загрузки скриптов и разрешенный домен. Начните новый диалог, чтобы старая реплика без контекста не искажала результат проверки.
Коннектор получает старый заказ
Убедитесь, что runtime-событие срабатывает после переключения страницы и заменяет объект целиком. Очистите устаревшее состояние приложения и убедитесь, что видимая карточка и отправленный payload содержат A-2048.
Ассистент называет статус без вызова инструмента
Остановите развертывание. Сделайте системную роль более строгой, исключите статус из контекста и промпта и требуйте обязательного вызова коннектора только для чтения для каждого ответа со статусом заказа.
Приватные данные заказа видны после изменения значения в браузере
Считайте это критической уязвимостью авторизации. Отключите прямой доступ по ID, внедрите короткоживущие токены с валидацией на сервере, выполните ротацию скомпрометированных учетных данных и проведите аудит логов эндпоинта.
Готовы к практическому тестированию
Используйте видео как пошаговое руководство, затем замените mock-URL в продакшне на эндпоинт только для чтения, проверяющий непрозрачный токен сессии. Прогоните заново все три состояния контекста и включите результаты в набор регрессионных тестов перед релизом.
Полезные материалы
Интеграция чат-бота с CRM
Используйте контекст клиента в связке с собственной CRM с соблюдением строгих правил авторизации.
Подключение чат-бота к REST API
Создайте и протестируйте коннектор только для чтения, используемый в данной схеме работы с контекстом.
Справочник разработчика по контексту виджета
Ознакомьтесь с актуальными интерфейсами, псевдонимами, логикой замены и лимитами.