Käyttöohjeet

1. Aloitus

Kirjaudu palveluun osoitteessa helpparibotti.fi ja luo ensimmäinen botti "Luo uusi botti" -painikkeella.

Pikaopas — kolme vaihetta käyttöönottoon

1 Luo botti

2 Lisää tietopohja

3 Asenna widget

2. Botin luominen

Paina "Luo uusi botti" -painiketta ja täytä asetukset. Alla on selitys jokaisesta kentästä.

Nimi

Näkyy widgetin ylätunnisteessa asiakkaille. Käytä esimerkiksi yrityksesi nimeä tai "Asiakaspalvelu".

Tervehdysviesti

Ensimmäinen viesti, joka näytetään automaattisesti kun asiakas avaa chatin. Esimerkki: "Hei! Miten voin auttaa sinua tänään?"

System prompt

Botin persoonallisuus ja rajoitukset. Kirjoita tähän ohjeet siitä, miten botti käyttäytyy — esimerkiksi "Olet Yritys Oy:n asiakaspalvelubotti. Vastaa vain yrityksen tuotteisiin liittyviin kysymyksiin."

Widget-väri

Widgetin brändiväri. Valitse valmiista väreistä tai syötä oma hex-arvo.

Sallitut verkkotunnukset

Turvaominaisuus: botti vastaa vain näiltä verkkotunnuksilta tuleviin pyyntöihin. Jätä tyhjäksi kehitysvaiheessa — lisää ennen tuotantoon siirtymistä (esim. yritys.fi, www.yritys.fi).

Malli

Haiku — nopea ja edullinen. Sonnet — laadukkaampi, suositellaan monimutkaiseen tietoon.

Sähköpostiosoite

Tarvitaan sähköpostikanavaa varten. Ks. osio 6.

3. Tietopohja

Tietopohja on kokoelma artikkeleita, joista botti hakee vastauksia. Mitä kattavampi tietopohja, sitä tarkempia vastaukset. Lisää sisältöä kolmella eri tavalla:

Manuaalinen artikkeli

Lisää artikkeli antamalla sille otsikko ja kirjoittamalla tai liittämällä sisältö suoraan. Sopii parhaiten FAQ-osioille, toimitusehdoille ja hinnastoille.

URL-tuonti

Kirjoita verkkosivun URL — järjestelmä hakee sivun tekstisisällön automaattisesti. Nopea tapa lisätä yksittäinen sivu tietopohjaan.

Sivuston automaattinen luku

Anna verkkosivustosi juuriURL (esim. https://yritys.fi) — järjestelmä käy automaattisesti läpi enintään 2 000 osoitetta ja tallentaa löytämänsä sisällön tietopohjaan (tyhjät, noindex-merkityt ja virheelliset sivut ohitetaan, joten tallennettuja sivuja voi olla vähemmän). Luku tapahtuu taustalla; edistyminen näkyy sivun yläpalkissa.

Artikkelin voi laittaa tilapäisesti pois käytöstä Julkaistu/Pois-vaihtokytkimellä ilman että se poistetaan tietopohjasta.

Widget on pieni JavaScript-tiedosto, joka lisää chat-painikkeen sivustollesi. Asennus vie alle minuutin.

Kopioi koodi

Siirry botin "Widget-koodi"-välilehdelle ja kopioi annettu script-tagi.
Liitä koodi sivustollesi

Lisää koodi jokaisen sivun HTML:ään juuri ennen sulkevaa </body>-tagia.

Esimerkki — lisää ennen </body>

<script
  src="https://helpparibotti.fi/widget.js"
  data-bot-id="SINUN-BOT-ID"
  defer
></script>

Muista lisätä tuotantotunnukset Sallitut verkkotunnukset -kenttään ennen julkaisua, esimerkiksi yritys.fi, www.yritys.fi.

Jos koodi päätyy vahingossa sivulle kahteen kertaan — esimerkiksi julkaisujärjestelmä lisää sen automaattisesti sivupohjaan ja se on jo valmiiksi sisällössä — widget tunnistaa tämän itse eikä tuota kahta päällekkäistä chat-painiketta.

5. Laukaisimet, painikkeet, ajanvaraus, eskalaatio ja live

Botin Asetukset-välilehdellä voi määrittää milloin botti kutsuu kävijän keskusteluun, tervetulonäkymän pikapainikkeet, botin itse ehdottamat toimintokehotteet sekä ajanvarauksen. Kaikki nämä ovat valinnaisia — botti toimii ilman niitäkin, mutta ne nopeuttavat kävijän etenemistä keskustelun sijaan. Ne ovat verkkosivuwidgetin ominaisuuksia: sähköposti-, Telegram-, Slack- ja API-kanavissa botti vastaa pelkällä tekstillä.

Laukaisimet

Laukaisin päättää milloin botti kutsuu kävijän keskusteluun — tai avaa sen suoraan hänen puolestaan. Sen sijaan että kutsu näytettäisiin sokeasti 15 sekunnin kuluttua kaikille samalla lauseella, laukaisin näyttää kutsun juuri sillä hetkellä kun kävijä on tilanteessa jossa se todennäköisimmin auttaa: on jäänyt viipymään hinnastosivulle, on poistumassa sivulta ostamatta, tai on tullut mainoslinkin kautta. Yhdellä botilla voi olla useita eri laukaisimia eri tilanteille — samaa lausetta ei tarvitse näyttää hinnastosivun ja yhteystietosivun kävijälle.

Otat laukaisimet käyttöön Asetukset-välilehden Kutsut ja laukaisimet -osiossa. Nopein tapa aloittaa on valita valmis pohja pudotusvalikosta "Lisää valmis pohja" — pohja täyttää kutsutekstin ja ehdot puolestasi, ja voit vielä muokata niitä. Voit myös rakentaa laukaisimen tyhjästä "+ Lisää laukaisin" -painikkeella.

Epäröijä

Kävijä on viipynyt sivulla ja vierittänyt puolet siitä läpi, mutta ei ole vielä toiminut. Yleiskäyttöinen ensimmäinen laukaisin.

Hinnaston poistuja

Kävijä on hinnastosivulla ja on poistumassa sivulta ostamatta.

Lukija joka pysähtyi

Kävijä on lopettanut selailun kesken — lukee, ei klikkaa mitään.

Palaava kävijä

Kävijä on käynyt sivustolla aiemminkin, ei ensimmäistä kertaa.

Kampanjaliikenne

Kävijä on tullut linkin kautta jossa on merkintä utm_source=google (esim. Google-mainos) — kampanjan lähteen voi muokata myös muuksi.

Aukiolon ulkopuolella

Kävijä on sivulla aikana kun toimisto ei ole auki — kutsu kertoo että botilta saa vastauksen silti.

Mobiilikävijä

Kävijä käyttää puhelinta, jolla selailu on hitaampaa kuin kysyminen.

Kampanjasivu: chat heti

Kävijä saapuu kampanjasivulle — chat avautuu suoraan, ei kutsukuplaa väliin.

Laukaisimen ehdot jakautuvat kahteen ryhmään, ja kaikkien valitsemiesi ehtojen — molemmista ryhmistä — täytyy täyttyä yhtä aikaa.

Laukeaa kun

Sen odotetaan tapahtuvan kävijän käynnin aikana: aika sivulla, vieritys, toimettomuus, poistumisaikomus (osoitin siirtyy pois yläreunasta — toimii vain työpöydällä, mobiilissa ei ole osoitinta), elementti tuli näkyviin tai elementtiä klikattiin.

Vain kun

Rajaa ketä kutsu koskee: sivun osoite, laite, uusi/palaava kävijä, aiempien käyntien määrä, liikenteen lähde, kampanjan UTM-parametrit, sivun kieli ja aukioloajat.

Yksi kutsu käyntikertaa kohti

Vaikka botilla olisi useita laukaisimia, kävijälle näytetään enintään yksi niistä per käynti — ensimmäinen jonka ehdot täyttyvät. Kutsu joka toistuisi joka sivunvaihdossa olisi mainos, ei kutsu.

Poistumisaikomus vain työpöydällä

Mobiilissa ei ole osoitinta, joten tätä ehtoa ei voi käyttää mobiilikävijöille — laukaisin, jossa se on ainoa ehto, ei koskaan näy heille.

* osoitekuvioissa

Sivun osoite -kentissä tähti tarkoittaa "mitä tahansa" — /tuotteet/* osuu kaikkiin tuotesivuihin.

Aukioloehto käyttää valittua aikavyöhykettä

Ei kävijän omaa kelloa. Jos yrityksesi on Helsingissä ja kävijä selaa sivustoa New Yorkista, aukioloehto arvioidaan Helsingin ajassa.

"Avaa chat heti" ei avaudu mobiilissa

Paneeli täyttäisi koko ruudun ennen kuin kävijä on nähnyt sivustosta mitään, joten tämä toiminto ei koskaan avaudu itsestään mobiililaitteella — vaikka laukaisimen muut ehdot täyttyisivät.

Estetty laukaisin ei tuhlaa käyntiä

Jos yksi laukaisin ei voi näyttää mitään tälle kävijälle (esimerkiksi edellä mainittu "Avaa chat heti" mobiilissa), käynnin yksi kutsu-mahdollisuus ei kulu siihen — listan seuraava laukaisin saa yhä yrittää.

"Elementti tuli näkyviin" / "Elementtiä klikattiin" -valitsimet ovat turvallisia

Valitsin (esim. button) ei koskaan laukea chat-ikkunan omista napeista — sulje, lähetä, tyhjennä ja niin edelleen — vaikka valitsin osuisi niihinkin muotoilultaan. Voit siis kirjoittaa laajan, sivustosi omaan HTML-rakenteeseen sopivan valitsimen ilman pelkoa siitä että kutsu laukeaisi kävijän omasta yrityksestä sulkea chat.

Hyvä kutsuteksti nimeää kävijän tilanteen, ei botin olemassaoloa — esimerkiksi "Kerro tilanteesi, niin ehdotan sopivaa vaihtoehtoa" toimii paremmin kuin "Hei! Voinko auttaa?".

Laukaisimen tehon näkee botin Yleiskatsaus-välilehdellä: laukaisintaulukko näyttää tämän jakson näytöt ja klikkaukset laukaisimittain, jotta huomaa kumpi kutsuteksti oikeasti tuo kävijän keskusteluun.

Aloitusnapit (tervetulonäkymä)

Aloitusnapit näkyvät kävijälle heti, kun hän avaa chatin ensimmäistä kertaa — ennen kuin hän on kirjoittanut mitään. Voit lisätä enintään viisi nappia, kullekin oman tekstin ja toiminnon:

Lähetä viesti

Napin painallus lähettää valmiiksi kirjoitetun viestin botille, aivan kuin kävijä olisi kirjoittanut sen itse. Sopii yleisimpiin kysymyksiin.

Avaa linkki

Napin painallus avaa annetun osoitteen. Vain https-osoitteet hyväksytään.

Avaa ajanvaraus

Napin painallus avaa ajanvarauksen (ks. alla). Vaatii, että Ajanvaraus-URL on asetettu — muuten nappia ei näytetä.

Toimintokehotteet (CTA)

Toimintokehotteet ovat nappeja, joita botti itse ehdottaa vastauksensa alla — silloin kun se arvioi niiden sopivan käynnissä olevaan keskusteluun. Voit määrittää enintään viisi toimintokehotetta; botti näyttää kerrallaan korkeintaan yhden. Jokaiselle annetaan tekninen avain (ei näy kävijälle), painikkeen teksti, toiminto (linkki tai ajanvaraus) sekä laukaisuohje — vapaamuotoinen kuvaus siitä, missä tilanteessa botin kannattaa ehdottaa juuri tätä nappia (esim. "kun asiakas vaikuttaa valmiilta kokeilemaan palvelua"). Laukaisuohje menee osaksi botin ohjeistusta, joten kirjoita se samaan tyyliin kuin system prompt.

Ajanvaraus

Ajanvaraus-URL on yksi yhteinen osoite, jota sekä aloitusnapit että toimintokehotteet voivat käyttää "Avaa ajanvaraus" -toiminnolla. Se asetetaan kerran botin asetuksissa (vain https). Kun osoite on asetettu, chat-ikkunan yläpalkkiin ilmestyy lisäksi aina ajanvarausnappi — kävijä pääsee varaamaan myös ilman erillistä aloitusnappia. Ajanvarauksen avaustavaksi valitaan jompikumpi:

Chatin sisällä (upotettu)

Oletustapa. Ajanvaraus avautuu omalle näkymälleen chat-ikkunan sisällä, kävijä pysyy widgetissä. Näkymä on kapea — n. 380 pikseliä leveä työpöydällä — joten se sopii varausjärjestelmille, jotka toimivat kapeassa palstassa.

Uudessa välilehdessä

Ajanvaraus avautuu omaan välilehteensä koko sivun leveydellä. Valitse tämä, jos varausjärjestelmä ei toimi kapeassa upotetussa näkymässä. Jos selain estää ponnahdusikkunan, varaus avautuu varmuuden vuoksi upotettuna.

Eskalaatio ihmiselle

Kun botti ei löydä vastausta tietopohjasta, se kertoo sen kävijälle ja tarjoaa mahdollisuutta jättää sähköpostiosoite chatiin — samalla kysymys eskaloituu hallintapaneelin Eskalaatiot-välilehdelle, ja jos Eskalaatioilmoitukset-osoite on asetettu, sinne lähtee myös ilmoitus. Eskalaatiot-välilehdellä vastaat kysymykseen: vastaus tallentuu botin tietopohjaan hyväksyttynä esimerkkinä, jolloin botti osaa vastata samaan kysymykseen jatkossa itse — ja jos kävijä jätti sähköpostiosoitteensa, vastauksesi lähetetään hänelle automaattisesti sähköpostitse samaan eskalaatioon liittyen. Jos lähetys epäonnistuu, näet virheen Eskalaatiot-välilehdellä ja voit ottaa yhteyttä muuta kautta.

Jos kävijä ei jätä sähköpostiosoitetta, vastauksesi tallentuu silti tietopohjaan — se ei vain mene kenellekään erikseen.

Live-keskustelu asiantuntijan kanssa

Eskalaation rinnalla kävijälle voidaan tarjota keskustelua oikean ihmisen kanssa. Tarjous näkyy vain kahden ehdon täyttyessä: botti ei osannut vastata, ja joku on juuri sillä hetkellä tavoitettavissa. Näin kävijälle ei koskaan luvata ihmistä jota ei ole paikalla.

Päivystys tapahtuu botin Live-välilehdellä. Laita Olen tavoitettavissa -kytkin päälle kun voit vastata; tila putoaa automaattisesti pois kun suljet välilehden tai yhteys katkeaa. Jonossa näkyvät odottavat pyynnöt, ja keskustelun avaaminen ottaa sen sinulle — samaan keskusteluun ei voi vastata kaksi henkilöä. Ehdota-painike hakee tietopohjasta vastausluonnoksen, jonka voit lähettää sellaisenaan tai muokata. Botti ei puhu kävijälle luovutuksen aikana.

Päätä palauttaa keskustelun botille. Jos kukaan ei ehdi poimia pyyntöä 90 sekunnissa, kävijälle kerrotaan se ja hän voi jättää sähköpostiosoitteensa normaaliin tapaan. Koko keskustelu — sekä botin että ihmisen viestit — tallentuu samaan keskusteluun Keskustelut-välilehdelle.

6. Sähköpostikanava

Botti voi vastata automaattisesti saapuviin sähköposteihin samassa viestiketjussa.

Aseta sähköpostiosoite

Syötä botin sähköpostiosoite Asetukset-välilehdellä olevaan kenttään.
Ohjaa saapuvat viestit webhookille

Konfiguroi Euromail tai vastaava sähköpostipalvelu lähettämään saapuvat viestit seuraavaan osoitteeseen:

Webhook-osoite

POST https://helpparibotti.fi/api/webhook/inbound-email

Botti vastaa sähköpostikeskusteluihin automaattisesti ja pitää vastaukset samassa viestiketjussa.

7. Telegram-integraatio

Yhdistä botti Telegram-kanavaan tai -ryhmään neljässä vaiheessa.

Luo Telegram-botti BotFatherilla

Avaa Telegram ja kirjoita @BotFather-botille komento /newbot. Saat Bot Token -tunnisteen.
Syötä Bot Token Integraatiot-välilehdelle

Avaa botin Integraatiot-välilehti hallintapaneelissa ja liitä saamasi Bot Token kenttään.
Luo Webhook Secret

Luo vähintään 8 merkin mittainen salainen avain (esim. satunnainen merkkijono). Tallenna se Integraatiot-välilehdelle.
Rekisteröi webhook Telegramille

Aja seuraava komento komentorivillä — korvaa arvot omillasi:

Webhook-rekisteröinti (komentorivi)

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=<WEBHOOK-URL>&secret_token=<SECRET>"

Webhook-URL:n näet Integraatiot-välilehdellä, kun olet tallentanut Telegram-integraation.

8. Slack-integraatio

Botti vastaa Slack-työtilan viesteihin. Vastaus tulee samaan viestiketjuun (thread), joten kanava pysyy siistinä. Botti vastaa sekä suoriin viesteihin (DM) että viesteihin, joissa se mainitaan @botti.

Luo Slack-sovellus

Mene osoitteeseen api.slack.com/apps ja paina "Create New App" → "From scratch". Valitse työtila.
Lisää oikeudet (scopes)

Kohdassa "OAuth & Permissions" → "Bot Token Scopes" lisää chat:write ja app_mentions:read. Lisää im:history suoria viestejä ja channels:history kanavaviestejä varten.
Asenna sovellus ja kopioi tokenit

Paina "Install to Workspace". Kopioi Bot User OAuth Token (alkaa xoxb-) ja Signing Secret (kohdasta "Basic Information").
Tallenna tokenit Integraatiot-välilehdelle

Avaa botin Integraatiot-välilehti, liitä Bot User OAuth Token ja Signing Secret Slack-osioon ja paina "Ota käyttöön". Kopioi näkyviin tuleva Request URL.
Aseta Request URL ja tilaa tapahtumat

Slackissa kohdassa "Event Subscriptions" laita "Enable Events" päälle ja liitä Request URL. Tilaa botin tapahtumat (Subscribe to bot events): message.im ja app_mention. Tallenna.

Request URL (Event Subscriptions)

https://helpparibotti.fi/api/webhook/slack/<BOTIN-SLUG>

Tallenna integraatio Integraatiot-välilehdellä ennen Request URL:n asettamista Slackiin — Slack vahvistaa osoitteen heti, ja vahvistus onnistuu vain jos Signing Secret on jo tallennettu.

9. REST API

REST API sopii omiin integraatioihin sekä Zapier- ja n8n-työnkulkuihin. API-avain tarvitaan kaikissa pyynöissä.

Luo API-avain

Siirry botin Integraatiot-välilehdelle ja paina "Luo API-avain". Avain näytetään vain kerran — tallenna se heti.
Lähetä viesti API:n kautta

Käytä alla olevaa esimerkkiä ensimmäisen viestin lähettämiseen.

Esimerkki — viestin lähetys

curl -X POST https://helpparibotti.fi/api/v1/chat \
  -H "Authorization: Bearer <API-AVAIN>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Mitä tuotteitanne on saatavilla?"}'

Vastauksen muoto

{
  "answer": "Meillä on seuraavat tuotteet...",
  "conversation_id": "uuid"
}

Jatkoviestit samaan keskusteluun: lisää "conversation_id" seuraaviin pyyntöihin.

10. Tilastot ja palautteet

Seuraa botin toimintaa Yleiskatsaus- ja Training-välilehdiltä.

Yleiskatsaus-välilehti

Näyttää reaaliajassa: viestit tänään, viikon keskustelut, kaikki keskustelut sekä asiakastyytyväisyysprosentin.

Asiakaspalaute

Jokaisen bottivastaukseen käyttäjä voi antaa peukku ylös tai peukku alas -palautteen. Palautteet kertyvät tilastoihin ja näkyvät tyytyväisyysprosenttina.

Training-välilehti

Palautteiden pohjalta järjestelmä ehdottaa kysymys-vastauspareja, jotka voit hyväksyä suoraan tietopohjaan tai hylätä. Hyväksytyt parit parantavat botin vastaustarkkuutta.

11. Usein kysytyt kysymykset

Kuinka monta bottia voin luoda?: Ei rajoitusta — voit luoda niin monta bottia kuin tarvitset.
Missä data sijaitsee?: Kaikki tiedot tallennetaan Cloudflaren EU-datakeskuksiin. Viestit lähetetään Anthropicin rajapintaan AI-vastausten generoimiseen.
Voiko botti vastata väärin?: Kyllä, kuten kaikki tekoälyt. Rakenna tietopohja huolellisesti ja testaa botti perusteellisesti ennen julkaisua.
Miten saan botin vastaamaan vain yritykseeni liittyviin kysymyksiin?: Lisää system promptiin selkeä ohje, esimerkiksi: "Vastaa vain tuotteisiimme liittyviin kysymyksiin. Jos kysymys ei liity toimintaamme, kerro kohteliaasti ettet voi auttaa siinä."
Onko viestimäärille rajaa?: Widgettiin on sisäänrakennettu roskapostisuoja: enintään 20 viestiä tunnissa per käyttäjä ja 100 viestiä tunnissa per IP-osoite.
Kuinka kauan keskustelu näkyy kävijän chat-ikkunassa?: Yhden käyntikerran ajan. Keskustelu jatkuu sivulta toiselle siirryttäessä, mutta alkaa alusta kun kävijä palaa sivustolle uudella käynnillä tai kun edellisestä viestistä on kulunut yli 30 minuuttia. Kävijä voi myös tyhjentää keskustelun itse chat-ikkunan yläreunan roskakori-painikkeesta. Tyhjennys koskee vain kävijän omaa näkymää — keskustelut säilyvät hallintapaneelin Keskustelut-välilehdellä.
Mihin kanaviin botin voi liittää?: Sama botti ja sama tietopohja toimii kaikilla kanavilla: verkkosivun widget, sähköposti, Telegram, Slack ja REST API. Otat käyttöön vain ne kanavat, joita tarvitset — ohjeet löytyvät osioista Widget-asennus, Sähköpostikanava, Telegram-integraatio, Slack-integraatio ja REST API.
Voiko sama botti palvella montaa kanavaa yhtä aikaa?: Kyllä. Jokainen keskustelu kirjautuu omalle kanavalleen, mutta botti käyttää kaikissa samaa tietopohjaa ja system promptia. Keskustelut näkyvät hallintapaneelin Keskustelut-välilehdellä kanavan mukaan eriteltyinä.