Чат

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

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

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

Чат

Endpoint чата в реальном времени отправляет сообщение посетителя AI-агенту и возвращает ответ AI за один запрос. Используйте его для создания собственного интерфейса чата на базе Quickchat AI.

Он отличается от других endpoints в двух отношениях: расположен на 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 строка, обязательный	ID AI-агента. Должен совпадать с scenario_id, привязанным к Bearer-токену
text строка, обязательный	Сообщение пользователя
conv_id строка	ID разговора. Не указывайте в первом запросе, чтобы начать новый разговор, затем передавайте полученный conv_id в следующих запросах для продолжения
client_metadata объект	Пользовательские пары ключ-значение (рекомендуем не более 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 строка	Идентификатор разговора. Возвращается всегда. Передайте его в поле тела conv_id, чтобы продолжить разговор
reply строка	Ответ AI-агента. Может содержать HTML, например переносы строк <br>
ord_number целое число	Последовательный номер сообщения в разговоре
src целое число	Внутренний индикатор источника. Клиенты 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()

Метаданные клиента

Endpoint чата принимает необязательный параметр 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"},
}

Ошибки

Endpoint чата возвращает текстовое сообщение об ошибке с соответствующим 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	Сервис недоступен	Серверы временно перегружены или обслуживаются. Если проблема сохраняется, свяжитесь с поддержкой