Omat API-integraatiot

Yhdistä chatbotisi mukautettuihin API-rajapintoihin

Tekoälytoimintojen muokkausohjelmamme avulla voit rakentaa minkä tahansa mukautetun integraation mihin tahansa taustajärjestelmään, joka pystyy tarjoamaan tietoja API-päätepisteiden kautta. Voit esimerkiksi asettaa chatbotin tarkistamaan tuotteen saatavuuden varastossasi, tarkistamaan tilauksen tilan toiminnanohjausjärjestelmässäsi (ERP) tai tarkistamaan asiakastilin nykyisen saldon.

Voit myös suorittaa toimintoja ulkoisten järjestelmien päivittämiseksi - esimerkiksi kutsua päätepisteitä, jotka tekevät ajanvarauksia tai lähettävät webhookeja.

Esivaatimukset

ℹ️ Ennen kuin aloitat - varmista, että sinulla on ChatLab-tilaus, joka sallii mukautetut API-integraatiot. Tarkista tiedot hinnoittelusivulta

Mukautetun API-rajapinnan lisääminen chatbottiisi

Mukautetun API:n integroiminen mahdollistaa sen, että chatbot voi viestiä ulkoisten palveluiden kanssa - esimerkiksi mukautetun verkkokauppasi kanssa noutaen tietoja tai suorittaen toimintoja käyttäjän puolesta.

Tämä opas käy läpi vaiheet, joita mukautetun API:n määrittäminen ChatLab-alustalla edellyttää.

Oma API-rajapintasi

Sinulla on oltava julkisesti saatavilla olevat API-päätepisteet, joita chatbot voi kutsua. Tämä tarkoittaa, että sinun on tarjottava tietoja e-commerce-alustaltasi tai mukautetusta järjestelmästäsi API-päätepisteiden kautta, jotta chatbotimme voi kutsua näitä päätepisteitä tietojen hakemiseksi ja näyttämiseksi käyttäjillesi.

Chatbotin tekemät API-kutsut

Chatbot kutsuu API:a dynaamisesti käyttäjäkeskustelujen aikana sen perusteella, tarvitseeko se pääsyä ulkoisiin tietoihin tai tarvitseeko sen suorittaa tiettyjä toimintoja. On tärkeää huomata seuraavat asiat:

• Ei taattua kutsua: API:a kutsutaan vain silloin, kun chatbotin logiikka katsoo sen tarpeelliseksi. API-kutsujen ajankohdalle tai tiheydelle ei ole takuita.

• Tekoälymallin vaatimukset: Parhaan suorituskyvyn saavuttamiseksi suosittelemme käyttämään korkeamman tason tekoälymalleja, jotka tukevat monimutkaista funktioiden kutsumista (function calling), kuten GPT-4o tai uudempi. Nämä mallit osaavat paremmin arvioida sopivat hetket API:n kutsumiseen keskustelukontekstin ja käyttäjän aikeen perusteella.

• Kontekstitietoiset kutsut: Chatbot yrittää kutsua API:a aina, kun se tunnistaa keskustelussa kontekstin, joka vastaa API:n käyttötarkoitusta, mutta varsinainen kutsu riippuu useista tekijöistä, kuten:

  • Ulkoisen API:n saatavuudesta ja vastausnopeudesta.
  • Keskustelun nykyisestä tilasta ja käyttäjän kehotteista.
  • Tekoälymallin sisäisestä varmuustasosta ja pisteytysalgoritmeista, joiden perusteella se päättää kutsun tarpeellisuudesta.

Mukautetun API:n käyttöönottovaiheet

Vaihe 1: Siirry Custom API -asetuksiin

1. Kirjaudu ChatLab-hallintapaneeliisi.

2. Napsauta vasemman reunan sivupalkissa Settings (Asetukset) -osiossa kohtaa Custom API (Mukautettu API).

Vaihe 2: Määritä uusi API

1. Napsauta + Define API (+ Määritä API) -painiketta.

2. Kirjoita API-rajapintasi nimi kenttään API Name (API:n nimi).

3. Anna yhdistettävän ulkoisen palvelun perus-URL-osoite kenttään URL.

4. Luo API napsauttamalla Save (Tallenna).

Vaihe 3: Lisää API-toiminnot

1. Napsauta juuri luodussa API-merkinnässä painiketta View (Näytä).

2. Määritä API:lle yksittäiset toiminnot (päätepisteet) napsauttamalla + Define API Operation (+ Määritä API-toiminto).

3. Täytä vaaditut tiedot:

• Operation Name (Toiminnon nimi): Toimintoa kuvaava nimi.
• Operation URI (Toiminnon URI): Toiminnon päätepisteen polku (esim. /v1/resource).

Vaihe 4: Määritä päätepisteen URI ja parametrit

1. Päätepisteen URI-määritys:

• Lisää kaikki toiminnossa tarvittavat polkumuuttujat napsauttamalla + Add path variable (+ Lisää polkumuuttuja).
• Syötä muuttujan tiedot ja merkitse ne tarvittaessa pakollisiksi.

• Valitse arvon lähde:
  • Provided by user to chatbot (Käyttäjän antama chatbotille) - jos kentän täyttämiseen vaaditaan arvo käyttäjältä.
  • Constant (Vakio) - jos kyseessä on vakioarvo, joka sinun on annettava API-toiminnon määrityshetkellä.
• Lisää uusi polkumuuttuja polun määrittelyyn kahden @-merkin väliin: @myvariable@:

1. Kyselyparametrit (Query Parameters):

• Lisää kyselyparametreja napsauttamalla + Add query parameter (+ Lisää kyselyparametri).
• Määritä parametrin nimi, tietotyyppi ja lähde (esim. käyttäjän tai chatbotin antama).

Vaihe 5: Valitse pyyntömenetelmä ja runko (Body)

1. Valitse toiminnon HTTP-menetelmä (esim. GET, POST).

2. Jos pyyntömenetelmä on POST, määritä pyynnön runko (request body):

• Valitse sisältötyyppi (esim. application/json).
• Lisää rungon parametrit määrittämällä nimi, tietotyyppi ja lähde.

• Lisää muuttujat rungon määritykseen - kyseessä on yleensä JSON-rakenne, johon voit sijoittaa määrittämäsi muuttujat.

Vaihe 6: Määritä toiminnon otsakkeet (Headers)

Lisää otsakkeet - esimerkiksi Authorization tai muut API-rajapintasi vaatimat otsakkeet. Alla olevasta kuvakaappauksesta näet pysyvän tokenin määrittämisen Authorization-otsakkeeseen:

Vaihe 7: Tallenna toiminto

1. Tarkista määritykset varmistaaksesi, että kaikki tiedot ovat oikein.

2. Tallenna API-toiminto napsauttamalla Save changes (Tallenna muutokset).

Vaihe 8: Testaa API-integraatio

1. Lähetä testipyyntö käyttämällä Test API (Testaa API) -toimintoa ja varmista, että integraatio toimii oikein.

2. Seuraa lokeja mahdollisten virheiden tai ongelmien varalta ja mukauta määrityksiä tarpeen mukaan.

Vaihe 9: Liitä API-toiminnot chatbottiin

Kun API Operations (API-toiminnot) on määritetty, on aika liittää ne chatbottiin. Valitse chatbot pääkoontinäytöstä, napsauta Integrations (Integraatiot) ja valitse vasemmasta valikosta AI API Actions (Tekoälyn API-toiminnot).

Napsauta valitun API-toiminnon kohdalla Attach (Liitä).

Vaihe 10: Lisää chatbotille rooliohjeet

Valitse chatbotisi pääkoontinäytöstä, napsauta Settings (Asetukset) ja valitse vasemmasta valikosta Role (Rooli).

Napsauta kohtaa Provide custom role instructions (Anna mukautetut rooliohjeet).

Lisää ohjeet juuri lisätyn API-toiminnon käyttämisestä. Voit lisätä esimerkiksi seuraavan säännön:

“- When user asks for store inventory always call getItems function and render the result of the function with following rules…..”

Vinkkejä onnistuneeseen integraatioon

• Varmista, että perus-URL ja päätepisteet ovat oikein ja saavutettavissa.

• Varmista, että kaikki todennusvaatimukset (kuten API-avaimet tai tokenit) on määritetty asianmukaisesti.

• Testaa jokainen toiminto perusteellisesti varmistaaksesi, että se palauttaa odotetut vastaukset.

Seuraamalla näitä ohjeita voit integroida mukautetut API-rajapinnat saumattomasti ChatLab-chatbottiisi, mikä laajentaa sen toiminnallisuutta ja tarjoaa käyttäjille monipuolisemman kokemuksen.

Mukautetun API-integraation suojaaminen

Jotta mukautettu API-rajapintasi pysyy turvassa ja suojattuna luvattomalta käytöltä, ota huomioon seuraavat parhaat käytännöt:

Käytä vakiotokeneita

Jatkuvat API-tokenit (Constant API Tokens): Määritä pysyvä API-token (tai avain), jota vaaditaan kaikissa API-pyynnöissä. Tämän tokenin tulisi olla yksilöllinen ja turvallisesti luotu.

• Toteutustapa: Liitä token pyynnön otsakkeeseen tai kyselyparametriksi jokaiseen API-kutsuun.

• Säilytyspaikka: Tallenna token turvallisesti ChatLab-asetuksiisi toiminnon vakioparametrina (constant parameter).

Käytä kirjautumispäätepistettä tilapäisille tokeneille

Lisää API:in ylimääräinen API-toiminto, joka palauttaa väliaikaisen suojaustokenin - eli kirjautumispäätepiste (login endpoint) järjestelmääsi.

Sinun on annettava järjestelmääsi vastaavat kirjautumistiedot kiinteinä API-toiminnon parametreina tätä toimintoa määritettäessä. Jotta chatbot voi käyttää tällä tavalla saatua tokenia, sinun on lisättävä suojaustoken muiden API-toimintojen määrityksiin ja annettava asianmukaiset kehoteohjeet sekä kirjautumistoiminnolle että muille API-toiminnoille (esimerkiksi “Always use the security token obtained from the Login operation as the security_token parameter for operation getOrder”).

Arkaluonteisten tietojen hallinta ChatLabin kautta

Estääkseen chatbotia näyttämästä arkaluonteisia tietoja ChatLabin käyttäjät voivat toimia seuraavasti:

Ohjaa tekoälyn toimintaa kehotemuotoilun (Prompt Engineering) avulla

• Aseta selkeät ohjeet kehotteisiin: Kun määrität chatbotia, anna kehoteasetuksissa selkeät ohjeet arkaluonteisten tietojen näyttämisen välttämiseksi. Esimerkiksi:

  • Esimerkkikehote: "Älä näytä mitään henkilökohtaisia, taloudellisia tai luottamuksellisia tietoja, jotka saadaan API-kutsun vastauksena."
  • Järjestelmäviestien käyttö: Liitä keskustelukulun alkuun järjestelmäviesti tietosuojan tärkeyden korostamiseksi (esim. "Varmista, että kaikista vastauksista jätetään pois kaikki arkaluonteiset tiedot.").

• Päivitä kehotteita säännöllisesti: Mukauta kehotteita käyttäjäpalautteen tai tietojen arkaluonteisuutta koskevien vaatimusten muuttumisen perusteella. Tämä auttaa varmistamaan, että tekoäly noudattaa johdonmukaisesti uusimpia ohjeita arkaluonteisten tietojen käsittelystä.

Suunnittele API-päätepisteet sisäänrakennetulla vahvistuslogiikalla

• Vaadi käyttäjän vahvistus arkaluonteisten tietojen saamiseksi: Suunnittele API-päätepisteesi sisältämään vahvistustarkistukset ennen arkaluonteisten tietojen palauttamista. Esimerkiksi:

  • Vahvistusparametrit: Vaadi käyttäjiä antamaan tiettyjä tietoja (kuten sähköpostiosoite, tilausnumero tai tietty turvakysymys), ennen kuin API palauttaa kyseiseen käyttäjään liittyviä tietoja.
  • Monivaiheinen vahvistus: Ota käyttöön lisäparametreja (esim. tilauspäivämäärä, toimitusosoite tai salainen koodi) käyttäjän henkilöllisyyden varmentamiseksi ja sen varmistamiseksi, että hänellä on oikeus nähdä tiedot.

• Käytä vikasietoisia vastauksia (Fail-Safe): Määritä API-logiikkasi palauttamaan yleisluontoisia viestejä tai virheilmoituksia, jos vaadittua vahvistusta ei anneta tai se ei täsmää:

  • Esimerkki: "Tilaustietoja ei voitu hakea. Vahvista sähköpostiosoitteesi ja tilausnumerosi."

Käytä rajoitettuja tietosisältöjä API-vastauksissa

• Minimoi tietojen näkyminen: Määritä API-vastaukset sisältämään vain chatbotin toiminnan kannalta välttämättömät tiedot, mikä vähentää riskiä arkaluonteisten tietojen tahattomasta näyttämisestä.
  • Esimerkki: Sen sijaan, että palautettaisiin täydelliset käyttäjäprofiilit, palauta vain tietyt kentät, kuten tilauksen tila tai maksuvahvistus, joita tarvitaan chatbotin suorittamaan tehtävään.