Så här skapar du ett verktyg

Du kommer att lära dig

Så ansluter du Customer Agent till en HTTP-slutpunkt med ett helt anpassat verktyg, skriver en verktygsbeskrivning som Customer Agent faktiskt använder och testar verktyget innan du kopplar det till en färdighet.

Innan du börjar

Du behöver:

• Customer Agent aktiverat
• En HTTP-slutpunkt som kan nås via ett offentligt värdnamn. Adresser för privata nätverk, localhost och URL:er som använder en IP-adress i stället för ett värdnamn stöds inte. Om slutpunkten kräver en API-nyckel eller token sparar du den som en hemlighet (se steg 1 och 6).
• En färdighet med redigerbara instruktioner för att koppla verktyget till

Du kan skapa och testa verktyget innan du kopplar det till en färdighet. Om du vill använda det i konversationer lägger du till det i färdighetens instruktioner. Om du behöver en ny färdighet kan du läsa Så skapar du en färdighet.

Vad ett helt anpassat verktyg är

Ett helt anpassat verktyg är en HTTP-begäran som Customer Agent kan göra under en konversation. Använd ett när verktygen som Customer Agent levereras med inte täcker det du behöver – till exempel för att slå upp en order i ditt eget orderhanteringssystem i stället för Shopify, kontrollera lagersaldo i ett anpassat lagersystem eller skapa ett ärende i ett helpdesk-system som Klaviyo inte har en inbyggd integration med.

För det underliggande konceptet, se Understanding Tools.

När ska man skapa ett helt anpassat verktyg?

Välj ett helt anpassat verktyg när:

• Du behöver realtidsdata från ett system som Klaviyo inte redan integrerar med
• Du vill att Customer Agent ska vidta en åtgärd i ett externt system (avsluta en prenumeration i ditt egna system, skapa ett ärende, uppdatera en post)
• Ett befintligt verktyg passar inte – du använder till exempel en anpassad OMS istället för Shopify för beställningar

Om informationen inte ändras ofta och är densamma för varje kund ska du lägga till den som innehåll istället. Verktygen är för dynamiska, kundspecifika data och åtgärder.

Konfigurera

1. Öppna sidan Anpassade verktyg

1. Gå till Customer Agent > Connectors och öppna sedan kortet Custom.
2. Om din slutpunkt behöver en autentiseringsuppgift går du till Hemligheter och klickar på Lägg till hemlighet. Ange ett Namn och ett Hemligt värde och klicka sedan på Lägg till hemlighet. Hoppa över det här steget om hemligheten redan är sparad eller om slutpunkten inte behöver någon.
3. Klicka på Skapa verktyg.

2. Namnge och beskriv verktyget

• Verktygsnamn — En kort identifierare som ”Hämta lagersaldo” eller ”Skapa returärende”.
• Beskrivning – Naturligt språk som förklarar vad verktyget gör och när det ska användas. Customer Agent läser denna beskrivning för att avgöra om verktyget ska användas för en viss begäran. Var specifik.

Ett bra beskrivningsexempel:

Hämtar lagerantal i realtid för en viss produkt-SKU från lagersystemet. Används när en kund frågar om en specifik produkt finns i lager.

Ett vagt beskrivningsexempel (undvik):

Hämtar produktinformation.

3. Konfigurera HTTP-begäran

• HTTP-metod – GET, POST, PUT, DELETE eller PATCH.
• URL-mall — Den fullständiga URL:en för slutpunkten. Du kan inkludera platshållare för dynamiska värden (se steg 5).
• Rubriker – Alla rubriker som din slutpunkt kräver, inklusive Content-Type och autentiseringsrubriker.
• Frågeparameter – Om din slutpunkt förväntar sig värden i frågesträngen anger du deras namn och värden här. Du kan använda platshållare för värdena (se steg 5).

4. Konfigurera brödtexten för begäran (för POST, PUT, PATCH)

I Mall för brödtext anger du ett JSON-objekt. Använd platshållare för värden som Customer Agent ska fylla i vid körning.

Exempeltext:

{
  ”customer_id”: ”{{profile_id}}”,
  ”SKU”: ”{{product_sku}}”
}

5. Definiera variabler för dynamiska värden

Varje platshållare måste ha en matchande variabel under Variabler. För exemplet på brödtexten ovan:

1. Klicka på Lägg till variabler och ange profile_id som variabelnamn. Ställ in Källa till Klaviyo-profil och Klaviyo-egenskap till Klaviyo-ID. Detta anger den autentiserade kundens Klaviyo-profil-ID.
2. Lägg till en annan variabel med namnet product_sku. Ange Källa till Dynamisk variabel, välj Sträng som dess Typ och beskriv vilken SKU Customer Agent ska tillhandahålla i Beskrivning. Välj Krävs om slutpunkten kräver det.

Upprepa för andra värden som din slutpunkt behöver, till exempel order_id. Variabelnamn måste matcha sina platshållare exakt. En variabel med namnet conversation_id fylls inte i automatiskt med ID:t för den aktuella konversationen.

Använd variablerna som platshållare, till exempel {{profile_id}} och {{product_sku}}, i webbadressen, rubrikerna, frågeparametrarna eller brödtexten. Verktyg som använder variabler för Klaviyo-profil kräver en autentiserad kund; om ett obligatoriskt profilvärde saknas kan begäran inte köras.

6. Autentisering

Om din slutpunkt kräver en API-nyckel, bearer-token eller annan autentiseringsuppgift ska du lagra den som en hemlighet. Hemligheter krypteras, deras värden visas aldrig för Customer Agent och de kan inte visas igen efter att du har sparat dem.

1. I ditt verktyg, under Variabler, klickar du på Lägg till variabler. Ge variabeln ett namn (till exempel api_key), ange Källa som Hemlighet och välj den hemlighet som du sparade.
2. Referera till variabeln där din slutpunkt förväntar sig autentiseringsuppgiften: i ett sidhuvud, URL:en, en frågeparameter eller brödtexten. Till exempel: lägg till ett sidhuvud med namnet Authorization och värdet Bearer {{api_key}}.

För att rotera en nyckel öppnar du hemlighetens radmeny, klickar på Uppdatera, anger ersättningsvärdet och klickar sedan på Uppdatera. Alla verktyg som använder hemligheten tar upp det nya värdet. Kolumnen Används av visar vilka verktyg som refererar till varje hemlighet, så kontrollera den innan du tar bort en.

7. Spara och testa verktyget

Innan du sparar ska du granska Tidsgräns (sekunder) och Maximalt antal försök under Inställningar. Du kan ange en övergripande tidsgräns på 1–10 sekunder och 0–3 nya försök vid tillfälliga fel. Om verktyget ändrar data ska du se till att din slutpunkt kan hantera en upprepad begäran på ett säkert sätt.

Klicka på Spara för att skapa verktyget. Det sparade verktyget öppnas med ett avsnitt för Test.

Tester skickar riktiga förfrågningar till din slutpunkt och kan ändra data. Använd en testprofil och testposter. Spara och kör test sparar också eventuella redigeringar i verktyget, inklusive ett verktyg som redan används av livefärdigheter.

I Test anger du exempelvärden för de dynamiska variablerna. Välj en testprofil under profil om verktyget använder variablerna Klaviyo-profil. Klicka på Spara och kör test.

Granska svar och kontrollera att:

• Svaret kommer tillbaka
• Svaret innehåller de data som din färdighet behöver
• Förväntade felfall returnerar användbara statuskoder och meddelanden

8. Koppla verktyget till en färdighet

1. Gå till Customer Agent > Färdigheter och öppna den färdighet som du vill använda verktyget för. Om instruktionerna är skrivskyddade skapar du en helt anpassad färdighet.
2. I Så här svarar du skriver du / där verktyget ska användas och väljer verktyget i menyn. Förklara när du ska anropa det, vilka värden du ska ange och vad du ska göra med resultatet eller ett fel.
3. När instruktionerna är klara klickar du på Publicera för en utkastfärdighet eller Uppdatera för en publicerad färdighet.

Skriva en bra beskrivning av verktyget

En tydlig beskrivning hjälper Customer Agent att avgöra när verktyget ska användas. Färdighetens instruktioner styr också vilket verktyg den anropar och hur den använder resultatet. Bra beskrivningar:

• Säg vad verktyget gör i en mening
• Säg när du ska använda det i en mening
• Är specifika om data som returneras eller åtgärder som vidtagits

Dåliga beskrivningar är vaga (”får kundinformation”), för breda (”hanterar allt som rör beställningar”) eller talar om för Customer Agent hur de ska bete sig snarare än vad verktyget gör.

Säkerhetshänsyn

• Lagra autentiseringsuppgifter som hemligheter. Klistra aldrig in en API-nyckel eller token direkt i ett sidhuvud, en URL eller en begärandetext. Lägg till den som en hemlighet och referera till den med en Secret-variabel (se steg 6).
• Använd IP-tillåtelselista där det är möjligt. Din slutpunkt måste fortfarande vara nåbar via ett offentligt värdnamn; privata nätverksadresser och localhost blockeras. Använd tillåtelselista som ett extra skyddslager tillsammans med autentisering.
• Var medveten om vilka data du skickar. Din begärandekonfiguration och dina variabelkällor avgör vilka värden som skickas till slutpunkten. Färdighetsinstruktioner styr vilka värden Customer Agent tillhandahåller för dynamiska variabler. Granska vilka fält din slutpunkt tar emot.
• Prisgränser. Om din slutpunkt har frekvensgränser ska du se till att de är tillräckligt höga för att hantera din förväntade konversationsvolym.

Felsökning

Symptom: Customer Agent använder aldrig verktyget.
Trolig orsak: Beskrivningen är för vag eller så ingår verktyget inte i den publicerade instruktionen för färdigheten.
Åtgärd: Skriv om beskrivningen så att det framgår specifikt när det ska användas. I Så här svarar du infogar du verktyget med / och förklarar när du ska anropa det. Klicka på Publicera eller Uppdatera för att tillämpa instruktionerna.

Symptom: Verktyget returnerar ett fel under testningen.
Trolig orsak: Fel URL, felaktigt formaterad brödtext, obligatoriska profildata saknas eller en payload som din slutpunkt inte accepterar.
Åtgärd: I Test granskar du Förhandsgranskning av begäran och Svar. Verifiera URL:en, headers och body mot slutpunktens förväntade indata. Om verktyget använder variabler för Klaviyo-profil väljer du en testprofil med de värden som krävs.

Symtom: Customer Agent använder verktyget men skickar fel parametrar.
Trolig orsak: En variabel har fel källa eller fel profilgenskap, eller så är kompetensinstruktionerna otydliga kring vad som ska skickas.
Åtgärd: Kontrollera variabelnamnen, källorna och de valda profilgenskaperna under Variabler. Uppdatera variabelbeskrivningarna och kompetensinstruktionerna så att de tydligt anger vad som ska anges.

Symtom: Verktyget är långsamt, vilket orsakar fördröjningar i svaren.
Sannolik orsak: Slutpunktsfördröjning.
Åtgärda: Optimera din slutpunkt. Kontrollera om du kan cachelagra resultat på din sida.

Vanliga frågor

Kan ett verktyg användas för flera olika kompetenser?
Ja. När ett verktyg har skapats kan det användas av flera färdigheter. Infoga den i varje färdighets redigerbara instruktioner och publicera eller uppdatera varje färdighet.

Vilka autentiseringsmetoder stöds?
Alla metoder som skickar en statisk autentiseringsuppgift med begäran, till exempel en bearer token eller ett API-nyckelhuvud. Lagra autentiseringsuppgiften som en hemlighet och referera till den med en Secret-variabel (se steg 6). Flöden som behöver hämta eller uppdatera en token vid begärandetillfället, till exempel OAuth, stöds inte i helt anpassade verktyg.

Vad händer om min slutpunkt ligger nere eller returnerar ett fel?
Klaviyo rapporterar verktygsfel till Customer Agent. Tillfälliga fel kan försöka igen inom verktygets tidsgräns och gränser för omförsök. I kompetensens instruktioner ska du förklara hur man ska svara om verktyget inte kan slutföra begäran, till exempel genom att erbjuda att lämna över. Använd tillförlitliga slutpunkter och övervaka verktygets beteende noggrant.

Kan jag redigera ett verktyg efter att jag har skapat det?
Ja. Öppna verktyget från Customer Agent > Connectors > Custom, redigera dess namn, beskrivning eller begärandekonfiguration och klicka sedan på Spara. Lägg till eller ta bort verktyget i instruktionerna för varje färdighet.

Kan jag versionshantera ett verktyg?
Versionshantering stöds inte än. Sparade ändringar gäller för det delade verktyget som används av varje färdighet som refererar till det. Spara och kör test sparar också ändringar, så kontrollera vilka publicerade färdigheter som använder verktyget innan du redigerar det.

Ytterligare resurser