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

Подключение с Claude

Подключение, наполнение базы знаний или план её обновления - выберите нужное задание для Claude Code.

Перед запуском замените YOUR_ASSISTANT_ID и https://your-site.example своими значениями или скопируйте заполненный промпт из кабинета. Введите команду claude в каталоге проекта и вставьте задание. Как начать работу с Claude Code.

При подключении проверьте реальный ответ чата. Для наполнения и обновления базы знаний Claude сначала составит план. Ответьте Начать работу, чтобы подтвердить его и перейти к реализации. Включение регулярной синхронизации согласуется отдельно после проверки. Использование Claude не меняет модель, которой отвечает ваш ассистент.

Контракты API (Markdown) · Полная текстовая инструкция для Claude · Указатель документации для ИИ. Claude найдёт здесь описание API и готовые примеры подключения.

Выберите способ интеграции

Поручите подключение Claude, добавьте готовый виджет или создайте свой интерфейс через API.

Встраивание через скрипт

В мастере настройки добавьте разрешённые адреса сайта и получите оба ключа. Замените YOUR_PUBLIC_KEY публичным ключом ca_pk_… и добавьте скрипт один раз в общий шаблон страниц.

Copy<script async src="https://contextassistant.io/assets/embed.js"
  data-public-key="YOUR_PUBLIC_KEY"
  referrerpolicy="no-referrer"></script>

Скрипт сам подключает и запускает виджет. Второй вызов mount(), локальная копия SDK и обработчик токенов на вашем сервере не нужны. CA создаёт и продлевает гостевые сессии. Секрет синхронизации в код страницы не добавляйте.

Выберите Lite/Advanced и приветствие в кабинете. При загрузке страницы виджет получает совместимые обновления по тому же адресу. Полный HTML-пример со сведениями об открытой странице.

Для управления используйте window.ContextAssistantWidget или event.detail.widget события context-assistant:ready: open(), close(), setContext(), clearContext(), destroy(). Передавайте только согласованные сведения о странице, не весь DOM и не личные данные.

Copyimport { mount } from '@context-assistant/embed-sdk';

const widget = mount({
  apiUrl: 'https://api.contextassistant.io',
  publicKey: 'YOUR_PUBLIC_KEY',
  title: 'Store Consultant',
  appearance: {
    variant: 'refined',
    theme: 'system',
    welcomeMessage: 'How can I help with this product?',
    starterPrompts: ['Is it in stock?', 'Compare the available options'],
    privacyUrl: '/privacy/',
  },
});

widget.setContext({
  page: { type: 'product', id: 184 },
});

Виджет для React

Используйте тот же виджет с нашего сайта. Если чат нужен во всём приложении, добавьте скрипт выше один раз в общий шаблон приложения. Устанавливать пакеты Context Assistant или добавлять серверный маршрут токенов не нужно.

Если виджет должен появляться и удаляться вместе с компонентом, скопируйте react-widget.tsx в проект и явно передайте публичный ключ:

Copy<ContextAssistantWidget
  publicKey="YOUR_PUBLIC_KEY"
  page={{ type: "product", id: 184 }}
/>

Выберите один способ: автоматический скрипт или этот компонент. Не добавляйте оба. Компонент загружает тот же файл, создаёт виджет в браузере и вызывает destroy() при размонтировании. Меняйте page при переходе к другому товару. В этом совместимом примере отсутствие publicKey включает приватную серверную схему, поэтому для публичного чата обязательно укажите ключ.

Copyimport { ContextAssistantProvider, Assistant } from '@context-assistant/react';


export function App() {
  return (
    <ContextAssistantProvider apiUrl="https://api.contextassistant.io" publicKey="YOUR_PUBLIC_KEY">
      <Assistant
        title="Store Consultant"
        appearance={{
          variant: 'refined',
          theme: 'system',
          welcomeMessage: 'How can I help with this product?',
          starterPrompts: ['Is it in stock?', 'Compare the available options'],
          privacyUrl: '/privacy/',
        }}
      />
    </ContextAssistantProvider>
  );
}

JavaScript API и SDK

Для готового чата достаточно скрипта выше. API нужен, если вы создаёте свой интерфейс: обменяйте публичный ключ через POST /v1/embed/public-token, затем обращайтесь к Conversations API с временным Bearer-токеном. Обработчик токенов на вашем сервере для публичного чата не нужен.

В собственном API-клиенте нужно учитывать срок сессии, сохранять visitorToken для продления, обрабатывать SSE-ответы и соблюдать Retry-After. Готовый виджет делает это сам. Публичный ключ не загружает знания: для синхронизации нужен отдельный секрет на сервере.

Copyimport { ConversationSession } from '@context-assistant/js-sdk';

const session = new ConversationSession({
  apiUrl: 'https://api.contextassistant.io',
  publicKey: 'YOUR_PUBLIC_KEY',
});

await session.send('What pairs well with this processor?', {
  onToken: (delta) => console.log(delta),
  onDone: (event) => console.log('\n[done]', event.message),
});

Личные заказы, закрытые документы и Remote Tools требуют серверной авторизации. Существующие приватные подключения сохраняйте; не заменяйте их ключи публичным.

Сессия публичного чата

POST /v1/embed/public-token. Без Authorization. Используется заголовок Origin браузера, не поле тела. Нужен действующий ca_pk_, явно выданный в мастере настройки, и точный разрешённый origin. Пустой список запрещает доступ.

Copy{
  "publicKey": "YOUR_PUBLIC_KEY",
  "visitorToken": "OPTIONAL_PREVIOUS_VISITOR_TOKEN"
}

200, Cache-Control: no-store:

Copy{
  "token": "SHORT_LIVED_ACCESS_JWT",
  "expiresAt": "2026-09-14T12:15:00Z",
  "visitorToken": "SIGNED_GUEST_RENEWAL_CREDENTIAL"
}

При первом запросе пропустите visitorToken; для продления того же гостя передайте значение из ответа. Оно истекает через 30 дней без продления и не принимается как Bearer чата. Для чата, config и context используйте token в Bearer с тем же Origin. SDK управляет кешированием, единым запросом обновления и хранением гостевой сессии. Внешний user ID не передавайте: его генерирует сервер. Публичный доступ не даёт прав управления и Remote Tools. Ошибки: 400 invalid_input; 401 visitor_expired; 403 origin_not_allowed/public_access_denied; 429 rate_limited; 503 not_configured. Бесконечные повторы недопустимы. Отзыв ключа и изменение origins учитываются на последующих запросах.

Выданный визардом ключ синхронизации имеет knowledge:read, knowledge:write и assistants:read в своём рабочем пространстве, без embed:token. Храните CONTEXT_ASSISTANT_SYNC_KEY только в серверной .env; добавьте .env в .gitignore. ca_pk_ не позволяет загружать знания. Существующие секретные ключи и POST /v1/embed/token не меняются.

HTTP API: авторизация и правила запросов

Все контракты одним файлом (Markdown)

Базовый адрес REST API: https://api.contextassistant.io/v1. Отправляйте JSON с Content-Type: application/json. Идентификаторы в примерах нужно заменить своими. В настройках виджета адрес указывается без /v1: SDK добавляет этот префикс сам.

Права ключей не взаимозаменяемы: embed:token не позволяет загружать документы. Маршруты /v1/cabinet/* используют сессию кабинета и не предназначены для серверной интеграции. /api/core и /api/embed-token относятся к нашему сайту.

Copycurl --fail-with-body "https://api.contextassistant.io/v1/assistants" \
  -H "Authorization: Bearer ${CONTEXT_ASSISTANT_SYNC_KEY}"

Команда использует ключ, уже заданный в окружении сервера. Не вставляйте его значение в промпт или исходники. Запросы записи применяются сразу: предпросмотр и подтверждение реализуются в вашем импорте или интерфейсе. Параметра dry-run у API нет.

Как получить идентификаторы ассистента

GET /v1/assistants -> 200 { "items": [...] }. GET /v1/assistants/{publicId} -> 200 с объектом одного ассистента. Оба запроса требуют assistants:read; в пути используется Public ID, не UUID.

Copy{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "workspaceId": "44444444-4444-4444-8444-444444444444",
      "publicId": "asst_example",
      "name": "Store assistant",
      "profile": "general",
      "instructions": "",
      "modelConfig": {},
      "toolPolicy": {},
      "allowedOrigins": [
        "https://shop.example"
      ],
      "createdAt": "2026-09-10T12:00:00Z",
      "updatedAt": "2026-09-10T12:00:00Z"
    }
  ]
}

POST /v1/embed/token

Серверный ключ с embed:token. JSON-тело до 4 KiB. Обязательный assistantId - Public ID. В origin укажите настроенные схему, домен и порт из разрешённых адресов ассистента. user.externalId берите из проверенной серверной сессии или подписанной cookie конкретного гостя; user.name необязателен.

Copy{
  "assistantId": "asst_example",
  "origin": "https://shop.example",
  "user": {
    "externalId": "member_42",
    "name": "Alex"
  }
}

Ответ 200:

Copy{
  "token": "<temporary JWT>",
  "expiresAt": "2026-09-10T12:15:00Z"
}

Ориентируйтесь на expiresAt при обновлении токена. Верните браузеру только эти два поля и Cache-Control: no-store. Токен определяет ассистента и посетителя. Разрешённый origin не подтверждает вход пользователя; публичному обработчику токенов нужна защита от злоупотреблений. Не объединяйте гостей под одним ID.

Диалоги и потоковые ответы

Все маршруты ниже требуют embed-токен. Начните с POST /v1/conversations, тело { "title": "Delivery question" } (title необязателен). Ответ 201:

Copy{
  "id": "55555555-5555-4555-8555-555555555555",
  "assistantId": "asst_example",
  "title": "Delivery question",
  "createdAt": "2026-09-10T12:00:00Z",
  "updatedAt": "2026-09-10T12:00:00Z"
}

Отправьте POST /v1/conversations/{id}/messages. Обязательное поле content - непустая строка. Необязательный context содержит небольшие структурированные сведения о странице; не весь DOM и не персональные данные. Лимит JSON-тела - 64 KiB. Поле agent пропустите: Public ID в этом поле вызывает unknown agent profile.

Copy{
  "content": "How long does delivery take?",
  "context": {
    "page": {
      "type": "product",
      "id": 184
    }
  }
}

Copycurl -N --fail-with-body "https://api.contextassistant.io/v1/conversations/${CONVERSATION_ID}/messages" \
  -H "Authorization: Bearer ${EMBED_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @message.json

Сохраните JSON выше в message.json в UTF-8. Успешный ответ - HTTP 200 text/event-stream, а не один JSON-документ. Собирайте события SSE независимо от границ сетевых фрагментов. Пример:

Copyevent: token
data: {"delta":"Delivery takes 2-4 business days."}

event: done
data: {"conversationId":"55555555-5555-4555-8555-555555555555","userMessageId":"user-message-uuid","messageId":"reply-message-uuid","message":"Delivery takes 2-4 business days.","model":"model-id","agent":"general","title":"Delivery question"}

События: token содержит delta; done - итоговый ответ; pending_action - предложенное действие; error - code/error и завершение неудачного потока. В done также могут быть suggestions и references. HTTP 200 сам по себе не подтверждает завершённый ответ. Повторная отправка может создать второе сообщение: после обрыва сначала проверьте историю.

Для постраничных списков limit по умолчанию равен 20, максимум - 100; неверный/неположительный limit или неверный cursor дают 400. Передавайте nextCursor с URL-кодированием, пока он не исчезнет из ответа. Сообщения идут от старых к новым, диалоги - по последней активности. Перед удалением диалога запросите подтверждение.

POST /v1/context/validate

Embed-токен. Необязательная предварительная проверка сведений о странице; чат проверяет их повторно. JSON-тело до 16 KiB, очищенный context до 4096 байт, глубина вложенности до 6. Разрешённые поля верхнего уровня: application, workspaceId, page, selection, entity, site. Остальные поля удаляются, строки, похожие на секреты, скрываются. Эти сведения не дают прав доступа и не меняют рабочее пространство из токена.

Copy{
  "context": {
    "page": {
      "type": "product",
      "id": 184
    }
  }
}

Ответ 200; если данные изменены при очистке, также могут присутствовать массивы droppedFields и redactedPaths:

Copy{
  "context": {
    "page": {
      "type": "product",
      "id": 184
    }
  }
}

Коды 400: invalid_input при неверном JSON-теле; context_not_an_object, context_too_large, context_too_deep или invalid_context при недопустимом context. Этот запрос не добавляет материалы в базу знаний.

API базы знаний: создание источника

POST /v1/knowledge/sources, серверный ключ с knowledge:write. Обязательны assistantId (внутренний UUID) и непустой name. type необязателен, по умолчанию manual; это только метка, она не запускает обход сайта или расписание. Лимит тела - 256 KiB.

Copy{
  "assistantId": "11111111-1111-4111-8111-111111111111",
  "name": "Store help",
  "type": "manual"
}

Ответ 201. Сохраните id как sourceId и его связь с ассистентом в своих настройках:

Copy{
  "id": "22222222-2222-4222-8222-222222222222",
  "name": "Store help",
  "type": "manual",
  "createdAt": "2026-09-10T12:00:00Z"
}

GET /v1/knowledge/sources требует knowledge:read и возвращает 200 { "items": [...] } для рабочего пространства, без пагинации. Объекты источников не содержат assistantId. Не определяйте владельца по имени и не создавайте новый источник при каждом импорте.

POST /v1/knowledge/documents

Серверный ключ с knowledge:write. Создание или обновление одного документа:

Copy{
  "sourceId": "22222222-2222-4222-8222-222222222222",
  "externalId": "help:delivery:en",
  "title": "Delivery",
  "contentType": "markdown",
  "content": "# Delivery\nDelivery takes 2-4 business days."
}

Copycurl --fail-with-body "https://api.contextassistant.io/v1/knowledge/documents" \
  -H "Authorization: Bearer ${CONTEXT_ASSISTANT_SYNC_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

Сохраните пример в document.json в UTF-8. Новый документ возвращает 201:

Copy{
  "id": "33333333-3333-4333-8333-333333333333",
  "sourceId": "22222222-2222-4222-8222-222222222222",
  "externalId": "help:delivery:en",
  "title": "Delivery",
  "contentType": "markdown",
  "status": "pending",
  "createdAt": "2026-09-10T12:00:00Z",
  "syncStatus": "created"
}

Идентичность документа - пара (sourceId, externalId). Изменения возвращают 200 updated с тем же id; одинаковый текст и метаданные - unchanged. Изменение только title/card обновляет метаданные без повторной векторизации готового документа. Изменение content ставит документ на индексацию. Без externalId каждый POST создаёт новый документ. PATCH для документа нет.

Copy{
  "sourceId": "22222222-2222-4222-8222-222222222222",
  "externalId": "product:42:ru",
  "title": "Кресло Oslo",
  "contentType": "text",
  "content": "Кресло Oslo: светлый дуб, серая ткань. Цена 120 EUR.",
  "card": {
    "title": "Кресло Oslo",
    "url": "https://shop.example/products/42",
    "image": "https://shop.example/images/42.jpg",
    "subtitle": "120 EUR",
    "badges": [
      "Светлый дуб",
      "Серая ткань"
    ]
  }
}

Карточки выбираются из результатов базы знаний без Remote Tools. Сервер передаёт сохранённые поля в references ответа чата. Изображения задаются ссылками: файлы не загружаются и не анализируются. Обновляйте цены и наличие синхронизацией: карточки из базы знаний не проверяют склад в реальном времени. Сейчас карточки видны в текущем ответе; при повторной загрузке истории восстанавливается текст, но не карточки.

syncStatus описывает результат записи, а не готовность индекса. status принимает pending, processing, ready или failed. URL в content не скачивается. PDF и изображения перед загрузкой преобразуйте в проверенный текст. Загружайте только материалы, доступные аудитории ассистента: источник не задаёт индивидуальные права посетителей.

POST /v1/knowledge/documents/bulk

В текущем контракте API есть пакетная загрузка с knowledge:write: 1-100 документов, externalId обязателен у каждого, JSON-тело до 8 MiB, content каждого документа до 256 KiB. Повторяющиеся пары (sourceId, externalId) внутри пакета отклоняются. Проверьте доступность маршрута в своём окружении; если bulk недоступен, используйте одиночные запросы.

Copy{
  "documents": [
    {
      "sourceId": "22222222-2222-4222-8222-222222222222",
      "externalId": "help:delivery:en",
      "title": "Delivery",
      "contentType": "markdown",
      "content": "# Delivery\nDelivery takes 2-4 business days."
    }
  ]
}

Ответ 200, по одному результату на документ в порядке запроса:

Copy{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "sourceId": "22222222-2222-4222-8222-222222222222",
      "externalId": "help:delivery:en",
      "title": "Delivery",
      "contentType": "markdown",
      "status": "pending",
      "createdAt": "2026-09-10T12:00:00Z",
      "syncStatus": "created"
    }
  ],
  "created": 1,
  "updated": 0,
  "unchanged": 0
}

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

Проверка индексации и постраничная загрузка

GET /v1/knowledge/documents?limit=100 требует knowledge:read. В ответе 200 items содержат id, sourceId, необязательный externalId, title, необязательный card, contentType, status, необязательный error и createdAt. Исходный content, checksum и syncStatus в списке не возвращаются.

Copy{
  "items": [
    {
      "id": "33333333-3333-4333-8333-333333333333",
      "sourceId": "22222222-2222-4222-8222-222222222222",
      "externalId": "help:delivery:en",
      "title": "Delivery",
      "contentType": "markdown",
      "status": "ready",
      "createdAt": "2026-09-10T12:00:00Z"
    }
  ],
  "nextCursor": "<opaque cursor; omitted on last page>"
}

limit по умолчанию 20, максимум 100; неверные/неположительные значения и неверные курсоры возвращают 400. Передавайте nextCursor с URL-кодированием, пока он не исчезнет. Список относится ко всему рабочему пространству, не к одному ассистенту или источнику. Фильтруйте sourceId в импорте. Фильтра sourceId в query и GET /documents/{id} нет; нужный документ ищется по id в постраничном списке.

Опрашивайте с паузами и предельным временем ожидания. ready означает, что документ проиндексирован; реальные ответы всё равно нужно проверить. При failed разберите error без вывода закрытого содержимого. Повторная отправка неизменного failed-документа не запускает индексацию заново. Сохраняйте исходные материалы у себя и сообщайте о сбое вместо бесконечных повторов.

Обновления, корзина и безопасная синхронизация

Восстановление может вернуть 409 conflict, если активный документ уже занимает пару (sourceId, externalId). Не удаляйте ни одну версию автоматически. Маршруты удаления не реализуют ваш процесс согласования: сначала покажите предпросмотр и получите отдельное двойное подтверждение. DELETE источника и purge не подходят для обычной очистки при синхронизации.

Стройте синхронизацию вокруг постоянного sourceId и стабильных externalId. Сравнивайте кандидатов на удаление только внутри этого источника, после полной успешной выгрузки и чтения всех страниц списка документов. Недоступность источника, пустая частичная выгрузка или пропущенная страница не должны приводить к массовому удалению. По умолчанию используйте dry-run, сохраняйте исходный контент и журнал запусков, останавливайтесь при необычно большом числе удалений. Расписание, webhook и чтение источника реализуются в проекте клиента; этот API не создаёт обходчик сайтов.

Ошибки и ограничения запросов

Copy{
  "code": "forbidden",
  "error": "the API key lacks the required scope"
}

Лимиты тела: токен 4 KiB; чат 64 KiB; одиночный запрос знаний 256 KiB; bulk 8 MiB и до 256 KiB content на элемент. Прокси может ограничивать размер сильнее и возвращать не-JSON ошибки, например 413. Проверяйте HTTP-статус и тип ответа перед разбором. Для POST с SSE в браузере используйте fetch с Authorization, а не EventSource.