Mukautettujen API-integraatioiden (Custom API integrations) avulla chatbotisi voi pyytää reaaliaikaista tietoa toiminnanohjausjärjestelmästäsi (ERP), varastostasi, CRM-järjestelmästäsi tai muusta palvelusta. Ne voivat myös tehdä muutoksia, kuten luoda ajanvarauksen. Integraatio tallentaa perus-URL-osoitteen; jokainen toiminto (operation) määrittää yhden kutsuttavan pyynnön. Sen jälkeen liität valitut toiminnot chatbotiin AI-toimintoina (AI actions).
Ennen kuin aloitat
Tarkista, että tilisi sisältää mukautetut API-integraatiot. Tarvitset päätepisteen URL-osoitteen, HTTP-metodin, parametrien nimet ja tyypit, todennusvaatimukset sekä esimerkkivastauksen. Päätepisteeseen on oltava yhteys ChatLabin palvelimilta; tietokoneesi localhost ei ole tuotantopäätepiste.
Käytä käyttöönottoon HTTPS-yhteyttä ja testipalvelua tai testitietueita. Testipyyntö kutsuu päätepistettä oikeasti, joten POST-, PATCH- tai DELETE-pyyntö voi muuttaa ulkoisia tietoja. Tee toiminnoista turvallisesti toistettavia aina kun mahdollista.
1. Luo integraatio
- Avaa päävalikosta Custom Integrations (Mukautetut integraatiot).
- Napsauta + Define API Integration (+ Määritä API-integraatio).
- Anna API name (API:n nimi) ja API Base URL (API:n perus-URL), esimerkiksi
https://api.example.com. - Napsauta Create API Integration (Luo API-integraatio).
- Napsauta sen luettelomerkinnässä View (Näytä) ja sitten + Define API Operation (+ Määritä API-toiminto).
2. Määritä toiminto
Anna toiminnolle tunnistettava nimike ja koneluettava Operation name (Toiminnon nimi), kuten getProductDetails. Käytä toiminnon nimessä vain kirjaimia ja numeroita, älä välilyöntejä tai alaviivoja. Kuvaile, mitä toiminto tekee ja milloin chatbotin tulisi käyttää sitä.
Syötä suhteellinen URI, esimerkiksi /v1/products/@productId@. Perus-URL ja URI muodostavat pyynnön osoitteen.
Jotkin olemassa olevat näyttökuvat esittävät vanhempia esimerkkinimiä tai aaltosulkeilla merkittyjä paikkamerkkejä. Noudata alla olevaa nykyistä syntaksia: toimintojen nimet kuten getProductDetails ja parametrien paikkamerkit ympäröityinä @-merkeillä.
Polku- ja kyselyparametrit
Napsauta Add path variable (Lisää polkumuuttuja) määrittääksesi muuttujan productId. Aseta sen tietotyyppi ja arvon lähde, ja sisällytä sitten @productId@ URI-osoitteeseen. Polkumuuttujat ovat pakollisia, ja jokaisen määritetyn polkumuuttujan on esiinnyttävä URI-osoitteessa, ennen kuin voit tallentaa tai testata.
Käytä painiketta Add query parameter (Lisää kyselyparametri) parametreille, kuten limit tai language, jotka kuuluvat URL-osoitteen kysymysmerkin jälkeen. Anna API:si odottama nimi, sen tyyppi, kuvaus ja arvon lähde.
Käytettävissä olevia arvon lähteitä ovat:
- Provided by user or chatbot: malli antaa arvon keskustelusta. Selitä odotettu muoto ja merkitse pakolliset arvot asianmukaisesti.
- Constant: toimintoon määritetty arvo, kuten kiinteä tilitunniste tai rajoitettu API-tunnistetieto.
- Random value: automaattisesti luotu arvo.
- Client context: isäntäsivuston välittämä arvo, mikäli se on käytettävissä tililläsi. Katso Chat API.
Skalaarityyppejä ovat string, integer, double ja boolean. Runkoparametrit tukevat myös string- ja integer-taulukoita.
3. Määritä metodi ja runko
Valitse päätepistettäsi vastaava GET, POST, PUT, PATCH tai DELETE. Muille metodeille kuin GET muokkain tarjoaa pyynnön sisällöksi vaihtoehdot raw tai form-data.
Jos kyseessä on raaka JSON-runko (raw), määritä runkoparametrit ja aseta niiden @name@-paikkamerkit mallipohjaan. Lisää päätepisteesi vaatima asianmukainen Content-Type-otsake. Esimerkiksi string-tyyppisellä name-parametrilla ja string-taulukkotyyppisellä tags-parametrilla:
{
"name": "@name@",
"tags": @tags@
}
Tämä on mallipohja, ei kirjaimellista JSONia ennen korvaamista. Taulukoiden paikkamerkkejä ei saa ympäröidä lainausmerkeillä. Jokainen määritetty runkoparametri on käytettävä mallipohjassa, kun raakarunkomuokkain on käytössä. Tarkista muodostettu pyyntö testauksen aikana, mukaan lukien teksti, joka sisältää lainausmerkkejä tai erikoismerkkejä.
4. Lisää todennusotsakkeet
Käytä toimintoa Add header (Lisää otsake) määrittääksesi API:n odottamat otsakkeet. Bearer-tokenille käytä otsakkeen nimeä Authorization, arvon lähteenä Constant ja arvona Bearer YOUR_RESTRICTED_TOKEN.
Pidä salaisuudet poissa kehotteista ja URL-osoitteista. Vältä toimintoja, jotka palauttavat kirjautumistokeneita mallille ja luottavat ohjeisiin niiden piilottamisessa. Suosi palvelinpuolen integraatiopäätepistettä, joka hallitsee omaa todennustaan ja paljastaa vain sallitun toiminnon.
5. Tallenna ja testaa pyyntö
- Napsauta Save changes (Tallenna muutokset) toimintomuokkkaimessa. Toisin kuin tavallisissa chatbotin asetuksissa, tässä muokkaimessa on erillinen tallennuspainike.
- Napsauta Test API Operation (Testaa API-toimintoa). Se on pois käytöstä, kun muutoksia on tallentamatta.
- Anna edustavat parametriarvot. Käytä taulukon testisyötteille pilkuin eroteltuja arvoja.
- Suorita testi vain sellaisia tietoja vastaan, joita sinulla on lupa lukea tai muuttaa.
- Tarkista tilakoodi, vastausrunko, pyynnön URL-osoite, otsakkeet, runko ja kaikki tuloksissa näkyvät varoitukset.
- Korjaa virheet, tallenna ja toista tarpeen mukaan.
Älä jaa testitulosteita, jotka sisältävät tunnistetietoja. Palauta mahdollisuuksien mukaan kohdennettua, sivutettua tietoa: suuret vastaukset voidaan katkaista ennen kuin ne saavuttavat mallin.
6. Liitä toiminto chatbotiin
Avaa chatbotisi ja valitse sitten Settings > Actions (Asetukset > Toiminnot). Käytä pluspainiketta lisätäksesi toiminnon, etsi toimintosi mukautetuista API:eista ja liitä tai ota se käyttöön. Pelkkä tilitason integraation luominen ei tee jokaisesta toiminnosta käytettävää jokaiselle chatbotille.
Tarkista toiminnon ohjeet ja käytettävissä olevat turvallisuusasetukset ja odota sitten tallennettu-tilaa. Katso toimintomuokkainta koskevat tiedot kohdasta AI-toiminnot.
7. Selitä, milloin sitä käytetään
Avaa Settings > Role & Behavior (Asetukset > Rooli ja käyttäytyminen).
Jos käytät mukautettuja rooliohjeita, valitse Custom Role Definition (Mukautettu roolimääritys) ja lisää tarkka sääntö, esimerkiksi: "Kun vierailija kysyy, onko tuotetta varastossa, kutsu toimintoa getProductDetails sen tuotetunnuksella. Ilmoita palautettu saatavuus. Jos haku epäonnistuu, selitä, että saatavuutta ei voitu tarkistaa."
Säilytä chatbotin muut hyödylliset ohjeet. Odota tallennettu-tilaa ja käytä sitten Overview-esikatselua (Yleiskatsaus) testataksesi realistisia kysymyksiä, puuttuvia parametreja, virheitä ja luvattomia pyyntöjä. Esikatselukeskustelut voivat käynnistää oikeita toimintoja.
AI:n suorittamaa kutsua ei taata, eikä se välttämättä tapahdu vain kerran. Testaa chatbotillesi valitulla mallilla; älä oleta, että pelkkä mallin nimi takaa oikean työkalujen käytön.
Turvallisuus ja vianmääritys
Päätepisteesi on todennettava pyynnöt ja valtuutettava kunkin käyttäjän pääsy ennen arkaluonteisten tietojen palauttamista tai muutoksen tekemistä. Selaimen toimittama asiakastunnus, sähköpostiosoite, tilausnumero tai kontekstikenttä ei ole riittävä todiste henkilöllisyydestä. Jos välität käyttäjäkohtaisen tokenin asiakaskontekstin kautta, palvelimesi on vahvistettava se.
Palauta vain ne kentät, joita chatbot tarvitsee, kuten tilauksen tila koko asiakasprofiilin sijaan. Kehotteen ohjeet voivat ohjata sanamuotoa, mutta ne eivät voi taata, että mallille palautetut arkaluonteiset tiedot pysyvät piilossa.
Jos pyyntö onnistuu testimuokkaimessa mutta ei keskustelussa, tarkista liitetty toiminto, sen käytössäolotila, ohjeet, pakolliset parametrit ja käytettävissä oleva konteksti. Jos molemmat epäonnistuvat, tarkista URL-osoite, HTTP-metodi, todennus, muodostettu runko ja päätepisteesi lokit. Vältä kirjoitustoiminnon toistuvaa yrittämistä, kunnes tiedät, onnistuiko edellinen pyyntö.