Overzicht

Quickchat AI biedt een REST API voor programmatische toegang tot de configuratie van je AI-agent, de Kennisbank, gesprekken, AI-acties en meer.

Optionele voorbeeldcontroles

• Vergelijk implementatiemethoden. Vergelijk je opgegeven kanalen, toegang tot de website en vereiste functies met de configuratieopties van Quickchat AI. Dit onderzoekt je website of account niet.

• Controleer een voorbeeld van een MCP-verbinding. Initialiseer en vraag alleen de lijst met tools op van het documentatie-endpoint van Cloudflare of Microsoft Learn. Er wordt niet ingelogd en er worden geen tools uitgevoerd.

Authenticatie

Alle API-endpoints gebruiken Bearer-tokenauthenticatie. Voeg je API-token toe aan de header Authorization van elke aanvraag:

Authorization: Bearer <API_TOKEN>

Tokens maak je aan in het Quickchat-dashboard onder Externe apps > API. Elk token is een JWT met je scenario_id, dus een extra identificatieheader is niet nodig.

• Geldigheid van het token: 52 weken vanaf aanmaak
• Tokens kunnen op elk moment vanuit het dashboard worden ingetrokken
• Elk token is beperkt tot één AI-agent (scenario)
• Voor het maken van tokens is het Business-abonnement of hoger vereist; bij lagere abonnementen is de optie uitgeschakeld en retourneert het endpoint 402 Payment Required

Opmerking

Het realtime Chat-endpoint (POST https://app.quickchat.ai/chat) accepteert hetzelfde Bearer-token als de rest van deze API, maar staat buiten het basispad /v1/api/ en vereist scenario_id in de requestbody. Zie de pagina Chat voor de volledige referentie.

Tokenbereiken

API-tokens worden met een van twee bereiken aangemaakt:

Bereik	Toegangsniveau	Beschrijving
read_all	Alleen lezen	Kan alle resources lezen, maar niet aanmaken, bijwerken of verwijderen
write_all	Lezen en schrijven	Volledige toegang tot alle endpoints, inclusief schrijfbewerkingen

• Tokens krijgen een bereik wanneer ze in het dashboard worden aangemaakt onder Externe apps > API
• Het bereik write_all omvat automatisch alle rechten van read_all
• Een read_all-token gebruiken op een schrijfendpoint retourneert 403 met "Insufficient token scope. Required: write_all"

Tip

Gebruik read_all-tokens voor monitoring, analyses en integraties die alleen lezen. Gebruik write_all-tokens alleen wanneer je integratie resources moet aanmaken of wijzigen.

Vereist bereik per endpointgroep:

Endpointgroep	Leesbewerkingen	Schrijfbewerkingen
Chatbotinstellingen	read_all	write_all
Kennisbank-instellingen	read_all	write_all
Artikelen	read_all	write_all
Taalgebonden artikel-URL’s	read_all	write_all
Tags	read_all	-
Bestanden uploaden	-	write_all
Externe inhoud importeren	-	write_all
Intercom-kennisbank	read_all	write_all
Widgetconfiguratie	read_all	write_all
Gesprekken	read_all	-
Gespreksmetadata	read_all	write_all
Overdrachtsconfiguratie	read_all	write_all
Gespreksbeoordeling	read_all	write_all
AI-acties	read_all	write_all

Basis-URL

Endpointgroep	Basis-URL
Kennisbank, AI-acties, bestanden uploaden, importeren, chatbotinstellingen, widget, overdracht, gespreksbeoordeling	https://app.quickchat.ai/v1/api/
Gesprekken	https://app.quickchat.ai/v1/api_core/
Realtime chat	https://app.quickchat.ai/chat

Snelheidslimieten

Snelheidslimieten gelden per token en per endpoint.

Categorie	Limiet	Van toepassing op
READ	120 aanvragen/min	GET- en lijstbewerkingen
WRITE	60 aanvragen/min	POST, PATCH, PUT, DELETE
HEAVY	20 aanvragen/min	Bestandsuploads, imports, scrapen

Wanneer een snelheidslimiet wordt overschreden, retourneert de API HTTP 429 Too Many Requests.

Webhooks

Quickchat AI verstuurt geen uitgaande webhooks. Je kunt je niet op een gebeurtenis abonneren om ons een POST-aanvraag naar je endpoint te laten sturen wanneer een bericht binnenkomt, een gesprek wordt overgedragen of een gesprek sluit.

De beschikbare alternatieven dienen verschillende doelen:

• AI-acties roepen je API aan tijdens een gesprek. API-acties bieden de modi AI beslist, Vóór het eerste antwoord en Wanneer metadata overeenkomen. De automatische modi proberen één aanroep per gesprek onder hun gedocumenteerde voorwaarden. Ze zijn geen abonnement op elk bericht of elke overdracht. Gebruik ze bijvoorbeeld om een lead vast te leggen of je systeem te informeren wanneer vereiste gegevens beschikbaar zijn.
• Google Sheets voegt een rij toe wanneer de bijbehorende actie wordt uitgevoerd. Het registreert niet automatisch elk bericht of elke overdracht.
• Periodiek opvragen van de Conversations API haalt opgeslagen gesprekken en hun gebeurtenissen op, inclusief berichten en geregistreerde overdrachtsmarkeringen. Volg de paginering en de bovenstaande READ-limiet. Periodiek opvragen zorgt voor vertraging; het vergelijken van de gespreksstatus tussen aanvragen kan tussentijdse wijzigingen missen. Ga er niet van uit dat dit een volledige geschiedenis van elke overdracht of toewijzingswijziging oplevert.

API-toegang vereist het Business-abonnement; zie Abonnementen en limieten.

Paginering

Lijstendpoints ondersteunen paginering via queryparameters:

Parameter	Beschrijving
limit integer	Aantal items per pagina
offset integer	Aantal over te slaan items

Gepagineerde antwoorden hebben deze structuur:

{
  "items": [],
  "offset": 0,
  "limit": 10,
  "count": 100
}

Foutafhandeling

Alle fouten worden als JSON geretourneerd in het volgende formaat:

{
  "errors": {
    "root": [
      {
        "message": "Description of the error",
        "code": "ERROR_CODE"
      }
    ]
  }
}

Status	Code	Beschrijving
400	BAD_REQUEST	Ongeldige invoer of ontbrekende verplichte velden
401	PERMISSION_DENIED	Ongeldig, verlopen of ingetrokken token
402	PAYMENT_REQUIRED	Actief abonnement vereist
403	PERMISSION_DENIED	Het token heeft niet het vereiste bereik voor deze bewerking
404	NOT_FOUND	Resource niet gevonden
409	CONFLICT	Conflicterende bewerking (bijvoorbeeld een gelijktijdige wijziging)
422	VALIDATION_ERROR	De requestbody voldoet niet aan het schema
429	TOO_MANY_REQUESTS	Snelheidslimiet overschreden
500	UNKNOWN	Interne serverfout
503	SERVICE_UNAVAILABLE	Tijdelijke onbeschikbaarheid

---