Hoe je een tool maakt

Wat je leert

Hoe je de Klantenserviceagent koppelt aan een HTTP-eindpunt met een volledig aangepaste tool, een toolbeschrijving schrijft die de Klantenserviceagent ook echt gebruikt, en je tool test voordat je deze aan een skill koppelt.

Voordat je van start gaat

Je hebt nodig:

• Klantenserviceagent ingeschakeld
• Een HTTP-eindpunt dat bereikbaar is via een openbare hostnaam. Privénetwerkadressen, localhost en URL's die een IP-adres gebruiken in plaats van een hostnaam worden niet ondersteund. Als het eindpunt een API-sleutel of token vereist, sla je deze op als een geheim (zie stappen 1 en 6).
• Een skill met bewerkbare instructies om de tool aan te koppelen

Je kunt de tool maken en testen voordat je deze aan een vaardigheid koppelt. Om deze in gesprekken te gebruiken, voeg je deze toe aan de instructies van de vaardigheid. Als je een nieuwe vaardigheid nodig hebt, zie Een vaardigheid maken.

Wat een volledig aangepaste tool is

Een volledig aangepaste tool is een HTTP-aanvraag die een Klantenserviceagent tijdens een gesprek kan doen. Gebruik er een als de tools die bij Klantenserviceagent worden geleverd niet dekken wat je nodig hebt — bijvoorbeeld een bestelling opzoeken in je eigen ordermanagementsysteem in plaats van Shopify, voorraad controleren in een aangepast magazijnsysteem of een ticket aanmaken in een helpdesk waarmee Klaviyo niet standaard integreert.

Zie Tools begrijpen voor het onderliggende concept.

Wanneer maak je een volledig aangepaste tool?

Kies voor een volledig aangepaste tool als:

• Je hebt realtime gegevens nodig van een systeem waarmee Klaviyo nog niet integreert
• Je wilt dat de Klantenserviceagent een actie onderneemt in een extern systeem (een abonnement opzeggen in je eigen systeem, een ticket maken, een record bijwerken)
• Een bestaande tool past niet. Je gebruikt bijvoorbeeld een aangepaste OMS in plaats van Shopify voor bestellingen

Als de informatie niet vaak verandert en voor elke klant hetzelfde is, voeg deze dan als content toe. Tools zijn voor dynamische gegevens en acties per klant.

Instellen

1. Open de pagina Aangepaste tools

1. Ga naar Klantenserviceagent > Connectors en open vervolgens de kaart Aangepast.
2. Als je eindpunt een inloggegeven nodig heeft, ga je naar Geheimen en klik je op Geheim toevoegen. Voer een naam en geheime waarde in en klik vervolgens op geheim toevoegen. Sla deze stap over als het geheim al is opgeslagen of als het eindpunt er geen nodig heeft.
3. Klik op Tool aanmaken.

2. Geef en beschrijf de tool

• Toolnaam — Een korte identifier zoals "Voorraad ophalen" of "Retourbon aanmaken".
• Beschrijving — Natuurlijke taal die uitlegt wat de tool doet en wanneer je de tool moet gebruiken. Klantenserviceagent leest deze beschrijving om te beslissen of ze de tool voor een bepaald verzoek wilt gebruiken. Wees specifiek.

Een voorbeeld van een goede beschrijving:

Haalt realtime voorraadtellingen voor een bepaalde product-SKU op uit het magazijnsysteem. Gebruik deze optie wanneer een shopper vraagt of een specifiek product op voorraad is.

Voorbeeld van vage beschrijving (vermijden):

Krijgt productinfo.

3. Configureer het HTTP-verzoek

• HTTP-methode — GET, POST, PUT, DELETE of PATCH.
• URL template — De volledige URL van het eindpunt. Je kunt placeholders toevoegen voor dynamische waarden (zie stap 5).
• Headers – Alle headers die je eindpunt vereist, waaronder Content-Type en authenticatieheaders.
• Queryparameters — Als je eindpunt waarden verwacht in de querystring, voer je hier de namen en waarden in. Je kunt tijdelijke aanduidingen gebruiken voor de waarden (zie stap 5).

4. Configureer de tekst van de aanvraag (voor POST, PUT, PATCH)

Geef in Body template een JSON-object op. Gebruik placeholders voor waarden die Klantenserviceagent tijdens runtime moet invullen.

Voorbeeldtekst:

{
"customer_id": "{{profile_id}}",
"sku": "{{product_sku}}"
}

5. Definieer variabelen voor dynamische waarden

Elke placeholder moet een overeenkomende variabele hebben onder Variabelen. Voor de voorbeeldtekst hierboven:

1. Klik op Variabelen toevoegen en voer profile_id in als de Naam van variabele. Stel Bron in op Klaviyo-profiel en Klaviyo-eigenschap op Klaviyo-ID. Dit levert de Klaviyo-profiel-ID van de geverifieerde shopper.
2. Voeg nog een variabele toe met de naam product_sku. Stel Bron in op Dynamische variabele, kies String als Type en beschrijf in Beschrijving welke SKU de Klantenserviceagent moet aanleveren. Selecteer Vereist als het eindpunt dit vereist.

Herhaal dit voor andere waarden die je eindpunt nodig heeft, zoals order_id. Variabelenamen moeten exact overeenkomen met hun placeholders. Een variabele met de naam conversation_id wordt niet automatisch ingevuld met de huidige conversatie-ID.

Gebruik de variabelen als placeholders, zoals {{profile_id}} en {{product_sku}}, in de URL, headers, queryparameter of body. Tools die Klaviyo-profiel -variabelen gebruiken, vereisen een geverifieerde shopper; als een vereiste profielwaarde ontbreekt, kan de aanvraag niet worden uitgevoerd.

6. Verificatie

Als je eindpunt een API-sleutel, bearer-token of andere inloggegevens vereist, sla je deze op als een geheim. Geheimen worden versleuteld, hun waarden worden nooit aan de Klantenserviceagent getoond en je kunt ze niet meer bekijken nadat je ze hebt opgeslagen.

1. Klik in je tool onder Variabelen op Variabelen toevoegen. Geef de variabele een naam (bijvoorbeeld api_key), stel Bron in op Secret en kies het geheim dat je hebt opgeslagen.
2. Verwijs naar de variabele waar je eindpunt de inloggegevens verwacht: een header, de URL, een queryparameter of de body. Voeg bijvoorbeeld een header met de naam Authorization toe met de waarde Bearer {{api_key}}.

Om een sleutel te roteren, open je het rijmenu van het geheim, klik je op Bijwerken, voer je de vervangende waarde in en klik je vervolgens op Bijwerken. Elke tool die het secret gebruikt, neemt de nieuwe waarde over. De kolom Gebruikt door laat zien welke tools naar elk secret verwijzen, dus controleer dit voordat je er een verwijdert.

7. Sla de tool op en test hem

Controleer vóór het opslaan Time-out (seconden) en Max. nieuwe pogingen onder Instellingen. Je kunt een algemene tijdslimiet van 1–10 seconden en 0–3 nieuwe pogingen instellen voor tijdelijke storingen. Als de tool gegevens wijzigt, zorg er dan voor dat je eindpunt een herhaalde aanvraag veilig kan verwerken.

Klik op Opslaan om de tool te maken. De opgeslagen tool wordt geopend met een sectie Test.

Tests sturen echte verzoeken naar je eindpunt en kunnen gegevens wijzigen. Gebruik een testprofiel en testrecords. Test opslaan en uitvoeren slaat ook alle bewerkingen in de tool op, inclusief een tool die al door live skills is gebruikt.

Voer in Testen voorbeeldwaarden in voor de dynamische variabelen. Selecteer een testprofiel onder Profiel als de tool Klaviyo-profiel -variabelen gebruikt. Klik op Opslaan en test uitvoeren.

Bekijk Antwoord en controleer of:

• Het antwoord is teruggekomen
• Het antwoord bevat de gegevens die je skill nodig heeft
• Verwachte foutgevallen leveren bruikbare statuscodes en berichten op

8. De tool koppelen aan een skill

1. Ga naar Klantenserviceagent > Skills en open de skill waarvoor je de tool wilt gebruiken. Als de instructies alleen-lezen zijn, maak dan een volledig aangepaste skill.
2. Typ in Hoe je reageert / op de plek waar de tool moet worden gebruikt en selecteer de tool in het menu. Leg uit wanneer je deze moet aanroepen, welke waarden je moet doorgeven en wat je met het resultaat of een fout moet doen.
3. Wanneer de instructies klaar zijn, klik je op Publiceren voor een conceptvaardigheid of op Bijwerken voor een live vaardigheid.

Een goede toolbeschrijving schrijven

Een duidelijke beschrijving helpt de Klantenserviceagent te bepalen wanneer de tool te gebruiken. De instructies van de skill geven ook aan welke tool die aanroept en hoe die het resultaat gebruikt. Goede beschrijvingen:

• Vertel in één zin wat de tool doet
• Vertel wanneer het in één zin moet worden gebruikt
• Zijn specifiek over de geretourneerde gegevens of de ondernomen actie

Slechte beschrijvingen zijn vaag ('krijgt klantinfo'), te breed ('verhandelt alles wat met bestellingen te maken heeft'), of vertellen Klantenserviceagent hoe ze zich moeten gedragen in plaats van wat de tool doet.

Overwegingen bij de beveiliging

• Sla inloggegevens op als secrets. Plak nooit een API-sleutel of token rechtstreeks in een header, URL of body. Voeg het toe als secret en verwijs ernaar met een Secret-variabele (zie stap 6).
• Gebruik waar mogelijk IP-allowlisting. Je eindpunt moet nog steeds bereikbaar zijn via een openbare hostnaam; adressen van privé-netwerken en localhost worden geblokkeerd. Gebruik allowlisting als een extra beschermingslaag naast authenticatie.
• Wees je bewust van welke gegevens je verstuurt. Je aanvraagconfiguratie en variabele bronnen bepalen welke waarden naar het eindpunt worden verzonden. Skill-instructies sturen de waarden die de Klantenserviceagent invult voor dynamische variabelen. Controleer welke velden je eindpunt ontvangt.
• Tarievenlimieten. Als je eindpunt frequentielimieten heeft, zorg er dan voor dat deze hoog genoeg zijn om je verwachte gespreksvolume aan te kunnen.

Probleemoplossing

Symptoom: Klantenserviceagent gebruikt de tool nooit.
Waarschijnlijke oorzaak: De beschrijving is te vaag, of de tool is niet opgenomen in de gepubliceerde instructies van de skill.
Oplossing: Herschrijf de beschrijving zodat je specifiek beschrijft wanneer deze moet worden gebruikt. Voeg in Hoe je reageert de tool in met / en leg uit wanneer je deze moet aanroepen. Klik op Publiceren of Bijwerken om de instructies toe te passen.

Symptoom: De tool geeft een foutmelding tijdens het testen.
Waarschijnlijke oorzaak: Verkeerde URL, onjuist opgemaakte body, ontbrekende vereiste profielgegevens of een payload die je eindpunt niet accepteert.
Oplossing: Bekijk in Testen de Aanvraagvoorbeeld en de Reactie. Controleer de URL, headers en body met de verwachte input van je eindpunt. Als de tool variabelen van Klaviyo-profiel gebruikt, selecteer je een testprofiel met de vereiste waarden.

Symptoom: Klantenserviceagent gebruikt de tool, maar geeft verkeerde parameters door.
Waarschijnlijke oorzaak: Een variabele heeft de verkeerde bron of profieleigenschap, of de skill-instructies zijn niet duidelijk over wat er moet worden doorgegeven.
Oplossing: Controleer de namen en bronnen van de variabelen en de geselecteerde profieleigenschappen onder Variabelen. Werk de variabele beschrijvingen en skill-instructies bij zodat ze expliciet maken wat je moet aanleveren.

Symptoom: de tool is traag, waardoor vertragingen in de reacties worden veroorzaakt.
Waarschijnlijke oorzaak: eindpuntlatentie.
Oplossing: Optimaliseer je eindpunt. Controleer of je resultaten aan jouw kant in de cache kunt opslaan.

Veelgestelde vragen

Kan één tool door meerdere skills worden gebruikt?
Ja. Zodra een tool is gemaakt, kan die door meerdere skills worden gebruikt. Voeg deze toe aan de bewerkbare instructies van elke skill en publiceer of werk elke skill bij.

Welke auth-methoden worden ondersteund?
Elke methode die een statische inloggegevens met de aanvraag meestuurt, zoals een bearer token of een API-sleutelheader. Sla de inloggegevens op als een geheim en verwijs ernaar met een Secret-variabele (zie stap 6). Flow die op het moment van de aanvraag een token moeten ophalen of vernieuwen, zoals OAuth, worden niet ondersteund in volledig aangepaste tools.

Wat gebeurt er als mijn eindpunt niet beschikbaar is of een fout retourneert?
Klaviyo meldt toolfouten aan de Klantenserviceagent. Tijdelijke fouten kunnen opnieuw worden geprobeerd binnen de time-out- en herhalingslimieten van de tool. Leg in de instructies van de skill uit hoe je moet reageren als de tool de aanvraag niet kan voltooien, bijvoorbeeld door aan te bieden om het over te dragen. Gebruik betrouwbare eindpunten en monitor het gedrag van de tool nauwlettend.

Kan ik een tool bewerken nadat ik deze heb gemaakt?
Ja. Open de tool via Klantenserviceagent > Connectors > Aangepast, bewerk de naam, beschrijving of aanvraagconfiguratie en klik vervolgens op Opslaan. Voeg de tool toe aan of verwijder deze uit de instructies van elke vaardigheid.

Kan ik een tool versiebeheer geven?
Versiebeheer wordt nog niet ondersteund. Opgeslagen wijzigingen zijn van toepassing op de gedeelde tool die door elke skill wordt gebruikt die ernaar verwijst. Opslaan en test uitvoeren slaat ook wijzigingen op, dus controleer welke live skills de tool gebruiken voordat je deze bewerkt.

Extra hulpbronnen