# Mukautetut HTTP-toiminnot

URL: https://aihio.ai/docs/chatbot/toiminnot
Kuvaus: Määrittele oma HTTPS-rajapintakutsu, jonka tekoälyagentti täyttää ja palvelin suorittaa keskustelun aikana. Tunnukset säilytetään salattuina ja kutsut on SSRF-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](/docs/chatbot/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.

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