Så skapar du ett verktyg (beta)

Betafunktion. Att skapa helt anpassade verktyg från grunden är öppet som betaversion och tillgängligt för alla Customer Agent-konton – ingen registrering krävs. Du hittar verktygssidan i Customer Agent. Funktionen utökas fortfarande och kan komma att ändras.

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 kommer att använda och testar ditt verktyg innan du kopplar det till en färdighet.

Innan du börjar

Du behöver:

• Customer Agent aktiverat
• En HTTP-slutpunkt som du vill att Customer Agent ska anropa – en som inte kräver hemliga autentiseringsuppgifter (API-nycklar, bearer-token etc.) för att komma åt idag (autentiserade slutpunkter kommer snart, se varning nedan)
• En färdighet att koppla verktyget till – antingen följer en färdighet med Customer Agent eller en helt anpassad färdighet som du har skapat

Om du inte har konfigurerat en färdighet ännu ska du skapa en först. Verktyg gör ingenting på egen hand – de måste vara knutna till en färdighet.

Varning: Säker lagring för API-nycklar och andra hemligheter kommer snart. Innan det skickas ska du inte sätta API-nycklar, bearer-token eller andra känsliga autentiseringsuppgifter i helt anpassade verktyg – verktygskonfigurationen är inte en säker plats att lagra dem på ännu. För närvarande får du bara använda verktyg med slutpunkter som är säkra att anropa utan hemlig autentisering (t.ex. interna slutpunkter bakom IP-tillåtna listningar eller slutpunkter som accepterar icke-känsliga identifierare). Stöd för autentiserade slutpunkter är på väg.

Vad ett helt anpassat verktyg är

Ett helt anpassat verktyg är en HTTP-begäran som Customer Agent kan göra under en konversation. Att skapa helt anpassade verktyg är öppet som betaversion och tillgängligt för alla Customer Agent-konton. Använd en när verktygen som Customer Agent levereras med inte täcker ditt behov – till exempel att söka upp en beställning i ditt eget beställningshanteringssystem istället för Shopify, kontrollera lagret i ett speciallagersystem eller skapa ett ärende i en helpdesk som Klaviyo inte integrerar med.

Information om det underliggande konceptet finns i artikeln om att förstå Customer Agent-verktyg.

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 Verktyg

Navigera till Customer Agent > Verktyg och klicka sedan på Skapa verktyg.

2. Namnge och beskriv verktyget

• Namn – En kort identifierare som ”Hämta lager” 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

• Metod – HÄMTA, LÄGGA UPP, LÄGGA TILL, TA BORT eller KORRIGERA.
• URL – URL:en för fullständig slutpunkt. 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.

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

Ange en JSON-text. Använd platshållare för värden som Customer Agent ska fylla i under körning.

Exempeltext:

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

5. Använd platshållare för dynamiska värden

Customer Agent kan fylla i värden vid körning med hjälp av platshållare. Vanliga platshållare:

• {{profile_id}} – Klaviyo-profil-ID för kunden i konversationen
• {{conversation_id}} — Det aktuella konversations-ID:t
• Alla parametrar som du definierar i ditt indataschema (t.ex. {{product_sku}}, {{order_id}})

Platshållare fungerar i URL:en, rubrikerna och brödtexten.

6. Autentisering

Support för autentiserade slutpunkter kommer snart. Fram till dess ska du inte lägga in API-nycklar, bearer-token eller andra hemligheter i ett helt anpassat verktyg. Använd endast slutpunkter som är säkra att anropa utan hemliga autentiseringsuppgifter – till exempel interna slutpunkter som skyddas av IP-godkännandelista eller offentliga slutpunkter som accepterar icke-känsliga identifierare.

Säker hemlig lagring är på väg, och kommer att låsa upp autentiserade slutpunkter.

7. Testa verktyget

Klicka på Testverktyg. Ange exempelvärden för eventuella indataparametrar. Kontrollera att:

• Svaret kommer tillbaka
• Svarsformatet är vad Customer Agent förväntar sig
• Eventuella felfall hanteras

8. Spara och koppla till en färdighet

Klicka på Spara. För att få Customer Agent att faktiskt använda verktyget ska du öppna den färdighet du vill använda det och lägga till verktyget där.

Skriva en bra beskrivning av verktyget

Beskrivningen är det viktigaste fältet. Customer Agent väljer vilket verktyg som ska användas helt och hållet baserat på beskrivningen – inte namnet. 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

• Använd inte helt anpassade verktyg för slutpunkter som kräver hemliga inloggningsuppgifter ännu. Support för autentiserade slutpunkter kommer snart. Innan den skickas ska du bara använda slutpunkter som är säkra att anropa utan hemlig autentisering.
• Använd IP-tillståndslistning om möjligt. Om din slutpunkt är intern ska du begränsa åtkomsten till Klaviyo IP-intervall snarare än att förlita dig på hemligheter.
• Var medveten om vilka data du skickar. Customer Agent skickar kunddata till verktyget baserat på vad färdighetsinstruktionerna säger till dem. 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

Symtom: Customer Agent använder aldrig verktyget.
Sannolik orsak: Beskrivningen är för vag, eller så är verktyget inte kopplat till färdigheten som skulle använda det.
Åtgärda: Skriv om beskrivningen för att specifikt beskriva när den ska användas. Bekräfta att verktyget visas i färdighetens verktygslista.

Symtom: Verktyget returnerar ett fel under testningen.
Sannolik orsak: Fel URL, felformaterad brödtext eller en nyttolast som din slutpunkt inte accepterar.
Fix: Använd testverktygets funktion för att kontrollera råbegäran och svar. Verifiera URL:en och brödtextformatet mot din slutpunkts förväntade inmatning.

Symtom: Customer Agent använder verktyget men skickar fel parametrar.
Sannolik orsak: Platshållarnamnen matchar inte schemat eller så är färdighetsinstruktionerna otydliga om vad som ska godkännas.
Åtgärda: Kontrollera att platshållarnamnen matchar exakt. Uppdatera färdighetsinstruktioner för att vara tydlig med när verktyget ska användas och vilka parametrar som ska tillhandahållas.

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 av flera färdigheter?
Ja. När verktyget har skapats kan det kopplas till ett obegränsat antal färdigheter.

Vilka autentiseringsmetoder stöds?
Support för autentiserade slutpunkter kommer snart. Använd nu slutpunkter som inte kräver hemliga autentiseringsuppgifter (interna slutpunkter med IP-tillåtelse eller offentliga slutpunkter med icke-känsliga identifierare).

Vad händer om min slutpunkt ligger nere eller returnerar ett fel?
Felhantering för helt anpassade verktyg är inte utbyggt ännu. Om din slutpunkt misslyckas kan Customer Agent ge ett försämrat eller förvirrande svar. Innan du hanterar fel på fartyg ska du bara använda slutpunkter du känner dig trygg med – och övervaka verktygets beteende noggrant.

Kan jag redigera ett verktyg efter att jag har skapat det?
Ja. Du kan när som helst redigera namn, beskrivning, konfiguration och bifogade färdigheter.

Kan jag versionera ett verktyg?
Versionshantering stöds inte ännu. Ändringar av ett verktyg träder i kraft omedelbart för varje färdighet som använder det.

Additional resources