Chat

Chat

Endpoint Chat w czasie rzeczywistym wysyła wiadomość odwiedzającego do Twojego AI Agenta i zwraca odpowiedź AI w pojedynczym żądaniu. To endpoint, którego potrzebujesz, budując własny interfejs czatu na bazie Quickchat AI.

Różni się od pozostałych endpointów na dwa sposoby: znajduje się pod app.quickchat.ai/chat, poza ścieżkami bazowymi /v1/api/ i /v1/api_core/, oraz odczytuje scenario_id z body żądania, a nie z tokena. Korzysta z tego samego uwierzytelniania Bearer tokenem co reszta tego API.

Notatka

Wysyłaj każde żądanie na https://app.quickchat.ai/chat. Wartość scenario_id w body musi odpowiadać AI Agentowi, do którego przypisany jest Twój Bearer token.

Send Message

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

Request Body

Parameter	Description
scenario_id string, required	ID Twojego AI Agenta. Musi odpowiadać wartości scenario_id przypisanej do Bearer tokena
text string, required	Wiadomość wprowadzona przez użytkownika
conv_id string	ID rozmowy. Pomiń w pierwszym żądaniu, aby rozpocząć nową rozmowę, a następnie przekazuj zwrócone conv_id w kolejnych żądaniach, aby ją kontynuować
client_metadata object	Niestandardowe pary klucz-wartość (zalecamy maksymalnie 5 kluczy) dołączane do każdej wiadomości. Wyświetlane jako kolumny danych w eksporcie rozmów w Inboksie

Żądanie bez conv_id rozpoczyna nową rozmowę, a wygenerowane conv_id jest zwracane w odpowiedzi. Zapisz to conv_id i odsyłaj je w kolejnych żądaniach, aby zachować kontekst rozmowy przez wiele interakcji użytkownika.

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()

Response 200 OK

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

Field	Description
conv_id string	Identyfikator rozmowy. Zawsze zwracany. Przekaż go z powrotem w polu body conv_id, aby kontynuować rozmowę
reply string	Odpowiedź AI Agenta. Może zawierać HTML, np. łamania linii <br>
ord_number integer	Kolejny numer wiadomości w rozmowie
src integer	Wewnętrzny wskaźnik źródła. Klienci API mogą zignorować to pole

Aby kontynuować istniejącą rozmowę, przekaż z powrotem otrzymane 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

Endpoint Chat akceptuje opcjonalny parametr client_metadata: niestandardowe atrybuty przypisywane do każdej nowej wiadomości i wyświetlane jako kolumny danych w eksporcie rozmów w Inboksie. Te same atrybuty możesz dołączyć przez widget. Zalecamy wysyłanie maksymalnie 5 kluczy naraz, na przykład {"userId": 12, "website": "mywebsite.com"}. To zalecenie, a nie limit wymuszany przez 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()

Knowledge Base Tag Filtering

Możesz dodawać tagi do artykułów Bazy Wiedzy i używać ich, aby ograniczyć, z których artykułów korzysta AI, tak by odpowiadał tylko na podstawie podzbioru Bazy Wiedzy. To filtrowanie jest obecnie obsługiwane wyłącznie przez API.

Aby filtrować według tagu, dodaj klucz kb_topic do client_metadata. Klucz kb_topic musi być obecny w każdym żądaniu rozmowy, w tym w żądaniu, które ją rozpoczyna. Jego wartość może się zmieniać między żądaniami, ale sam klucz musi być obecny przez całą rozmowę, aby filtr zadziałał.

W poniższym przykładzie do puli kandydatów wiedzy dla odpowiedzi trafia każdy artykuł oznaczony tagiem your-topic lub bez żadnego tagu.

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

Errors

Endpoint Chat zwraca komunikat błędu w postaci zwykłego tekstu wraz z odpowiednim kodem statusu HTTP.

Status	Description	Action
400	Brak scenario_id lub brak podanych poświadczeń	Dołącz scenario_id w body oraz prawidłowy nagłówek Authorization: Bearer <API_TOKEN>
400	Nieprawidłowe conv_id (Conversation conv_id <id> is not valid.)	Pomiń conv_id, aby rozpocząć nową rozmowę, lub przekaż conv_id zwrócone przez wcześniejszą odpowiedź
401	Nieprawidłowe poświadczenia (Unauthorized.)	Sprawdź, czy Twój Bearer token lub klucz API jest prawidłowy dla tego scenario_id
404	Nieznane scenario_id (No implementation found for scenario_id <id>)	Zweryfikuj scenario_id oraz to, że Twój Bearer token jest do niego przypisany
500	Wewnętrzny błąd serwera	Problem po naszej stronie. Prosimy o kontakt z supportem
503	Usługa niedostępna	Serwery są chwilowo przeciążone lub w trakcie konserwacji. Jeśli problem się utrzymuje, prosimy o kontakt z supportem