Customer Agent API:er (beta)

Du kommer att lära dig

Vad Customer Agent API:er är, vad varje slutpunktsgrupp gör och hur man börjar anropa dem. Med API:erna kan du konfigurera din Customer Agent, läsa vad den gör i produktion och köra den programmatiskt – direkt över HTTP, tillsammans med resten av Klaviyos offentliga API.

Obs: Customer Agent-API:erna är i beta. Slutpunkter och scheman kan ändras innan allmän tillgänglighet. Beta-API:er är inte avsedda för användning i produktion – se Klaviyo policy för versionshantering och utfasning för detaljer.

Vad API:erna låter dig göra

Customer Agent-API:erna omfattar 4 uppgifter:

1. Konfigurera agenten – läs eller uppdatera själva agenten, plus dess färdigheter, verktyg, kunskapskällor och hemligheter.
2. Läs produktionskonversationer – lista och inspektera Customer Agent-konversationer.
3. Rapport om prestanda – pull-volym, lösningsfrekvens och mättal per färdighet.
4. Kör agenten en sväng – skicka en konversationssväng och få agentens svar tillbaka. Detta är den rubriklösa primitiven – användbar för att bädda in agenten i din egen yta.

Eftersom de här fyra jobben alla ligger bakom ett API kan du koppla ihop dem i en kontinuerlig träningsloop: hämta vad som hände, diagnostisera vad som fungerade och vad som inte gjorde det och skicka sedan tillbaka konfigurationsändringar. Med en säkert konfigurerad API-integration eller MCP-anslutning kan en AI-assistent som Claude eller ChatGPT hjälpa till att läsa konversationer, hitta mönster i misslyckanden och föreslå ändringar i dina färdigheter, verktyg, kunskap och riktlinjer.

Autentisering och åtkomst

Använd en privat Klaviyo-API-nyckel med omfånget agents för att anropa dessa slutpunkter. Customer Agent måste redan vara aktiverat för ditt Konto.

När du skapar nyckeln väljer du åtkomstnivån för omfånget agents:

Välj skrivskyddat om din integration bara behöver observera agenten (till exempel en rapporteringsinstrumentpanel). Välj läs/skriv om den behöver konfigurera agenten eller köra konversationsvändningar.

1. Navigera till Inställningar > API-nycklar och klicka på Skapa privat API-nyckel.
2. Ange ett namn för den privata API-nyckeln och välj Anpassad nyckel.
3. På raden Agenter väljer du Läsbehörighet eller Fullständig behörighet för din integration med hjälp av tabellen ovan.
4. Klicka på Skapa och klicka sedan på kopieringsikonen och förvara nyckeln säkert. Du kan inte visa nyckeln igen efter att du har lämnat bekräftelsesidan.

För mer information kan du läsa hur du skapar eller klonar en privat API-nyckel.

Skicka API-begäranden från din server till https://a.klaviyo.com och inkludera det här auktoriseringshuvudet. Håll den privata nyckeln borta från webbläsarkod och appar som kunder använder:

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

Varje begäran måste också innehålla betaversionshuvudet:

revision: 2026-10-15.pre

Utan betaversionshuvudet kommer begäran att avvisas.

Prisgränser

Begränsningar för begäranden beror på slutpunktsgruppen:

• Agent, färdigheter, verktyg, kunskap, hemligheter och svar: burstgräns på 10 förfrågningar per sekund och en stadig gräns på 150 förfrågningar per minut.
• Konversationer, konversationsmeddelanden och rapporter: burstgräns på 3 begäranden per sekund och jämn gräns på 60 begäranden per minut.

Begär format

Använd Klaviyo JSON:API-begärandekonventioner, med ett separat format för filuppladdningar:

• Innehållstyp: application/vnd.api+json för JSON-begäranden. Använd multipart/form-data för POST /api/agent-knowledge-files.
• Sidindelade samlingar använder page[cursor] och page[size] (standard 50, max 100, endast framåt). Följ links.next tills den är tom för att hämta de återstående sidorna.
• Filtrering använder de fält och operatorer som stöds och som listas i varje slutpunkts referens. Sorteringsordningen är specifik för slutpunkten: konversationer visas med de senaste först, meddelanden visas med de äldsta först och färdigheter och verktyg sorteras efter ID.

Slutpunktsgrupper

Agent

Det finns som mest 1 Customer Agent per företag. Anropa GET /api/customer-agents för att hitta dess ID och använd sedan det ID:t i GET- eller PATCH-URL:en. Listan är tom om Customer Agent inte är aktiverat för Kontot.

Agentfärdigheter

Du kan läsa förbyggda och anpassade färdigheter. Endast anpassade färdigheter kan uppdateras eller tas bort. Ange en anpassad färdighets status till draft för att mellanlagra eller pausa den, eller live för att aktivera den.

Agentverktyg

Endast anpassade verktyg kan uppdateras eller tas bort. När du har skapat ett externt HTTP-verktyg kopplar du det till en anpassad färdighet via färdighetens agent-tools -relation. Ett verktyg är inte tillgängligt för den färdigheten förrän det har kopplats.

Agentkunskap

Skapa textutdrag, webbsidor, Q&A-par eller mappar genom att ställa in source.source_type på snippet, webpage, qa eller folder. Om du vill lägga till en file använder du den separata filuppladdningsslutpunkten.

Agenthemligheter

Krypterade hemligheter som används av anpassade verktyg. Listans slutpunkt returnerar endast säkra metadata – det hemliga värdet i sig returneras aldrig.

Konversationer

Läs konversationer som agenten har haft med kunder, eller skapa en konversation att köra via API. En konversation kan omfatta många meddelanden under en lång tidsperiod. Listan kan innehålla både live- och förhandsgranskningskonversationer. Använd filter=equals(mode,"live") för att begränsa den till livekonversationer.

Rapporter

Sammanställ mättal, avgränsade till det begärande företaget. Båda rapporterna nedan är POST-slutpunkter: skicka rapportparametrarna i brödtexten. De kräver agents:read, så en skrivskyddad nyckel kan köra dem.

Kör agenten

Detta är det primitiva sättet att bädda in Customer Agent i din egen yta (din app, ditt hjälpcenter, en partnerbyggd supportpanel).

Skapa en öppen konversation med POST /api/customer-agent-conversations innan du kör en tur. Svarslutpunkten accepterar bara konversationer som har skapats via API:t. En stängd konversation, eller en som redan har dirigerats till ditt team, kan inte ta emot fler svar.

Vad som fortfarande kräver Klaviyo UI

Vissa konfigurationssteg finns inte i API:et ännu:

• Kanalkonfiguration (webbchatt, e-post, sms, WhatsApp) – kanalkonfigurationen lever i Klaviyo-plattformsinställningarna.
• Aktiveras på varje kanal – på/av-knappen per kanal stannar kvar i användargränssnittet.
• Val av Helpdesk — i Customer Agent öppnar du en kanal under kanal och konfigurerar avsnittet Handoff. Se Hantera inställningar för Customer Agent för mer information.

Typiska arbetsflöden

Konfigurera en gång och underhåll sedan

1. Skapa en privat API-nyckel med omfånget agents och läs-/skrivåtkomst i Klaviyo.
2. Hämta aktuellt tillstånd – GET /api/customer-agents för att hitta Customer Agent-ID:t, och hämta sedan Customer Agent och listorna för färdigheter, verktyg och kunskap. Följ sidindelningslänkarna för att läsa alla sidor.
3. Gör ändringar – skapa eller uppdatera anpassade färdigheter, verktyg, kunskap och hemligheter efter behov. Koppla nya verktyg till de färdigheter som använder dem och ställ in anpassade färdigheter på status: live när du är redo att aktivera dem.
4. Kontrollera produktionen – visa en lista över de senaste konversationerna och dra en värdrapport för att se hur agenten presterar.
5. Iterera.

Träna din agent i en slinga

API:erna är utformade för att sluta loopen mellan vad din agent gjorde i produktionen och hur den är konfigurerad. En typisk slinga:

1. Hämta senaste konversationer – HÄMTA konversationer filtrerade efter created_at och status och lägg till equals(mode,"live") i filtret för produktionskonversationer. Hämta varje konversations Customer Agent-messages och följ links.next för att läsa varje sida.
2. Diagnostisera – för varje konversation klassificera den som en framgång eller ett misslyckande. Leta efter mönster: är eskaleringar grupperade kring ett ämne? Dirigeras vissa färdigheter när de inte borde? Saknar agenten den kunskap den behöver?
3. Pull Metrics – Värderapport för volym och lösningsfrekvens, plus färdighetsvärderapport för per färdighetsspecifikation. Bekräfta mönstren som håller samman.
4. Föreslå ändringar – baserat på felmönstren, bestäm vad du ska ändra: redigera en färdighets instruktioner, lägg till en kunskapssnippet, skapa ett nytt anpassat verktyg, strama åt en tonregel, lägg till en eskaleringsutlösare.
5. Tillämpa förändringar – PATCHA de berörda färdigheterna, LÄGG UPP nya kunskapskällor etc.
6. Loop. Upprepa mot nästa fönster med konversationer.

Du kan använda en AI-assistent som Claude, ChatGPT eller Cursor för att hämta konversationer, hitta luckor, föreslå specifika ändringar och tillämpa ändringar med ditt godkännande. Anslut den via Klaviyo MCP-servern eller din egen API-integration, och förvara privata API-nycklar i säker konfiguration i stället för i prompter. MCP-servern stöder många av de här uppgifterna, men att skapa eller uppdatera hemligheter och ladda upp kunskapsfiler kräver direkta API-anrop.

Bädda in agenten i din egen yta

Använd mode: preview för testning utan debitering eller mättal för produktion. mode: live är för verkliga kundinteraktioner och räknas med i debitering och mättal för produktion. Varningen om betaanvändning ovan gäller fortfarande.

1. Skapa en nyckel med agentomfattning (läs/skriv).
2. Skapa en konversation – från din server, POST:a till /api/customer-agent-conversations med den valda mode. Spara det returnerade konversations-ID:t.
3. Öppna en konversation i ditt användargränssnitt – samla in kundens inmatning.
4. Kör en tur — från din server, gör en POST till /api/customer-agent-responses med mode, messages och det sparade ID:t i data.relationships.conversation.data.id. Använd relationstypen customer-agent-conversation. Inkludera konversationshistoriken i messages och avsluta med kundens senaste meddelande med role: user.
5. Rendera svaret – bearbeta de returnerade händelserna i ordning och visa agentens meddelanden och eventuella strukturerade data som stöds i ditt gränssnitt. Hantera överlämningshändelser i din integration. API:et returnerar händelser tillsammans utan strömning; det levererar dem inte via en kanal.
6. Upprepa för varje tur med samma konversations-ID och läge medan konversationen är öppen. Efter en hård eller tyst överlämning ska du sluta begära agentsvar och i stället dirigera kunden till ditt supportteam.

Vanliga frågor

Finns det en MCP-server?

Ja. Den fjärrhostade Klaviyo MCP-servern innehåller Customer Agent-verktyg för färdigheter, verktyg, kunskap, hemlig metadata, konversationer, rapporter och att köra agenten. För att skapa en konversation, skapa eller uppdatera hemligheter och ladda upp kunskapsfiler krävs direkta API-anrop. Se Klaviyo MCP-server.

Är detta stabilt nog att bygga vidare på?

Beta innebär att schemat kan komma att ändras. Slutpunkterna är fullt möjliga att anropa, men vi förbinder oss ännu inte till långsiktig stabilitet. Leverera inte produktionskritiska integrationer mot betaversionen.

Var hittar jag hela schemat?

Den fullständiga referensen finns i Klaviyos utvecklarportal på https://developers.klaviyo.com/en/reference/. Customer Agent-slutpunkterna finns under beta-API:er i revisionen 2026-10-15.pre.

Relaterade artiklar