Огляд

Quickchat AI надає REST API для програмного доступу до налаштувань AI-агента, Бази знань, Розмов, дій AI та інших можливостей.

Необов’язкові перевірки прикладів

• Порівняння способів розгортання. Зіставте вказані канали, доступ до сайту й потрібні функції з варіантами налаштування Quickchat AI. Ваш сайт чи обліковий запис не перевіряються.

• Перевірка тестового підключення MCP. Ініціалізуйте підключення й отримайте список інструментів лише з ендпоїнта документації Cloudflare або Microsoft Learn. Вхід і виконання інструментів не здійснюються.

Автентифікація

Усі ендпоїнти API використовують автентифікацію через Bearer-токен. Додавайте токен API до заголовка Authorization кожного запиту:

Authorization: Bearer <API_TOKEN>

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

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

Заувага

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

Області доступу токенів

Токени API створюються з однією з двох областей доступу:

Область доступу	Рівень доступу	Опис
read_all	Лише читання	Можна читати всі ресурси, але не створювати, оновлювати чи видаляти
write_all	Читання та запис	Повний доступ до всіх ендпоїнтів, зокрема операцій запису

• Область доступу призначається під час створення токена в Зовнішні застосунки > API
• Область write_all автоматично включає всі дозволи read_all
• Використання токена read_all на ендпоїнті запису повертає 403 із "Insufficient token scope. Required: write_all"

Порада

Використовуйте токени read_all для моніторингу, аналітики й інтеграцій лише для читання. Токени write_all потрібні лише тоді, коли інтеграція створює або змінює ресурси.

Вимоги до області доступу за групами ендпоїнтів:

Група ендпоїнтів	Операції читання	Операції запису
Налаштування чатбота	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-адреса

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

Обмеження частоти запитів

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

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

Коли ліміт перевищено, API повертає HTTP 429 Too Many Requests.

Вебхуки

Quickchat AI не надсилає вихідні вебхуки. Неможливо підписатися на подію й отримати від нас POST на ваш ендпоїнт, коли надходить повідомлення, розмова передається оператору або закривається.

Доступні альтернативи виконують різні завдання:

• Дії AI викликають ваш API під час розмови. Дії API мають режими AI вирішує, Перед першою відповіддю та За збігу метаданих. Автоматичні режими намагаються виконати один виклик на розмову за описаних умов; це не підписки на кожне повідомлення чи передавання. Використовуйте їх, наприклад, для запису ліда або сповіщення вашої системи, коли зібрано потрібні дані.
• Google Sheets додає рядок під час виконання відповідної дії. Усі повідомлення чи передавання автоматично не записуються.
• Опитування API розмов отримує збережені розмови та їхні події, зокрема повідомлення й записані маркери передавання. Дотримуйтеся правил пагінації та ліміту READ вище. Опитування створює затримку; порівняння стану між запитами може пропустити проміжні зміни. Не вважайте це вичерпною історією всіх передавань чи змін виконавця.

Доступ до API потребує тарифу Business; див. Тарифи й ліміти.

Пагінація

Ендпоїнти списків підтримують пагінацію через параметри запиту:

Параметр	Опис
limit integer	Кількість елементів на сторінці
offset integer	Кількість елементів, які слід пропустити

Відповіді з пагінацією мають таку структуру:

{
  "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	Тимчасова недоступність

---