API

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

Uwierzytelnianie

Uwzględniaj API Key i scenario_id w każdym żądaniu.

Aby uzyskać klucz API, zaktualizuj swoją subskrypcję, aby obejmowała dostęp do API.

Chat

Zainicjuj nową rozmowę / nową historię użytkownika

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

Powyższe polecenie zwraca JSON o strukturze:

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

conv_id to parametr opcjonalny. Żądanie bez conv_id rozpoczyna nową rozmowę i zwraca nowo wygenerowany conv_id.

Skojarz conv_id z konkretnym użytkownikiem, aby utrzymać kontekst rozmowy w czasie i wielu interakcjach.

Ten endpoint realizuje pojedynczą wymianę w rozmowie.

HTTP Request

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

Query Parameters

Parameter	Type	Description
api_key	string	Utwórz konto i zasubskrybuj, aby otrzymać klucz API
scenario_id	Text	ID powiązane z Twoją implementacją Quickchat API.
text	string	Wiadomość użytkownika

Wyślij wiadomość 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')))

Powyższe polecenie zwraca JSON o 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	Utwórz konto i zasubskrybuj, aby otrzymać klucz API
scenario_id	string	ID powiązane z Twoją implementacją Quickchat API.
conv_id	string (Optional)	Identyfikator konkretnej rozmowy/użytkownika.
text	string	Wiadomość użytkownika.
message_context	string (Optional)	Dodatkowy, przekazywany przez klienta kontekst per-wiadomość, który trafia do AI razem z wiadomością.
client_metadata	dict (Optional)	Np. {userId: 12, website: mywebsite.com}. Maksymalnie 5 kluczy naraz. Parametry zostaną przypisane do każdej nowej wiadomości i będą widoczne jako kolumny w eksporcie rozmów w Inboxie.

Wiadomości z kontekstem i metadanymi

Jak w tabeli powyżej, endpoint https://chat.quickchat.ai/chat pozwala przesłać dwa opcjonalne parametry: message_context i client_metadata.

Client metadata to atrybuty niestandardowe przypisywane do każdej nowej wiadomości i widoczne w eksporcie w Inboxie. Możesz też dodać atrybuty przez Widget z tym samym skutkiem.

Message context pozwala dostarczyć np. kontekst indywidualny per użytkownik, aby nadać 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 filtrów tagów Bazy Wiedzy przez API

W Quickchat AI App możesz dodawać tagi do każdego Artykułu. Mogą one służyć do filtrowania Bazy Wiedzy, aby AI odpowiadało wyłącznie na podstawie wybranego podzbioru artykułów. Na razie funkcja jest obsługiwana tylko przez API.

Aby filtrować po tematach Bazy Wiedzy (tagach), dodaj kb_topic do client_metadata w wywołaniach API. Ważne: upewnij się, że klucz kb_topic jest obecny w każdym wywołaniu API, w tym podczas inicjowania rozmowy. Wartość kb_topic może się zmieniać między wywołaniami, ale sam parametr musi być stale obecny przez całą rozmowę, aby został uwzględniony przez system.

Poniższy przykład pokazuje, jak dodać kb_topic do client_metadata. W przykładzie każdy Artykuł z tagiem your-topic lub bez żadnego tagu zostanie wzięty do puli kandydatów 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'}
  }

Błędy

Poniżej zebraliśmy kody błędów, które może zwrócić API, wraz z opisem i możliwymi rozwiązaniami.

Code	Description	Action
400	The following parameters must be provided: api_key, scenario_id, text	Upewnij się, że wszystkie wymagane parametry są podane.
400	conv_id abcd1234 does not exist	Zweryfikuj, czy conv_id, do którego się odwołujesz, jest poprawny.
400	The limit for message context is 1000 characters.	Skróć pole message context do 1000 znaków (łącznie ze spacjami).
401	Unauthorized	Upewnij się, że api_key i scenario_id są poprawne (patrz Integrations - API w Aplikacji).
500	Internal Server Error	Problem po naszej stronie. Skontaktuj się z pomocą.
503	Service Unavailable	Serwery przeciążone lub w trakcie prac. Jeśli problem się utrzymuje, skontaktuj się z pomocą.