Chat

Optionele voorbeeldcontroles

• Bekijk een voorbeeld van een API-actieaanvraag. Vul een aangeleverd aanvraagsjabloon in met synthetische voorbeeldwaarden zonder het te versturen. Laat headers met inloggegevens weg.

• Bekijk een voorbeeld van metadatasleutels. Controleer hoe opgegeven veldnamen variabelesleutels worden, inclusief dubbele namen en fouten door gereserveerde sleutels. Dit controleert geen waarden of accountspecifieke rechten.

Chat

Het realtime Chat-endpoint stuurt een bezoekersbericht naar je AI-agent en retourneert het AI-antwoord in één aanvraag en antwoord. Gebruik dit endpoint om een eigen chatinterface bovenop Quickchat AI te bouwen.

Het verschilt op twee punten van de andere endpoints: het staat op app.quickchat.ai/chat, buiten de basispaden /v1/api/ en /v1/api_core/, en leest scenario_id uit de requestbody in plaats van uit het token. Het gebruikt dezelfde Bearer-tokenauthenticatie als de rest van deze API.

Opmerking

Stuur elke aanvraag naar https://app.quickchat.ai/chat. De scenario_id in de body moet overeenkomen met de AI-agent waaraan je Bearer-token is gekoppeld.

Bericht versturen

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

Requestbody

Parameter	Beschrijving
scenario_id string, verplicht	ID van je AI-agent. Moet overeenkomen met de scenario_id waaraan het Bearer-token is gekoppeld
text string, verplicht	Invoerbericht van de gebruiker
conv_id string	Gespreks-ID. Laat dit bij de eerste aanvraag weg om een nieuw gesprek te beginnen. Stuur daarna de geretourneerde conv_id mee bij volgende aanvragen om het gesprek voort te zetten
client_metadata object	Aangepaste sleutel-waardeparen (we raden maximaal 5 sleutels aan) die aan elk bericht worden gekoppeld. Worden als gegevenskolommen getoond in de gespreksexport in de Inbox

Een aanvraag zonder conv_id start een nieuw gesprek. De aangemaakte conv_id wordt in het antwoord geretourneerd. Bewaar die conv_id en stuur deze bij latere aanvragen mee om de gesprekscontext over meerdere interacties te behouden.

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

Antwoord 200 OK

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

Veld	Beschrijving
conv_id string	Gespreks-ID. Wordt altijd geretourneerd. Stuur deze mee in het bodyveld conv_id om het gesprek voort te zetten
reply string	Het antwoord van de AI-agent. Kan HTML bevatten, zoals regeleinden met <br>
ord_number integer	Oplopend berichtnummer binnen het gesprek
src integer	Interne bronindicator. API-clients kunnen dit veld negeren

Om een bestaand gesprek voort te zetten, stuur je de ontvangen conv_id terug:

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

Clientmetadata

Het Chat-endpoint accepteert de optionele parameter client_metadata: aangepaste attributen die aan elk nieuw bericht worden toegekend en als gegevenskolommen verschijnen in de gespreksexport in de Inbox. Je kunt dezelfde attributen via de widget toevoegen. We raden maximaal 5 sleutels tegelijk aan, bijvoorbeeld {"userId": 12, "website": "mywebsite.com"}. Dit is een richtlijn, geen door de API afgedwongen limiet.

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

Kennisbank filteren op tags

Je kunt tags aan Kennisbank-artikelen toevoegen en daarmee beperken welke artikelen de AI gebruikt, zodat antwoorden alleen op een subset van de Kennisbank zijn gebaseerd. Dit filter wordt momenteel alleen via de API ondersteund.

Voeg een sleutel kb_topic toe aan client_metadata om op tag te filteren. De sleutel kb_topic moet in elke aanvraag van het gesprek aanwezig zijn, inclusief de eerste. De waarde mag tussen aanvragen wijzigen, maar de sleutel zelf moet gedurende het hele gesprek aanwezig zijn om het filter toe te passen.

In het onderstaande voorbeeld worden alle artikelen met de tag your-topic, of zonder tag, opgenomen in de mogelijke kennisbronnen voor het antwoord.

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

Fouten

Het Chat-endpoint retourneert een foutmelding als platte tekst met een passende HTTP-statuscode.

Status	Beschrijving	Actie
400	scenario_id ontbreekt of er zijn geen inloggegevens opgegeven	Voeg scenario_id toe aan de body en een geldige header Authorization: Bearer <API_TOKEN>
400	Ongeldige conv_id (Conversation conv_id <id> is not valid.)	Laat conv_id weg om een nieuw gesprek te starten, of stuur een conv_id mee die door een eerder antwoord is geretourneerd
401	Ongeldige inloggegevens (Unauthorized.)	Controleer of je Bearer-token of API-sleutel geldig is voor deze scenario_id
404	Onbekende scenario_id (No implementation found for scenario_id <id>)	Controleer de scenario_id en of je Bearer-token eraan is gekoppeld
500	Interne serverfout	Een probleem aan onze kant. Neem contact op met support
503	Service niet beschikbaar	De servers zijn tijdelijk overbelast of in onderhoud. Neem contact op met support als het probleem aanhoudt