# Mukautetut HTTP-toiminnot

URL: https://aihio.ai/ohjekeskus/tekoalyagentti/toiminnot
Kuvaus: Määrittele HTTPS-rajapintakutsu, jonka agentti täyttää ja palvelin suorittaa keskustelun aikana. Tunnukset säilytetään salattuina ja kutsut on suojattu.

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](/ohjekeskus/tekoalyagentti/identiteettivarmistus)), 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.

## Ominaisuuskirjasto

Toiminnot-sivun yläosassa on ominaisuuskirjasto: kortit valmiista ominaisuuksista, kuten tietopohjavastauksista, liidienkeruusta ja ihmistuesta. Kortti kertoo yhdellä silmäyksellä kolme asiaa:

- **Tila**: "Saatavilla" tarkoittaa, että ominaisuuden voi ottaa käyttöön heti; "Tulossa" tarkoittaa, että se on vasta kehitteillä.
- **Tilaustaso**: jos ominaisuus vaatii nykyistä korkeamman tilaustason, kortissa näkyy tason merkki (esimerkiksi Starter tai Pro). Merkki katoaa, kun taso riittää.
- **Määritä**: painike vie suoraan oikeaan asetusnäkymään, esimerkiksi tietopohjaan tai ihmistuen asetuksiin.

**Testaa**-painike ajaa ominaisuudelle valmiustestin: se tarkistaa, onko ominaisuus käytössä tällä botilla, ja Vastaa tietopohjasta -kortin kohdalla myös, onko tietopohjassa sisältöä. Tulos näkyy värillisenä merkkinä (valmis, osittain valmis tai vaatii toimia), ja tarkemmat tiedot avautuvat viemällä osoitin merkin päälle. Testi ei lähetä viestejä eikä muuta asetuksia.

## 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).