API (Legacy)

Informacja o wycofaniu

Ta strona dokumentuje starsze API Chat korzystajace z uwierzytelniania kluczem API. Aby zapoznac sie z nowym API z tokenem Bearer, obejmujacym endpointy Bazy Wiedzy, Rozmow i Akcji AI, zobacz API.

W tym przewodniku omawiamy kroki potrzebne do integracji Twojego niestandardowego Asystenta Quickchat AI z produktem za posrednictwem endpointu API.

Uwierzytelnianie

Uwzgledniaj API Key i scenario_id w kazdym zadaniu.

Aby uzyskac klucz API, zaktualizuj swoja subskrypcje, aby obejmowala dostep do API.

Chat

Zainicjuj nowa rozmowe / nowa historie uzytkownika

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "text": "Hello!"
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "text": "Hello!"
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Powyzsze polecenie zwraca JSON o nastepujacej strukturze:

{
  "ord_number": 2,
  "conv_id": "abcd1234",
  "reply": "Hey there! 🙂"
}

conv_id to parametr opcjonalny. Zadanie bez conv_id rozpoczyna nowa rozmowe i zwraca nowo wygenerowany conv_id.

Skojarz conv_id z konkretnym uzytkownikiem, aby utrzymac kontekst rozmowy w czasie i wielu interakcjach.

Ten endpoint realizuje pojedyncza wymiane w rozmowie.

HTTP Request

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

Query Parameters

Parameter	Type	Description
api_key	string	Utworz konto i zasubskrybuj, aby otrzymac klucz API
scenario_id	Text	ID powiazane z Twoja implementacja Quickchat API.
text	string	Wiadomosc uzytkownika

Wyslij wiadomosc do Asystenta AI

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Powyzsze polecenie zwraca JSON o nastepujacej strukturze:

{
  "ord_number": 236,
  "reply": "Hey, great to hear from you again! 😉"
}

HTTP Request

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

Query Parameters

Parameter	Type	Description
api_key	string	Utworz konto i zasubskrybuj, aby otrzymac klucz API
scenario_id	string	ID powiazane z Twoja implementacja Quickchat API.
conv_id	string (Optional)	Identyfikator konkretnej rozmowy/uzytkownika.
text	string	Wiadomosc uzytkownika.
message_context	string (Optional)	Dodatkowy, przekazywany przez klienta kontekst per wiadomosc, ktory trafia do AI razem z wiadomoscia.
client_metadata	dict (Optional)	Np. {userId: 12, website: mywebsite.com}. Maksymalnie 5 kluczy naraz. Parametry zostana przypisane do kazdej nowej wiadomosci i beda widoczne jako kolumny w eksporcie rozmow w Inboxie.

Wiadomosci z kontekstem i metadanymi

Jak w tabeli powyzej, endpoint https://chat.quickchat.ai/chat pozwala przeslac dwa opcjonalne parametry: message_context i client_metadata.

Client metadata to atrybuty niestandardowe przypisywane do kazdej nowej wiadomosci i widoczne w eksporcie w Inboxie. Mozesz tez dodac atrybuty przez Widget z tym samym skutkiem.

Message context pozwala dostarczyc np. kontekst indywidualny per uzytkownik, aby nadac rozmowie bardziej spersonalizowany charakter.

Shell

curl https://chat.quickchat.ai/chat \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "<API_KEY>",
  "scenario_id": "<SCENARIO_ID>",
  "conv_id": "abcd1234",
  "text": "Hello!",
  "message_context": "The users name is John.",
  "client_metadata": {userId: 12, website: mywebsite.com}
}'

Python

import requests, json
response = requests.post(
  url="https://chat.quickchat.ai/chat",
  json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'userId': 12, 'website': 'mywebsite.com'}
  })
if response.status_code == 200:
  data = json.loads(response.content)
else:
  raise ValueError(
    "Error code {}: {}".format(
      response.status_code,
      response.content.decode('utf-8')))

Dodawanie filtrow tagow Bazy Wiedzy przez API

W Quickchat AI App mozesz dodawac tagi do kazdego Artykulu. Moga one sluzyc do filtrowania Bazy Wiedzy, aby AI odpowiadalo wylacznie na podstawie wybranego podzbioru artykulow. Na razie funkcja jest obslugiwana tylko przez API.

Aby filtrowac po tematach Bazy Wiedzy (tagach), dodaj kb_topic do client_metadata w wywolaniach API. Wazne: upewnij sie, ze klucz kb_topic jest obecny w kazdym wywolaniu API, w tym podczas inicjowania rozmowy. Wartosc kb_topic moze sie zmieniac miedzy wywolaniami, ale sam parametr musi byc stale obecny przez cala rozmowe, aby zostal uwzgledniony przez system.

Ponizszy przyklad pokazuje, jak dodac kb_topic do client_metadata. W przykladzie kazdy Artykul z tagiem your-topic lub bez zadnego tagu zostanie wziety do puli kandydatow do odpowiedzi.

json={
    "api_key": "<API_KEY>",
    "scenario_id": "<SCENARIO_ID>",
    "conv_id": "abcd1234",
    "text": "Hello!",
    "message_context": "The users name is John.",
    "client_metadata": {'kb_topic': 'your-topic'}
  }

Bledy

Ponizej zebralismy kody bledow, ktore moze zwrocic API, wraz z opisem i mozliwymi rozwiazaniami.

Code	Description	Action
400	The following parameters must be provided: api_key, scenario_id, text	Upewnij sie, ze wszystkie wymagane parametry sa podane.
400	conv_id abcd1234 does not exist	Zweryfikuj, czy conv_id, do ktorego sie odwolujesz, jest poprawny.
400	The limit for message context is 1000 characters.	Skroc pole message context do 1000 znakow (lacznie ze spacjami).
401	Unauthorized	Upewnij sie, ze api_key i scenario_id sa poprawne (patrz Integrations - API w Aplikacji).
500	Internal Server Error	Problem po naszej stronie. Skontaktuj sie z pomoca.
503	Service Unavailable	Serwery przeciazone lub w trakcie prac. Jesli problem sie utrzymuje, skontaktuj sie z pomoca.