Интеграция

Сценарии страниц

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

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

Из чего состоит сценарий

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

Поле	Кто видит	Что делает
Контекст	Только агент	О чем эта страница и что обычно беспокоит попавших на нее посетителей
Приветствие	Посетитель	Первое, что он читает, открыв чат
Готовые вопросы	Посетитель	До четырех вопросов в один клик

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

Как определяется страница

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

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

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

/pricing            подходит для /pricing, /pricing/, /pricing?utm_source=x
/solutions/*        подходит для /solutions/legal, /solutions/insurance
*/solutions/legal   подходит и для /solutions/legal, и для /zh/solutions/legal

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

На локализованном сайте /zh/solutions/legal не совпадает с /solutions/legal. Пишите */solutions/legal, чтобы охватить все языковые префиксы.

По ключу — для страниц с общим 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");

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

Явно заданный ключ, если он есть
Первое подошедшее правило URL
Сценарий по умолчанию, если он настроен
Ничего — посетитель получает обычное окно чата

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

Как создать сценарий

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

В списке есть проверка соответствия: вставьте любой 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": "Страница тарифов",
    "url_pattern": "*/pricing",
    "context": "Посетитель изучает наши тарифы. Четыре тарифа, которые различаются месячной квотой токенов и числом конечных пользователей. Обычно спрашивают, какой тариф подойдет под их масштаб и что будет при превышении квоты.",
    "greeting_mode": "generated"
  }'

Как писать контекст

Именно эта часть делает всю работу. Несколько вещей, которые стоит учитывать:

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

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

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

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

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

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

Для многоязычного сайта генерация — вариант по умолчанию. Фиксированный режим уместен там, где важна каждая формулировка: регулируемые отрасли или страница, фразу для которой вылизывал копирайтер.

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

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

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

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

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

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

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

<p data-ca-ask="overage-billing"
   data-ca-question="Что будет при превышении квоты и можно ли ограничить расходы?"
   data-ca-label="Спросить об этом">
  Когда квота исчерпана, запросы к чату возвращают 429 …
</p>

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

Атрибут	Значение
`data-ca-ask`	Ключ сценария, с которым открывать чат — обязательный
`data-ca-question`	Отправляется как первое сообщение посетителя — необязательный
`data-ca-label`	Текст всплывающей подсказки (по умолчанию: «Спросить об этом»)

Фрагменты, появившиеся позже — из фреймворка, вкладки или аккордеона, — подхватываются автоматически. Если вы отрисовываете контент способом, который обходит этот механизм, вызовите caWidget.rescan().

data-ca-ask принимает ключ, а не текст абзаца. Агент читает именно тот сценарий, который назван ключом, а он хранится на сервере. Исключение — data-ca-question: он становится собственным сообщением посетителя, а сообщения посетителя по определению недоверенные, ведь он мог бы набрать эту фразу и сам.

Что работает, а что нет

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

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

Встраивание веб-виджета

Telegram и WhatsApp