Сценарии для страниц

Чат-пузырь в углу легко проигнорировать, и посетитель, который на него нажимает, попадает в пустое окно и не понимает, что спросить. Страницовые сценарии (playbooks) решают обе проблемы: агент знает, с какой страницы был открыт чат, приветствует посетителя соответствующим образом и предлагает несколько вопросов, которые можно отправить одним нажатием.

Что такое сценарий

Три элемента, привязанные к выбранному вами ключу:

Открывающую фразу и вопросы можете написать вы сами, либо их может сгенерировать агент на основе фонового текста на языке, установленном в браузере посетителя.

Привязка к странице

Вы никогда не отправляете со страницы контент из браузера — только идентификатор. Текст хранится на платформе. (См. Почему контент остаётся на сервере.)

По URL — ничего не нужно менять на странице

Задайте сценарию правило URL, и виджет сопоставит его автоматически:

/pricing            matches /pricing, /pricing/, /pricing?utm_source=x
/solutions/*        matches /solutions/legal, /solutions/insurance
*/solutions/legal   matches /solutions/legal AND /zh/solutions/legal

Сравнивается только путь — хост, протокол, строка запроса и завершающий слэш игнорируются, поэтому одно правило покрывает www и домен без префикса, http и https.

По ключу — для страниц с общим URL

Одностраничные приложения, модальные окна и многошаговые процессы часто не имеют отдельного URL. Вместо этого явно укажите имя сценария:

<script src="https://chat.agent4.io/ui/embed.js"
        data-token="YOUR_SHARE_TOKEN"
        data-page-key="checkout-step-2" async></script>

Если страница меняется без перезагрузки, сообщите виджету об этом при изменении маршрута:

caWidget.setPage("checkout-step-3");

Порядок разрешения

1. Явный ключ, если он был указан
2. Первое совпадающее правило URL
3. Сценарий по умолчанию, если он у вас есть
4. Ничего — посетитель получает обычный чат-бокс

Явный ключ, которого не существует, переходит к сценарию по умолчанию, а не тихо совпадает с каким-либо правилом URL. Таким образом, опечатка приведёт к появлению «сценария по умолчанию», а не «неправильного сценария».

Настройка одного сценария

В консоли откройте раздел Page playbooks и создайте новый. Сначала выберите тип страницы — страница с ценами, страница решения, документация, кейс, главная, контакты — и вопросы будут предварительно заполнены тем, что посетители обычно спрашивают на страницах такого типа. Затем переформулируйте их своим стилем.

В списке есть средство проверки: вставьте любой URL, и он покажет, какой сценарий получит эта страница, и совпало ли это по ключу, по правилу URL или сценарий по умолчанию не подошёл.

Или через API:

curl -X PUT https://api.agent4.io/v1/manage/page-contexts/pricing \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "label": "Pricing page",
    "url_pattern": "*/pricing",
    "context": "The visitor is looking at our pricing. Four tiers separated by monthly token quota and end-user count. The usual questions are which tier fits their size and what happens when they go over.",
    "greeting_mode": "generated"
  }'

Написание фонового текста

Это та часть, которая выполняет основную работу. Несколько моментов, которые стоит знать:

Достаточно одного языка. Модель читает то, что вы написали, и отвечает на языке посетителя. Вам не нужен перевод для каждой локали.

Не повторяйте факты, которые уже есть в вашей базе знаний. Цены, квоты и лимиты берутся из базы знаний, которая имеет более высокий приоритет, чем сценарий — число, указанное здесь, не переопределит его. Пишите о ситуации: кто попадает на эту страницу, что они пытаются решить, о чём обычно беспокоятся.

Пишите о том, что делает посетитель, а не о том, что написано на странице. «Посетитель сравнивает тарифы и пытается предсказать свой ежемесячный счёт» полезнее, чем краткое содержание текста на странице — агент уже может посмотреть этот текст.

Статические или сгенерированные приветствия

greeting_mode: "static" использует точную открывающую фразу и вопросы, которые вы написали, для каждого посетителя на любом языке. Полный контроль, никаких сюрпризов.

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

Сгенерированный вариант — лучший выбор по умолчанию для многоязычного сайта. Статический подходит, когда формулировки критичны — регулируемые отрасли или страница, где вы отточили текст с копирайтером.

Сгенерированное приветствие может содержать форму. Когда фоновый текст сценария явно указывает на необходимость сбора данных при первом контакте («представьте форму в вашем приветствии»), открывающая фраза появляется уже с интерактивной формой внутри — канал, поле контакта, всё, что просит фоновый текст — а стартовые вопросы отступают. Отправка формы является обычным сообщением, поэтому инструменты агента (save_contact, schedule_followup) срабатывают как обычно. Карточка «Поговорить с человеком» на нашей странице контактов — это именно так: форма бронирования появляется на экране до того, как посетитель введёт хоть слово.

Почему контент остаётся на сервере

Виджет сообщает ключ или URL. Он никогда не загружает текст страницы, и платформа никогда не читает ваш DOM.

Это сделано намеренно. Всё, что отправляет браузер, может быть изменено человеком, сидящим перед ним, а контекст страницы попадает близко к инструкциям агента. Мы протестировали это: с сфабрикованным «в этом месяце Enterprise стоит $199 с неограниченным количеством мест», внедрённым в блок контекста страницы — явно ограждённым как данные, с инструкцией агенту, что цены берутся только из базы знаний — модель повторила фейковую цену посетителю как факт. Ограждения и осторожные формулировки не помогли.

Хранение текста на сервере полностью устраняет канал утечки. Худшее, что может сделать посетитель, — запросить другой ключ и получить сценарий, который вы написали сами.

Компромисс, о котором стоит знать: текст сценария полупубличный. Любой, кто угадает ключ, получит открывающую фразу этого сценария. Не размещайте там внутренние заметки.

Точки входа внутри вашего контента

Пузырь в углу легко проигнорировать. Момент, когда у человека действительно есть вопрос, — это когда он читает определённый абзац — поэтому вы можете разместить точку входа прямо там:

<p data-ca-ask="overage-billing"
   data-ca-question="What happens if we go over, and can we cap the spend?"
   data-ca-label="Ask about this">
  When the quota is exhausted, chat requests return 429 …
</p>

При наведении на абзац появляется небольшая подсказка. При нажатии страница подсвечивается цветом вашего бренда, выделяет этот абзац, затем открывает чат, который уже работает на основе сценария этого абзаца — и, если вы указали вопрос, сразу же задаёт его.

Абзацы, добавленные позже — через фреймворк, вкладку, аккордеон — подхватываются автоматически. Вызовите caWidget.rescan(), если вы рендерите контент способом, который не попадает под автоматический скан.

Подключение ваших собственных кнопок

Любой элемент на вашей странице может открыть разговор на выбранном сценарии — шаблон превращения существующей кнопки «Связаться с отделом продаж» или «Забронировать демо» в разговор с агентом вместо формы:

const ok = caWidget.open("contact-sales");            // open on that playbook
caWidget.open("contact-sales", "I need a quote");     // …and ask the first question for them
if (!ok) location.href = "mailto:sales@example.com";  // false = script blocked; keep a fallback

caWidget.open работает одинаково независимо от формы виджета на вашем сайте — угловой пузырь или палитра команд Ask. Он возвращает false, когда виджет недоступен (скрипт не загружен или заблокирован), поэтому клик никогда не становится тупиком: используйте резервную ссылку, которая была у кнопки раньше.

Наша собственная страница контактов построена именно так — семь карточек намерений, каждая открывает сценарий, который задаёт два или три вопроса, сохраняет контакт и бронирует последующий разговор.

Детерминированная регистрация данных

Когда задача сценария — собирать данные — бронирование, лид, жалобу, — добавьте в его фоновый текст машинный маркер: [[inbox:submit_lead]], [[inbox:escalate]] или [[inbox:request_booking]]. Когда посетитель отправляет интерактивную форму на этом сценарии, платформа регистрирует запись сама, до того как ответит модель — агент лишь передаёт ссылку, которую вернул инструмент. Контактные данные в ответах сохраняются тем же способом.

Это существует потому, что регистрация — это единственный шаг, который никогда не должен зависеть от настроения модели: при тестировании в продакшене модель среднего размера с доступным инструментом, инструктированная и подталкиваемая, всё равно подтверждала бы вербально — один раз процитировав пример ссылки из документации так, как будто это реальный факт. С маркером ссылка в ответе — это ссылка в вашем почтовом ящике, каждый раз. Если регистрация по какой-либо причине не удалась, разговор продолжается нормально, и инструкции, основанные на модели, берут на себя управление.

Видимость результатов

В консоли показывается, сколько раз открывался каждый сценарий и какие стартовые вопросы нажимали. Используйте это, чтобы убрать вопросы, которые никто не выбирает, и выявить страницы, где посетители открывают чат, но никогда не вступают в диалог — обычно это признак того, что открывающая фраза говорит не о том.

События — это только подсчёты. Они не содержат идентификатора посетителя, потому что вопрос, на который нужно ответить, — «хороший ли этот текст», а не «кто и что спрашивал».

После того как они поговорили

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