Mukautetut HTTP-toiminnot

Mukautetuilla HTTP-toiminnoilla tekoälyagentti voi kutsua omaa HTTPS-rajapintaasi kesken keskustelun: esimerkiksi hakea tilauksen tilan, varata ajan tai luoda tukipyynnön suoraan omasta järjestelmästäsi. Sinä määrität rajapinnan ja parametrit, tekoälyagentti täyttää parametrit keskustelusta ja Aihion palvelin suorittaa kutsun turvallisesti.

Edellytykset

• Aihio-tilaus Starter-tasolta ylöspäin.
• HTTPS-rajapinta, jota agentti kutsuu. Vain https hyväksytään, ja kutsut suoritetaan palvelinpuolella SSRF-suojattuna (yksityiset ja sisäverkko-osoitteet estetään).
• Tarvittaessa rajapinnan tunnus (Bearer-token tai API-avain).

Toiminnon luonti

1. Avaa Toiminnot-välilehti

   Ohjauspaneelissa: Chatbotit → valitse chatbot → Asetukset → Toiminnot. Valitse Lisää toiminto.

2. Määrittele perustiedot

   • Tunniste on toiminnon koneluettava nimi (snake_case, esim. hae_tilaus). Tekoälyagentti viittaa toimintoon tällä nimellä.
   • Kuvaus kertoo tekoälyagentille, milloin toimintoa käytetään. Kirjoita se selkeästi, esimerkiksi “Hae asiakkaan tilauksen tila tilausnumerolla.”
   • URL ja HTTP-metodi (GET, POST, PUT, PATCH tai DELETE). URL:n on alettava merkeillä https://.
3. Lisää parametrit

   Parametrit ovat tietoja, jotka tekoälyagentti kerää keskustelusta ja täyttää kutsuun. Anna jokaiselle parametrille nimi (snake_case), näyttönimi ja tyyppi (teksti, sähköposti tai puhelin). Viittaa parametriin URL:ssä, otsikoissa tai rungossa kaksoisaaltosulkeilla, esimerkiksi https://api.esimerkki.fi/tilaukset/{{tilausnumero}}.

   Voit lisäksi antaa parametrille valinnaisen vihjeen tekoälylle (esimerkiksi “Asiakkaan tilausnumero, kuten ORD-123”). Vihje parantaa sitä, miten tarkasti agentti täyttää kentän keskustelusta.

   Pyynnössä käytetyn parametrin on oltava pakollinen, jotta kutsu ei suoriudu vajailla tiedoilla.

4. Valitse todennus

   • Ei todennusta julkisille rajapinnoille.
   • Bearer-token tai API-avain: syötä tunnus kerran. Se tallennetaan salattuna (Supabase Vault), eikä sitä näytetä enää myöhemmin; vain viimeiset merkit jäävät näkyviin tunnistamista varten.
5. (Valinnainen) Välitä varmennetun käyttäjän tiedot

   Jos chat-widget varmentaa käyttäjän henkilöllisyyden (ks. Identiteetin varmennus), voit välittää varmennetut tiedot kutsuun viittauksilla kuten {{identity.email}}. Tämä edellyttää, että toiminnossa on Vaadi varmennettu identiteetti käytössä.

   Tunnistetietojen välitys edellyttää JWT-varmennusta. Vain allekirjoitettu JWT tuo {{identity.*}}-kentät HTTP-toimintojen käyttöön. HMAC-tiivistemenetelmällä käyttäjä varmennetaan näyttöä varten, mutta tunnistetietojen viittaukset jäävät tyhjiksi ja kutsu epäonnistuu hallitusti. Käytä allekirjoitettua JWT:tä, jos toimintosi lähettää tunnistetietoja.

   Koska tällöin lähetät henkilötietoja omaan järjestelmääsi, varmista että käsittely on tietosuoja-asetuksen mukaista. Aihio näyttää tästä muistutuksen.

6. Ota käyttöön ja testaa

   Voit testata toiminnon jo ennen tallennusta: syötä esimerkkiarvot lomakkeen Testaa toiminto -osiossa ja suorita kutsu, jolloin näet rajapinnan vastauksen ja statuksen heti. Autentikoidun toiminnon testaaminen edellyttää tunnuksen syöttämistä.

   Kun toiminto on valmis, kytke se päälle ja kokeile keskustelua, joka laukaisee sen. Kun tekoälyagentti suorittaa toimintoa, chat-widget näyttää siitä ilmaisimen vierailijalle.

Miten se toimii

Kun keskustelu vastaa toiminnon kuvausta, tekoälyagentti kutsuu toimintoa: se täyttää parametrit, ja Aihion palvelin suorittaa HTTP-kutsun ja palauttaa vastauksen agentille, joka muotoilee siitä vastauksen asiakkaalle. Kutsut ovat aina https, ne on SSRF-suojattu, ja vain määrittelemäsi parametrit ja varmennetut identiteettitiedot välitetään. Mitään muuta keskustelun sisältöä ei lähetetä rajapintaasi automaattisesti.

Tietoturva

• Tunnukset tallennetaan salattuina, eikä niitä koskaan paljasteta selaimelle.
• Kutsut suoritetaan palvelinpuolella: vain https, portti 443, ei uudelleenohjauksia, vastekoon raja ja aikakatkaisu.
• Yksityiset, sisäverkko- ja metadata-osoitteet estetään (SSRF-suoja).