API-yhteydet
Yhdistä ulkoiset API:si enuchatiin, jotta tekoäly ja säännöt voivat hakea reaaliaikaista tietoa järjestelmistäsi.
Kuinka se toimii
API-yhteydet antavat sinun integroida enuchatin omiin backend-järjestelmiisi — varausjärjestelmiin, CRM:iin, tilauksenhallintaan, varastoon ja muihin. Kun vierailija esittää kysymyksen, enuchat voi kutsua API:asi saadakseen todellista tietoa ja sisällyttää sen vastaukseen.
Kulku
- Määritä yhteys — API:si perus-URL ja todennus
- Lisää päätepisteet — tietyt API-kutsut polkumalleineen ja vastauksen mappauksineen
- Luo sääntö — tekoäly- tai staattinen sääntö CALL_API-toiminnolla
- Vierailija esittää kysymyksen — sääntö laukeaa, kutsuu API:asi, mappaa vastauksen istunnon muuttujiin
- Tekoäly vastaa todellisilla tiedoilla — istunnon muuttujat ovat tekoälyn käytettävissä tarkan vastauksen luomiseen
Esimerkki: Hotellihuoneen saatavuus
Vierailija: „Onko huone 205 saatavilla ensi viikolla?"
Tekoälysääntö täsmää: „Kun vierailija kysyy huoneen saatavuudesta"
CALL_API-toiminto: GET https://api.hotel.com/rooms/205/availability
Vastaus mapattu: room_available = true, price = „120 €/yö"
Tekoäly vastaa: „Huone 205 on saatavilla ensi viikolla hintaan 120 €/yö. Haluaisitko varata sen?"
Yhteyden asettaminen
Mene Asetukset → API-yhteydet paneelissasi.
1. Yhteyden luominen
Yhteys edustaa yhtä ulkoista API:a. Tarvitset:
| Kenttä | Kuvaus | Esimerkki |
|---|---|---|
| Nimi | Merkintä tälle yhteydelle | Hotellivarausten API |
| Perus-URL | API:n juuri-URL | https://api.hotel.com/v1 |
| Todennustyyppi | Kuinka todentaa | Bearer Token, OAuth2 jne. |
2. Todennustyypit
Ei mitään
Julkisille API:ille, jotka eivät vaadi todennusta.
API-avain
Lähettää staattisen avaimen otsikkona tai kyselyparametrina.
| Kenttä | Kuvaus |
|---|---|
| Avain | API-avaimesi arvo |
| Otsikon nimi | Käytettävä otsikko (oletus: X-Api-Key) |
Avain lähetetään muodossa: X-Api-Key: your_key_here
Bearer Token
Lähettää staattisen tokenin Authorization-otsikossa.
Lähetetään muodossa: Authorization: Bearer your_token_here
Basic Auth
Lähettää käyttäjätunnuksen ja salasanan base64-koodattuna.
Lähetetään muodossa: Authorization: Basic dXNlcjpwYXNz
OAuth 2.0 (Client Credentials)
Hakee pääsytokenin automaattisesti ja välimuistittaa sen vanhentumiseen asti. Paras moderneille API:ille kuten Salesforce, Google tai mukautetut OAuth-palvelimet.
| Kenttä | Kuvaus |
|---|---|
| Token-URL | OAuth-tokenin päätepiste (esim. https://auth.example.com/oauth/token) |
| Client ID | OAuth-asiakastunnuksesi |
| Client Secret | OAuth-asiakassalaisuutesi |
| Scope | Välilyönnein eroteltu scope (esim. read write) |
enuchat hoitaa tokenin elinkaaren automaattisesti — hakee ensimmäisessä kutsussa, välimuistittaa vanhentumiseen asti, päivittää tarvittaessa.
Turvallisuus: Kaikki tunnukset salataan levossa käyttäen libsodiumia. Niitä ei koskaan paljasteta API-vastauksissa — vain peitetyt arvot näkyvät paneelissa.
Päätepisteiden määritys
Jokaisella yhteydellä voi olla useita päätepisteitä — tietyt API-kutsut, joita haluat tehdä.
| Kenttä | Kuvaus | Esimerkki |
|---|---|---|
| Nimi | Merkintä tälle päätepisteelle | Tarkista saatavuus |
| Metodi | HTTP-metodi | GET, POST, PUT, DELETE |
| Polku | URL-polku (liitetään perus-URL:ään). Käytä {'{'}variable} dynaamisille arvoille | /rooms/{'{'}roomId}/availability |
| Kyselyparametrit | URL-parametrit avain-arvo-pareina. Arvot tukevat {'{'}variable}-muotoa | date={'{'}checkIn} |
| Rungon malli | JSON-runko POST/PUT:lle. Tukee {'{'}variable}-interpolaatiota | {'{'}"guest": "{'{'}name}"} |
| Vastauksen mappaus | Mappaa JSON-vastauskentät istunnon muuttujiin käyttäen piste-notaatiota | data.available → room_available |
| Kuvaus | Konteksti tekoälylle (mitä tietoja tämä päätepiste palauttaa) | Palauttaa huoneen saatavuuden ja hinnoittelun |
Muuttujien interpolaatio
Käytä {'{'}variableName} poluissa, kyselyparametreissa ja rungon malleissa. Muuttujat tulevat:
- Istunnon muuttujista — aiempien sääntöjen asettamina (SET_VARIABLE-toiminto)
- Toiminnon parametreista — kovakoodattuina CALL_API-säännön toimintoon
Vastauksen mappaus
Mappaa JSON-vastauskentät istunnon muuttujiin käyttäen piste-notaatiota:
// API palauttaa:
{'{'}
"data": {'{'}
"available": true,
"price": {'{'} "amount": 120, "currency": "EUR" }
}
}
// Mappaus:
data.available → room_available // "true"
data.price.amount → room_price // "120"
data.price.currency → room_currency // "EUR"Mapatut muuttujat tallennetaan istunnon muuttujina keskusteluun ja ovat tekoälyn käytettävissä vastausten luomiseen.
Käyttö sääntöjen kanssa
API-kutsut laukaistaan sääntöjen CALL_API-toiminnolla. Voit yhdistää niitä muiden toimintojen kanssa.
Resepti: Tilauksen tilan haku
Yhteys: Tilauksenhallinnan API — https://api.shop.com/v2 — Bearer Token
Päätepiste: GET /orders/{'{'}orderId} → mappaa data.status → order_status, data.eta → delivery_eta
Sääntö (tekoälytyyppi): „Kun vierailija kysyy tilauksensa tilasta tai toimituksesta"
Toiminnot:
- CALL_API → Tilauksen tilan päätepiste
- REPLY_AI → Tekoäly käyttää
order_statusjadelivery_etavastaamiseen
Tulos: Vierailija: „Missä tilaukseni #4521 on?" — Tekoäly: „Tilauksesi #4521 on parhaillaan matkalla ja sen pitäisi saapua torstaihin mennessä."
Resepti: Reaaliaikainen hinnoittelu
Yhteys: Hinnoittelu-API — https://pricing.example.com — API-avain
Päätepiste: GET /products/{'{'}productId}/price → mappaa price → current_price, currency → price_currency
Sääntö (staattinen): MESSAGE_MATCHES_REGEX: /\b(price|cost|how much)\b/i
Toiminnot:
- CALL_API → Hinnoittelupäätepiste
- REPLY_TEXT → „Nykyinen hinta on {'{'}current_price} {'{'}price_currency}."
Testaus
Testaa aina yhteytesi ja päätepisteesi ennen niiden käyttöä säännöissä:
- Testaa yhteys — varmistaa, että todennus toimii (OAuth2:lle: hakee tokenin)
- Testaa päätepiste — tekee todellisen API-kutsun esimerkkimuuttujilla ja näyttää vastauksen
- Testaa sääntö (dry-run) — Säännöt-sivulla testaa, täsmäisikö sääntö ja mitä toimintoja suoritettaisiin
Vinkki: Aloita testaamalla yhteys, sitten kukin päätepiste, sitten koko sääntö. Näin voit eristää ongelmat kullakin tasolla.
Turvallisuus
- Salaus levossa — kaikki tunnukset salataan libsodiumilla ennen tallennusta
- Ei koskaan paljasteta — API-vastaukset eivät koskaan sisällä salauksen purettuja tunnuksia, vain peitettyjä arvoja
- SSRF-suojaus — enuchat estää kutsut localhostiin, yksityisiin IP-osoitteisiin ja sisäisiin isäntänimiin
- Aikakatkaisu — ulkoisten API-kutsujen aikakatkaisu on 5 sekuntia juuttumisen estämiseksi
- OAuth2-tokenin välimuistitus — pääsytokenit välimuistitetaan turvallisesti ja päivitetään automaattisesti
- Tenant-eristys — yhteydet on rajattu tenantiisi, eivätkä ole muiden käytettävissä