Обзор

Quickchat AI предоставляет REST API для программного доступа к конфигурации AI-агента, Базе знаний, Разговорам, AI-действиям и другим ресурсам.

Необязательные проверки примеров

• Сравнение способов развёртывания. Сопоставьте указанные каналы, доступ к сайту и нужные функции с вариантами настройки Quickchat AI. Проверка не изучает ваш сайт или аккаунт.

• Проверка примера MCP-подключения. Инициализация и получение списка инструментов только на endpoint документации Cloudflare или Microsoft Learn. Вход и выполнение инструментов не производятся.

Аутентификация

Все endpoints API используют аутентификацию Bearer-токеном. Добавляйте API-токен в заголовок Authorization каждого запроса:

Authorization: Bearer <API_TOKEN>

Токены создаются в панели управления Quickchat в Внешние приложения > API. Каждый токен является JWT, содержащим ваш scenario_id, поэтому дополнительный заголовок с идентификатором не нужен.

• Срок действия токена: 52 недели с момента создания
• Токен можно отозвать в любое время в панели управления
• Каждый токен относится к одному AI-агенту (сценарию)
• Для создания токенов нужен тариф Business или выше; на младших тарифах опция отключена, а endpoint возвращает 402 Payment Required

Заметка

Endpoint чата в реальном времени (POST https://app.quickchat.ai/chat) принимает тот же Bearer-токен, что и остальной API, но находится вне базового пути /v1/api/ и требует scenario_id в теле запроса. Полный справочник см. на странице Чат.

Права токенов

API-токен создаётся с одним из двух наборов прав:

Права	Уровень доступа	Описание
read_all	Только чтение	Можно читать все ресурсы, но нельзя создавать, изменять или удалять
write_all	Чтение и запись	Полный доступ ко всем endpoints, включая операции записи

• Права назначаются при создании токена в Внешние приложения > API
• write_all автоматически включает все права read_all
• Использование токена read_all для endpoint записи возвращает 403 с "Insufficient token scope. Required: write_all"

Совет

Используйте токены read_all для мониторинга, аналитики и интеграций только для чтения. Применяйте write_all, только если интеграции нужно создавать или изменять ресурсы.

Требования к правам по группам endpoints:

Группа endpoints	Чтение	Запись
Настройки чат-бота	read_all	write_all
Настройки Базы знаний	read_all	write_all
Статьи	read_all	write_all
Языковые URL статей	read_all	write_all
Теги	read_all	-
Загрузка файлов	-	write_all
Импорт внешнего содержимого	-	write_all
База знаний Intercom	read_all	write_all
Настройки виджета	read_all	write_all
Разговоры	read_all	-
Метаданные разговора	read_all	write_all
Настройка передачи	read_all	write_all
Оценка разговора	read_all	write_all
AI-действия	read_all	write_all

Базовый URL

Группа endpoints	Базовый URL
База знаний, AI-действия, загрузка файлов, импорт, настройки чат-бота, виджет, передача, оценка разговора	https://app.quickchat.ai/v1/api/
Разговоры	https://app.quickchat.ai/v1/api_core/
Чат в реальном времени	https://app.quickchat.ai/chat

Ограничения частоты запросов

Ограничения применяются отдельно к каждому токену и endpoint.

Категория	Лимит	Применяется к
READ	120 запросов/мин	GET и получение списков
WRITE	60 запросов/мин	POST, PATCH, PUT, DELETE
HEAVY	20 запросов/мин	Загрузка файлов, импорт, извлечение содержимого сайтов

При превышении лимита API возвращает HTTP 429 Too Many Requests.

Webhooks

Quickchat AI не отправляет исходящие webhooks. Нельзя подписаться на событие, чтобы мы отправляли POST на ваш endpoint при поступлении сообщения, передаче или закрытии разговора.

Доступные альтернативы решают разные задачи:

• AI-действия вызывают ваш API во время разговора. API-действия поддерживают режимы AI решает, Перед первым ответом и При совпадении метаданных. Автоматические режимы выполняют попытку вызова один раз за разговор при описанных условиях; это не подписка на каждое сообщение или передачу. Используйте их, например, для записи лида или уведомления системы, когда нужные данные доступны.
• Google Sheets добавляет строку при выполнении действия. Оно не записывает автоматически каждое сообщение или передачу.
• Опрос API разговоров получает сохранённые разговоры и их события, включая сообщения и записанные отметки передачи. Учитывайте пагинацию и лимит READ выше. Опрос добавляет задержку; сравнение состояния между опросами может пропустить промежуточные изменения. Не считайте его полным журналом всех переходов передачи или назначения.

Для API нужен тариф Business; см. Тарифы и лимиты.

Пагинация

Endpoints списков поддерживают пагинацию через параметры запроса:

Параметр	Описание
limit целое число	Число элементов на странице
offset целое число	Число пропускаемых элементов

Ответы с пагинацией имеют следующую структуру:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Обработка ошибок

Все ошибки возвращаются в JSON в следующем формате:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Статус	Код	Описание
400	BAD_REQUEST	Некорректный ввод или отсутствие обязательных полей
401	PERMISSION_DENIED	Недействительный, истёкший или отозванный токен
402	PAYMENT_REQUIRED	Требуется активная подписка
403	PERMISSION_DENIED	Токен не имеет необходимых для операции прав
404	NOT_FOUND	Ресурс не найден
409	CONFLICT	Конфликтующая операция (например, одновременное изменение)
422	VALIDATION_ERROR	Тело запроса не прошло проверку схемы
429	TOO_MANY_REQUESTS	Превышено ограничение частоты
500	UNKNOWN	Внутренняя ошибка сервера
503	SERVICE_UNAVAILABLE	Временная недоступность

---