Klantenserviceagent-API's (bèta)

Wat je leert

Wat de Klantenserviceagent-API is, wat elke eindpuntgroep doet en hoe je ze begint te bellen. Met de API kun je je Klantenserviceagent configureren, lezen wat het doet in productie en de API programmatisch uitvoeren - direct via HTTP, naast de rest van Klaviyo's openbare API.

Let op: De Klantenserviceagent-API's zijn in bèta. Eindpunten en schema's kunnen veranderen voordat ze algemeen beschikbaar zijn. Bèta-API's zijn niet bedoeld voor gebruik in productie — zie het versie- en afschaffingsbeleid van Klaviyo voor meer informatie.

Wat de API's je laten doen

De Klantenserviceagent-API's omvatten 4 taken:

1. Configureer de agent — lees of update de agent zelf, plus de bijbehorende vaardigheden, tools, kennisbronnen en geheimen.
2. Leesproductiegesprekken — bekijk en inspecteer Klantenserviceagent-gesprekken.
3. Rapport over prestaties — pull-volume, oplossingspercentage en meetwaarde per vaardigheid.
4. Geef de agent één beurt: stuur een gespreksbeurt en krijg het antwoord van de agent terug. Dit is de onthoofde primitief — handig om de agent in je eigen oppervlak in te sluiten.

Omdat deze vier taken allemaal achter één API zitten, kun je ze koppelen in een continue trainingslus: haal op wat er is gebeurd, diagnosticeer wat werkte en wat niet, en lever vervolgens configuratiewijzigingen terug. Met een veilig geconfigureerde API-integratie of MCP-verbinding kan een AI-assistent zoals Claude of ChatGPT helpen om gesprekken te lezen, patronen in fouten te vinden en wijzigingen voor te stellen voor je vaardigheden, tools, kennis en richtlijnen.

Verificatie en toegang

Gebruik een Klaviyo private API-sleutel met het bereik agents om deze eindpunten aan te roepen. Klantenserviceagent moet al zijn ingeschakeld voor je account.

Wanneer je de sleutel maakt, kies je het toegangsniveau voor het bereik agents:

Kies alleen-lezen als je integraties alleen de agent waar moeten nemen (bijv. een rapportagedashboard). Kies lezen/schrijven als het de agent moet configureren of gespreksbeurten moet uitvoeren.

1. Navigeer naar Instellingen > API-sleutels en klik op Privé-API-sleutel maken.
2. Voer een naam voor de privésleutel van de API-sleutel in en selecteer Aangepaste sleutel.
3. Selecteer in de rij Agents Leestoegang of Volledige toegang voor je integratie met behulp van de tabel hierboven.
4. Klik op Maken en klik vervolgens op het kopieerpictogram en bewaar de sleutel veilig. Je kunt de sleutel niet opnieuw bekijken nadat je de bevestigingspagina hebt verlaten.

Bekijk voor meer informatie hoe je een privé API-sleutel kunt maken of klonen.

Verstuur API-verzoeken vanaf je server naar https://a.klaviyo.com en voeg deze autorisatieheader toe. Houd de privésleutel uit browsercode en apps die shoppers gebruiken:

Authorization: Klaviyo-API-Key your-private-api-key

Elk verzoek moet ook de koptekst van de bètarevisie bevatten:

revision: 2026-10-15.pre

Zonder de koptekst voor de bètarevisie wordt het verzoek afgewezen.

Tarieflimieten

Limieten voor aanvragen zijn afhankelijk van de eindpuntgroep:

• Agent, vaardigheden, tools, kennis, geheimen en antwoorden: burstlimiet van 10 verzoeken per seconde en een vaste limiet van 150 verzoeken per minuut.
• Conversaties, conversatieberichten en rapporten: burstlimiet van 3 aanvragen per seconde en steady-limiet van 60 aanvragen per minuut.

Verzoekindeling

Gebruik de JSON:API-aanvraagconventies van Klaviyo, met een aparte indeling voor het uploaden van bestanden:

• Contenttype: application/vnd.api+json voor JSON-verzoeken. Gebruik multipart/form-data voor POST /api/agent-knowledge-files.
• Gepagineerde collecties gebruiken page[cursor] en page[size] (standaard 50, max. 100, alleen vooruit). Volg links.next totdat het leeg is om de resterende pagina's op te halen.
• Filteren gebruikt de ondersteunde velden en operators die worden vermeld in de referentie van elk eindpunt. De sorteervolgorde is eindpunt-specifiek: gesprekken zijn eerst de nieuwste, berichten eerst de oudste en vaardigheden en tools worden gesorteerd op ID.

eindpunt groepen

Agent

Er is maximaal 1 Klantenserviceagent per bedrijf. Roep GET /api/customer-agents aan om de ID te vinden en gebruik die ID vervolgens in de GET- of PATCH-URL. De lijst is leeg als Klantenserviceagent niet is ingeschakeld voor de account.

Agentvaardigheden

Je kunt vooraf gebouwde en aangepaste skills lezen. Alleen aangepaste skills kunnen worden bijgewerkt of verwijderd. Stel de status van een aangepaste skill in op draft om deze klaar te zetten of te pauzeren, of op live om deze te activeren.

Agenttools

Alleen aangepaste tools kunnen worden bijgewerkt of verwijderd. Nadat je een externe HTTP-tool hebt gemaakt, koppel je deze aan een aangepaste vaardigheid via de agent-tools -relatie van de vaardigheid. Een vaardigheid heeft pas toegang tot een tool als die eraan is gekoppeld.

Kennis van agent

Maak tekstfragmenten, webpagina's, Q&A-paren of mappen door source.source_type in te stellen op snippet, webpage, qa of folder. Als je een file wilt toevoegen, gebruik je het afzonderlijke eindpunt voor het uploaden van bestanden.

Agentgeheimen

Versleutelde geheimen gebruikt door aangepaste tools. Het lijsteindpunt geeft alleen veilige metadata terug. De geheime waarde zelf wordt nooit geretourneerd.

Gesprekken

Lees gesprekken die de agent met shoppers heeft gehad, of maak een gesprek om via de API uit te voeren. Eén gesprek kan over een lange periode veel berichten omvatten. De lijst kan live- en previewgesprekken bevatten; gebruik filter=equals(mode,"live") om deze te beperken tot livegesprekken.

Rapporten

Geaggregeerde meetwaarden, beperkt tot het aanvragende bedrijf. Beide onderstaande rapporten zijn POST-eindpunten: geef de rapportparameters door in de body. Ze vereisen agents:read, dus een alleen-lezen sleutel kan ze uitvoeren.

Agent uitvoeren

Dit is de primitieve voor het insluiten van Klantenserviceagent in je eigen omgeving (je app, je Helpcentrum, een door een partner gemaakt supportpaneel).

Maak een open gesprek aan met POST /api/customer-agent-conversations voordat je een run uitvoert. Het response-eindpunt accepteert alleen gesprekken die via de API zijn aangemaakt. Een gesloten gesprek, of een gesprek dat al naar je team is doorgestuurd, kan geen extra responses accepteren.

Wat nog steeds de UI van Klaviyo nodig heeft

Sommige installatiestappen zijn nog niet beschikbaar in de API:

• kanaalconfiguratie (webchat, e-mail, sms, WhatsApp) — kanaalinstellingen vind je in de platforminstellingen van Klaviyo.
• Gaat live op elk kanaal: de aan/uit-schakelaar per kanaal blijft in de UI.
• Selectie van Helpdesk — open in Klantenserviceagent een kanaal onder kanaal en configureer de sectie Overdracht. Bekijk Klantenserviceagent-instellingen beheren voor meer informatie.

Standaard workflow

Eén keer configureren, dan onderhouden

1. Maak een privé API-sleutel met het bereik agents en lees-/schrijftoegang in Klaviyo.
2. Haal de huidige status op — GET /api/customer-agents om de ID van de Klantenserviceagent te vinden, en haal vervolgens de agent en de vaardigheids-, tool- en kennislijsten op. Volg pagineringslinks om alle pagina’s te lezen.
3. Wijzigingen aanbrengen — maak of werk aangepaste skills, tools, kennis en secrets bij als dat nodig is. Koppel nieuwe tools aan de skills die ze gebruiken en stel aangepaste skills in op de status: live wanneer je klaar bent om ze te activeren.
4. Controleer de productie — maak een lijst van recente gesprekken en stel een waardenrapport op om te zien hoe de agent presteert.
5. Herhalen.

Train je agent in een loop

De API's zijn ontworpen om de cirkel te sluiten tussen wat je agent in productie heeft gedaan en hoe deze is geconfigureerd. Een standaard lus:

1. Recente gesprekken ophalen — GET-gesprekken gefilterd op created_at en status, waarbij je equals(mode,"live") aan het filter toevoegt voor productiegesprekken. Haal de Klantenserviceagent-berichten van elk gesprek op en volg links.next om elke pagina te lezen.
2. Diagnose — voor elk gesprek classificeer je het als een succes of een mislukking. Zoek naar patronen: worden escalaties geclusterd rond een onderwerp? Worden bepaalde vaardigheden doorgestuurd wanneer dit niet zou moeten? Ontbreekt de agent de kennis die nodig is?
3. Pull meetwaarde — rapport met waarden voor volume en oplossingspercentage, plus vaardigheids-waardenrapport voor een uitsplitsing per vaardigheid. Bevestig dat de patronen bij elkaar opgeteld blijven.
4. Stel wijzigingen voor — op basis van de foutpatronen, beslis wat je wilt veranderen: bewerk de instructies van een vaardigheid, voeg een kennisfragment toe, maak een nieuwe aangepaste tool, stel een toonregel vast en voeg een escalatietrigger toe.
5. Wijzigingen toepassen — PATCH de getroffen vaardigheden, POST nieuwe kennisbronnen, enz.
6. Lus. Herhaal dit voor het volgende venster met gesprekken.

Je kunt een AI-assistent zoals Claude, ChatGPT of Cursor gebruiken om gesprekken op te halen, hiaten te vinden, specifieke bewerkingen voor te stellen en met jouw goedkeuring wijzigingen toe te passen. Verbind het via de Klaviyo MCP-server of je eigen API-integratie, en bewaar privé API-sleutels in een beveiligde configuratie in plaats van in prompts. De MCP-server ondersteunt veel van deze taken, maar voor het aanmaken of bijwerken van secrets en het uploaden van knowledge-bestanden zijn directe API-calls vereist.

De agent insluiten in je eigen oppervlak

Gebruik mode: preview om te testen zonder facturering of productiemeetwaarden. mode: live is bedoeld voor echte interacties van shoppers en telt mee voor facturering en productiemeetwaarden. De waarschuwing hierboven voor bètagebruik is nog steeds van toepassing.

1. Maak een sleutel met het agentenbereik (lezen/schrijven).
2. Maak een gesprek aan — POST vanaf je server naar /api/customer-agent-conversations met de gekozen mode. Sla de geretourneerde gespreks-ID op.
3. Open een gesprek in je UI — verzamel de invoer van de shopper.
4. Voer een turn uit — POST vanaf je server naar /api/customer-agent-responses met mode, messages en de opgeslagen ID in data.relationships.conversation.data.id. Gebruik relationshiptype Klantenserviceagent-conversation. Neem de gespreksgeschiedenis op in messages en eindig met het meest recente bericht van de shopper met role: user.
5. De response weergeven — verwerk de geretourneerde gebeurtenissen op volgorde en toon de berichten van de agent en alle ondersteunde gestructureerde data in je interface. Verwerk handoff-events in je integratie. De API retourneert events samen zonder streaming; ze worden niet via een kanaal geleverd.
6. Herhaal dit voor elke beurt met dezelfde gesprek-ID en modus zolang het gesprek open is. Na een harde of stille overdracht stop je met het opvragen van agentreacties en stuur je de shopper door naar je supportteam.

Veelgestelde vragen

Is er een MCP-server?

Ja. De op afstand gehoste Klaviyo MCP-server bevat Klantenserviceagent-tools voor vaardigheden, tools, kennis, geheime metadata, gesprekken, rapporten en het uitvoeren van de agent. Voor het aanmaken van een gesprek, het aanmaken of bijwerken van geheimen en het uploaden van kennisbestanden zijn directe API-calls vereist. Zie Klaviyo MCP-server.

Is dit stabiel genoeg om op voort te bouwen?

Bèta betekent dat het schema kan veranderen. De eindpunt is volledig opvraagbaar, maar we zetten ons nog niet in voor stabiliteit op de lange termijn. Verzend geen productie kritieke integraties tegen de bètaversie.

Waar vind ik het volledige schema?

De volledige referentie staat in het Klaviyo-ontwikkelaarsportaal op https://developers.klaviyo.com/en/reference/. De eindpunten van de Klantenserviceagent staan onder Beta APIs in de 2026-10-15.pre revision.

Gerelateerde artikelen