Документация

Витрима — встраиваемый AI-чат

Витрима — SaaS-платформа, которая позволяет добавить умного AI-консультанта на любой сайт за 5 минут. Этот раздел — полный гид по установке, API, брендингу и безопасности.

Если вы только что зарегистрировались — начните с раздела Установка виджета. Если интересен прямой доступ к данным сессий — смотрите REST API.

Установка виджета

Самый простой способ — один тег <script> в шапке сайта. Виджет смонтируется автоматически в правом нижнем углу.

<script
  src="https://app.vitrima.pro/widget-loader.js"
  data-vitrima-key="vit_••••••••"
  data-vitrima-host="https://app.vitrima.pro"
  defer
></script>

Где взять ключ? В кабинете на странице «Обзор».
Куда вставлять? В блок <head> или перед закрытием </body>.
Сколько весит? Лоадер около 12 КБ; сам чат подгружается ленивым iframe только после первого открытия.

Альтернатива: iframe вручную

Если вы хотите контролировать положение виджета или сделать его inline — используйте iframe напрямую.

<iframe
  src="https://app.vitrima.pro/widget?apiKey=vit_••••••••"
  style="width:380px;height:560px;border:0;border-radius:20px;"
  loading="lazy"
  title="Vitrima AI Chat"
></iframe>

В URL ?apiKey=… — это один из способов авторизации виджета. Для работы привязки к домену встройте через официальные скрипты выше или отдавайте страницу с родителем того же origin (иначе API вернёт отказ). Сессии хранятся в localStorage вашего домена и автоматически продолжаются между визитами.

Брендинг

Параметры брендинга задаются на странице Кабинет → Брендинг:

Имя ассистента — отображается в шапке виджета.
Цвет акцента — кнопки, пузыри, фокус-рамки. HEX, например #7c6cf8.
Логотип — URL на прозрачный PNG / SVG, отрисуется в шапке (~32px высотой).
Тон голоса и системный промпт — добавляются к промпту модели. Опишите роль, ограничения, формат ответов.

REST API

Все эндпоинты живут под /api/ai-brief/embed и требуют заголовков X-Api-Key (или Authorization: Bearer …) и X-Vitrima-Embed-Parent — origin сайта, где показывается виджет (например https://example.com). Первый успешный запрос привязывает ключ к этому домену.

GET /branding

Получить публичные параметры бренда: имя, цвет, логотип.

curl https://app.vitrima.pro/api/ai-brief/embed/branding \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com"

POST /sessions

Создать новую сессию диалога.

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /sessions/:id/messages

Отправить сообщение от пользователя и получить ответ модели.

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions/SID/messages \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com" \
  -H "Content-Type: application/json" \
  -d '{"content":"Здравствуйте"}'

POST /sessions/:id/site-photo

Загрузить фото участка (multipart, поле image). Файл сохраняется в сессии и передаётся модели при каждом сообщении и при генерации фасада (если провайдер поддерживает референс).

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions/SID/site-photo \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com" \
  -F "image=@plot.jpg"

Удалить фото: DELETE /sessions/:id/site-photo с теми же заголовками.

POST /sessions/:id/confirm-concept-for-tz

Зафиксировать переход клиента к этапу ТЗ после выбора концепции (хотя бы одна визуализация уже есть). До этого запроса ответы модели не поднимают briefPhase выше концепции — можно безопасно уточнять фасад и перегенерировать изображение.

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions/SID/confirm-concept-for-tz \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com"

Webhooks

Чтобы получать события (новые лиды / сообщения) на свой сервер — задайте URL webhook в Кабинете → Брендинг и опционально HMAC-secret.

Витрима отправит POST-запрос с подписью:

POST https://your-crm/api/vitrima
X-Vitrima-Signature: sha256=<hmac(sha256, secret, body)>
Content-Type: application/json

{
  "type": "session.completed",
  "tenantId": "...",
  "session": { "_id": "...", "messages": [...] }
}

Проверяйте подпись перед обработкой — это защитит от подделки. Подпись рассчитывается по сырому телу запроса.

Безопасность ключа

Полный ключ показывается один раз при создании или перевыпуске. На сервере хранится только bcrypt-хеш.
Если потеряли ключ — нажмите «Перегенерировать» в кабинете. Старый перестанет работать сразу.
«Деактивировать» — мягкое отключение: tenant остаётся, но виджет перестаёт авторизоваться. Можно выпустить новый ключ когда нужно.
Ключ ходит в HTTPS. По возможности храните его в backend и проксируйте запросы — для frontend-only сайтов используйте ?apiKey или data-attribute, понимая, что любой посетитель сможет его увидеть.

Лимиты и тарифы

Тариф	Сообщений / мес	Изображений / мес	Цена
Start	1 000	150	4 900 ₽ / мес
Pro	10 000	500	12 900 ₽ / мес
Studio	200 000	1 500	29 900 ₽ / мес
Внедрение	индивидуально	индивидуально	150 000 – 500 000 ₽ разово + от 49 000 ₽ / мес

Лимиты считаются в календарном месяце по UTC. При превышении виджет сообщает пользователю «лимит исчерпан» и продолжит работать после переключения тарифа в один клик. Сверх включённого пакета генераций — оплата по факту (30 ₽ за генерацию).

Поддержка

Telegram: @vitrimaru
E-mail: vitrima.pro@gmail.com

Не нашли ответ? Напишите нам — обычно отвечаем в течение нескольких часов в рабочее время.