Чат

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

• Попередній перегляд запиту дії API. Побудуйте запит із наданого шаблону й синтетичних тестових значень без надсилання. Не додавайте заголовки з обліковими даними.

• Попередній перегляд ключів метаданих. Перевірте, як надані назви полів перетворюються на ключі змінних, зокрема дублікати назв і помилки зарезервованих ключів. Значення та дозволи конкретного облікового запису не перевіряються.

Чат

Ендпоїнт чату в реальному часі надсилає повідомлення відвідувача AI-агенту й повертає відповідь за один запит. Використовуйте його, щоб створити власний інтерфейс чату на основі Quickchat AI.

Він відрізняється від інших ендпоїнтів двома рисами: розташований за адресою app.quickchat.ai/chat, поза базовими шляхами /v1/api/ і /v1/api_core/, та читає scenario_id із тіла запиту, а не з токена. Автентифікація через Bearer-токен така сама, як у решті API.

Заувага

Надсилайте всі запити на https://app.quickchat.ai/chat. Поле scenario_id у тілі має відповідати AI-агенту, до якого прив’язаний Bearer-токен.

Надсилання повідомлення

POST https://app.quickchat.ai/chat

Тіло запиту

Параметр	Опис
scenario_id string, обов’язковий	ID AI-агента. Має збігатися з scenario_id, до якого прив’язаний Bearer-токен
text string, обов’язковий	Повідомлення користувача
conv_id string	ID розмови. Не передавайте в першому запиті, щоб почати нову розмову, а потім передавайте отриманий conv_id у наступних запитах для її продовження
client_metadata object	Власні пари ключ-значення (рекомендуємо не більше 5 ключів), що додаються до кожного повідомлення. Показуються як стовпці даних в експорті розмов із Вхідних

Запит без conv_id починає нову розмову, а згенерований conv_id повертається у відповіді. Збережіть цей conv_id і надсилайте в подальших запитах, щоб підтримувати контекст розмови між взаємодіями користувача.

Shell

# Start a new conversation by omitting conv_id
curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "text": "Hello!",
    },
)
data = response.json()

Відповідь 200 OK

{
  "conv_id": "conv-uuid-1234",
  "reply": "Hi there! How can I help you today?",
  "ord_number": 3,
  "src": 0
}

Поле	Опис
conv_id string	Ідентифікатор розмови. Повертається завжди. Передавайте його в полі тіла conv_id для продовження розмови
reply string	Відповідь AI-агента. Може містити HTML, наприклад перенесення рядків <br>
ord_number integer	Порядковий номер повідомлення в розмові
src integer	Внутрішній індикатор джерела. Клієнти API можуть ігнорувати це поле

Щоб продовжити наявну розмову, передайте отриманий conv_id:

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "What is your return policy?"
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "What is your return policy?",
    },
)
data = response.json()

Клієнтські метадані

Ендпоїнт чату приймає необов’язковий параметр client_metadata: власні атрибути, які додаються до кожного нового повідомлення й показуються як стовпці в експорті розмов із Вхідних. Ті самі атрибути можна передавати через віджет. Рекомендуємо надсилати не більше 5 ключів одночасно, наприклад {"userId": 12, "website": "mywebsite.com"}. Це рекомендація, а не обмеження API.

Shell

curl -X POST https://app.quickchat.ai/chat \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "conv-uuid-1234",
  "text": "Hello!",
  "client_metadata": {"userId": 12, "website": "mywebsite.com"}
}'

Python

import requests

response = requests.post(
    url="https://app.quickchat.ai/chat",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "scenario_id": "<SCENARIO_ID>",
        "conv_id": "conv-uuid-1234",
        "text": "Hello!",
        "client_metadata": {"userId": 12, "website": "mywebsite.com"},
    },
)
data = response.json()

Фільтрування Бази знань за тегами

До статей Бази знань можна додавати теги і обмежувати ними джерела AI, щоб він відповідав лише на основі частини Бази знань. Наразі це фільтрування підтримується лише через API.

Для фільтрування додайте ключ kb_topic до client_metadata. Ключ kb_topic має бути в кожному запиті розмови, включно з першим. Значення може змінюватися між запитами, але для застосування фільтра сам ключ має бути присутнім упродовж усієї розмови.

У прикладі нижче до можливих джерел відповіді входять усі статті з тегом your-topic або без жодного тегу.

json={
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "conv-uuid-1234",
    "text": "Hello!",
    "client_metadata": {"kb_topic": "your-topic"},
}

Помилки

Ендпоїнт чату повертає повідомлення про помилку звичайним текстом із відповідним статусом HTTP.

Статус	Опис	Дія
400	Відсутній scenario_id або облікові дані	Додайте scenario_id до тіла й коректний заголовок Authorization: Bearer <API_TOKEN>
400	Некоректний conv_id (Conversation conv_id <id> is not valid.)	Не передавайте conv_id, щоб почати нову розмову, або передайте conv_id із попередньої відповіді
401	Недійсні облікові дані (Unauthorized.)	Перевірте, що Bearer-токен або ключ API дійсний для цього scenario_id
404	Невідомий scenario_id (No implementation found for scenario_id <id>)	Перевірте scenario_id і прив’язку Bearer-токена до нього
500	Внутрішня помилка сервера	Проблема з нашого боку. Зв’яжіться з підтримкою
503	Сервіс недоступний	Сервери тимчасово перевантажені або обслуговуються. Якщо проблема не зникає, зверніться до підтримки