Виджет¶
Интеграция Виджета
Подключите ИИ-агента Cavuer к вашему сайту и автоматизируйте общение с посетителями 24/7.
Быстрый старт¶
Запустите агента за три шага.
Шаг 1 — Создайте агента в Cavuer¶
Агент — это ИИ-профиль, который управляет вашими каналами. К одному агенту можно подключить несколько каналов связи одновременно.
- Зарегистрируйтесь в console.cavuer.com
-
На главной странице нажмите «Создать агента», задайте имя и выберите языковую модель
-
После создания агента откройте его настройки и добавьте инструкцию — правила поведения агента при общении с клиентами
Пример инструкции
Ты — вежливый ассистент службы поддержки компании «МояКомпания».
Всегда обращайся к клиенту по имени.
Отвечай только на вопросы, связанные с нашими услугами.
Если не знаешь ответа — предложи связаться с оператором.
Выбор языковой модели
Каждая модель отличается по скорости, точности и стоимости. Для большинства задач поддержки отлично подходят модели семейства GPT-4 и Claude Haiku. Для сложных аналитических задач больше подойдут модели семейства GPT-5, Claude Sonnet или Claude Opus.
Шаг 2 — Подключите канал Виджет¶
-
На главной странице рядом с агентом нажмите «Добавить канал» и выберите Widget
-
Нажмите «Создать»
Шаг 3 — Настройте виджет и начните работу¶
После создания канала перейдите в его настройки для завершения конфигурации.
1. Добавьте скрипт на ваш сайт¶
В разделе «Установка» скопируйте скрипт и вставьте его в HTML-код вашего сайта перед закрывающим тегом </body>:
<script src="https://widget.cavuer.com/embed.js" data-token="ваш_токен"></script>
2. Разрешённые домены и идентификация пользователей¶
В разделе «Безопасность» добавьте домены, из которых разрешено отправлять сообщения в виджете.
Вы также можете установить обязательную идентификацию (подробнее об идентификации) пользователей используя «Секретный ключ», для этого включите ползунок в разделе «Безопасность».
Важно
При отсутствии указанных доменов виджет будет недоступен.
3. Настройте внешний вид и контент¶
В разделе «Настройки» настройте виджет под стиль вашего сайта:
Переключите ползунок в разделе «Статус» и нажмите «Сохранить».
Готово! Виджет появится на вашем сайте, и ИИ-агент начнёт автоматически отвечать посетителям.
Дополнительная настройка¶
Настройка агента в личном кабинете Cavuer¶
Настройте поведение агента в console.cavuer.com:
| Параметр | Описание |
|---|---|
| Название | Переименуйте агента и канал для удобного использования в личном кабинете Cavuer |
| Модель | Выберите языковую модель |
| Инструкция | Правила поведения агента: приветствие, описание компании, условия перевода на оператора, языковые настройки. Укажите, на каком языке агент должен отвечать — на языке обращения или только на конкретном языке |
| Задержка ответа | Задержка перед ответом. Полезно, когда клиенты пишут несколько сообщений подряд — агент дождётся и обработает все сообщения вместе |
| Обрабатывать изображения | Позволяет агенту просматривать изображения, анализировать их содержимое (на данный момент не доступно для канала Виджет) |
| Обрабатывать аудио | Агент сможет распознавать голосовые сообщения (на данный момент не доступно для канала Виджет) |
| База знаний | Загрузите файлы .txt, .pdf или .docx и подключите их в настройках агента |
Полное описание параметров: Настройка агента и канала
Наполнение базы знаний¶
Перейдите в раздел База знаний → нажмите Загрузить данные → укажите название статьи и выберите файл.
Затем в настройках агента установите чек-бокс напротив загруженных статей и сохраните изменения. Подробная информация по работе с Базой знаний.
Рекомендации по базе знаний
- Используйте ключевые слова в заголовках — например, «Стоимость услуг, цена, оплата, тариф» вместо просто «Стоимость»
- Разбивайте большие тексты — создавайте небольшие статьи под конкретные запросы (например, отдельно «Доставка», «Оплата», «Возврат»)
- Заголовки нельзя изменить — содержание статьи можно обновить, но заголовок останется прежним
- Ссылайтесь на документацию — загружайте основную информацию и прикрепляйте ссылку на полную документацию
Идентификация пользователей¶
По умолчанию каждый посетитель получает случайный идентификатор вида v_.... Если на вашем сайте есть система авторизации, вы можете передавать собственный идентификатор пользователя, чтобы:
- объединять диалоги одного пользователя из разных браузеров и устройств в один чат
- видеть в консоли Cavuer реальные ID пользователей вместо случайных
Требования
Для настройки идентификации необходим сервер (Node.js, Python, PHP и т.д.), так как секретный ключ должен храниться на стороне сервера и не передаваться в браузер.
Как это работает¶
- Сервер вычисляет HMAC-SHA256 хеш от идентификатора пользователя, используя секретный ключ из консоли Cavuer
- Хеш передаётся в скрипт виджета через атрибуты
data-user-idиdata-user-hash - После получения корректного хэша, пользователи будут идентифицированы
Настройка¶
1. Получите секретный ключ¶
В консоли Cavuer перейдите в настройки канала Widget → Безопасность и скопируйте Секретный ключ.
2. Вычислите хеш на сервере¶
const crypto = require("crypto");
const SECRET_KEY = process.env.CAVUER_SECRET_KEY;
function computeHash(userId) {
return crypto
.createHmac("sha256", SECRET_KEY)
.update(userId)
.digest("hex");
}
// Пример: computeHash("john@example.com")
import hmac
import hashlib
import os
SECRET_KEY = os.environ["CAVUER_SECRET_KEY"]
def compute_hash(user_id: str) -> str:
return hmac.new(
SECRET_KEY.encode(),
user_id.encode(),
hashlib.sha256
).hexdigest()
# Пример: compute_hash("john@example.com")
$secretKey = getenv('CAVUER_SECRET_KEY');
function computeHash(string $userId): string {
global $secretKey;
return hash_hmac('sha256', $userId, $secretKey);
}
// Пример: computeHash("john@example.com")
3. Передайте данные в скрипт виджета¶
Добавьте атрибуты data-user-id и data-user-hash в скрипт виджета:
<script
src="https://widget.cavuer.com/embed.js"
data-token="ваш_публичный_токен"
data-user-id="john@example.com"
data-user-hash="вычисленный_хеш">
</script>
Безопасность
Никогда не вставляйте секретный ключ (Secret Key) в клиентский код. Хеш должен вычисляться исключительно на стороне сервера.
Сценарии поведения¶
| Сценарий | Результат |
|---|---|
Переданы data-user-id и корректный data-user-hash | В чате отображается ваш ID пользователя. Диалоги из разных браузеров объединяются |
| Атрибуты не переданы (гость) | Пользователь получает случайный ID вида v_... |
Передан неверный data-user-hash | Сообщение не будет отправлено — защита от подмены |
Тестовый сервер¶
Для проверки идентификации можно воспользоваться готовым тестовым сервером на Node.js.
Установка и запуск тестового сервера
Установка¶
mkdir widget-id-test
cd widget-id-test
npm init -y
npm install express
Создайте файл server.js¶
const express = require("express");
const crypto = require("crypto");
const app = express();
const PORT = 3000;
// =============================================
// ПОДСТАВЬТЕ СВОИ ЗНАЧЕНИЯ ИЗ КОНСОЛИ CAVUER
// =============================================
const WIDGET_TOKEN = "wgt_ВСТАВЬТЕ_PUBLIC_TOKEN";
const SECRET_KEY = "sk_ВСТАВЬТЕ_SECRET_KEY";
const WIDGET_SCRIPT = "https://widget.cavuer.com/embed.js";
// =============================================
// Тестовые пользователи
// =============================================
const USERS = {
john: { id: "john@example.com", name: "John" },
anna: { id: "anna@example.com", name: "Anna" },
guest: null, // без идентификации
};
function computeHash(userId) {
return crypto
.createHmac("sha256", SECRET_KEY)
.update(userId)
.digest("hex");
}
// Главная страница — выбор пользователя
app.get("/", (req, res) => {
res.send(`
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Тест идентификации виджета</title>
<style>
body { font-family: sans-serif; max-width: 600px; margin: 40px auto; }
a { display: block; margin: 10px 0; padding: 12px 20px;
background: #6C47FF; color: white; text-decoration: none;
border-radius: 8px; text-align: center; }
a:hover { background: #5a3ad9; }
.guest { background: #666; }
.guest:hover { background: #555; }
</style>
</head>
<body>
<h1>Тест идентификации виджета</h1>
<p>Выберите пользователя для тестирования:</p>
<a href="/chat/john">John (john@example.com)</a>
<a href="/chat/anna">Anna (anna@example.com)</a>
<a href="/chat/guest" class="guest">Гость (без идентификации)</a>
</body>
</html>
`);
});
// Страница с Widget для конкретного пользователя
app.get("/chat/:userKey", (req, res) => {
const user = USERS[req.params.userKey];
const hash = user ? computeHash(user.id) : null;
const scriptTag = user
? '<script src="' + WIDGET_SCRIPT + '" data-token="' + WIDGET_TOKEN
+ '" data-user-id="' + user.id
+ '" data-user-hash="' + hash + '"></script>'
: '<script src="' + WIDGET_SCRIPT + '" data-token="'
+ WIDGET_TOKEN + '"></script>';
const displayName = user
? user.name + " (" + user.id + ")"
: "Гость (без идентификации)";
res.send(`
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Чат — ${displayName}</title>
<style>
body { font-family: sans-serif; max-width: 600px; margin: 40px auto; }
.badge { display: inline-block; padding: 6px 14px;
border-radius: 6px; font-size: 14px; margin-bottom: 16px; }
.identified { background: #dcfce7; color: #166534; }
.anonymous { background: #fef3c7; color: #92400e; }
a { color: #6C47FF; }
pre { background: #f1f5f9; padding: 12px; border-radius: 8px;
font-size: 12px; overflow-x: auto; }
</style>
</head>
<body>
<a href="/">← Назад к выбору пользователя</a>
<h1>${displayName}</h1>
<span class="badge ${user ? "identified" : "anonymous"}">
${user ? "Идентифицированный пользователь" : "Анонимный посетитель"}
</span>
${user ? `
<h3>Данные идентификации:</h3>
<pre>user-id: ${user.id}\nuser-hash: ${hash}</pre>
` : `
<p>Виджет работает в обычном режиме — случайный ID посетителя.</p>
`}
<p>Откройте виджет в правом нижнем углу и отправьте сообщение.</p>
${scriptTag}
</body>
</html>
`);
});
app.listen(PORT, () => {
console.log("Тестовый сервер запущен: 'тестовый домен'" + PORT);
console.log("Добавьте 'тестовый домен':" + PORT
+ " в разрешённые домены виджета в консоли Cavuer");
});
Запуск¶
node server.js
Откройте указанный домен в браузере.
Нужна помощь?
Если у вас остались вопросы по настройке виджета или по идентификации пользователей, пожалуйста, свяжитесь с нашей службой поддержки.