> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Keskeiset käsitteet
> Kartta kaikesta alustalla — mitä kukin objekti tekee, missä se sijaitsee hallintapaneelissa ja mitä APIa se käyttää.
ThunderPhone on kokonaisvaltainen alusta tekoälypohjaisten
puheagenttien rakentamiseen, käyttämiseen ja kehittämiseen. Tämä sivu on kartta:
jokainen vastaan tuleva käsite on selitetty omassa lyhyessä osiossaan
sekä hallintapaneelin näkymän että sitä tukevan API:n kautta. Silmäile sivu kerran
ja palaa siihen aina, kun jokin termi kaipaa selvennystä.
Hallintapaneelin sivupalkki noudattaa tätä rakennetta:
[Agentit](#agents), [puhelinnumerot](#phone-numbers),
[web-widgetit](#web-widgets), [puhelut](#calls),
[tietopohjat](#knowledge-bases).
[Reaaliaikainen seuranta](#live-monitoring) ja lähtevät
[kampanjat](#campaigns).
[Sovellukset, API:t, MCP-palvelimet ja VoIP-palveluntarjoajat](#connections), joita
agenttisi voivat käyttää.
[Simulaatiot](#simulations), [kokeet](#experiments),
[ongelmat](#issues), [raportit](#reports),
[havainnoitavuus](#observability).
[Tiimi ja roolit](#team-and-roles), [API-avaimet](#organizations),
[hälytykset](#alerts), [laskutus](#billing).
[Webhookit](#webhooks) ja [funktiotyökalut](#function-tools)
omaa koodiasi varten.
***
## Organisaatiot
**Organisaatio** on vuokralaisuuden yksikkö. Jokainen muu resurssi —
agentit, puhelinnumerot, puhelut ja avaimet — kuuluu täsmälleen yhteen organisaatioon. Tilisi
voi kuulua useisiin organisaatioihin; jokaisella on oma saldonsa, omat
avaimensa ja oma jäsenluettelonsa.
Kohdassa **Organisaatio → Avaimet** luomasi `sk_live_`-API-avain on
sidottu yhteen organisaatioon. Tämä sidonta tekee REST API:sta niin
suoraviivaisen: sinun ei tarvitse lisätä organisaatiotunnusta URL-polkuun, koska avaimesi
tunnistaa sen jo.
**Hallintapaneelissa:** organisaation valitsin (sivupalkin alareunassa) ja
**Organisaatio**-asetukset — välilehdet Yleiset, Avaimet, Hälytykset, Laskutusasetukset
ja Laskutushistoria.
**API:ssa:** [`/v1/orgs`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/developer-api-keys).
***
## Agentit
**Agentti** on puhelua käyttävä tekoälymääritys. Se sisältää:
* **Kehotteen**, joka ohjaa agentin puhetta ja toimintaa —
mukaan lukien puhelutoiminnot, kuten siirrot, näppäinpainallukset ja puhelun lopetukset,
jotka ovat erillisten asetusten sijaan tavallisia kehoterivejä.
* **Moottoritason** (`spark`, `bolt`, `storm-*`): Spark on optimoitu
kustannuksia varten, Bolt nopeutta varten ja Storm monimutkaisten kehotteiden älykkyyttä varten.
* **Äänen** sekä **ensisijaisen kielen** ja valinnaiset **lisäkielet**
— agentti vaihtaa automaattisesti, kun soittaja vaihtaa
kieltä. Katso [Tuetut kielet](/fi/guides/supported-languages).
* Liitetyt ominaisuudet: [yhdistetyt sovellukset](#connections),
[API-yhteydet](#connections), [tietopohjat](#knowledge-bases),
[MCP-palvelimet](#connections) ja upotetut
[funktiotyökalut](#function-tools).
* Toiminta-asetukset: puheenvuorojärjestys, kuittaustila, taustaraita,
pidon aikakatkaisu.
Muutokset rakennustyökalussa **tallennetaan automaattisesti luonnokseen**; mikään ei siirry käyttöön ennen kuin
napsautat **Julkaise**. Jokaisesta julkaisusta otetaan tilannekuva rakennustyökalun
**Historia**-välilehdelle, joten voit tarkastella ja palauttaa minkä tahansa aiemman version.
**Hallintapaneelissa:** **Puheagentit** → agentin rakennustyökalu
(`/dashboard/agents`). Katso
[Rakenna ensimmäinen puheagenttisi](/fi/guides/build-an-agent).
**API:ssa:** [`/v1/agents`](/api-reference/agents) — CRUD,
monistaminen, siirto, versiohistoria ja kehotteen aputoiminnot.
***
## Puhelinnumerot
**Puhelinnumero** kuuluu organisaatiolle ja reitittää saapuvat puhelut
agentille (ja voi välittää lähtevät puhelut). Kaksi lähdettä:
* **Demonumerot** — ThunderPhonen poolista käyttöön otettavia oikeita yhdysvaltalaisia
numeroita, jotka ovat käytössä sekunneissa. Vain saapuville puheluille, ne vastaavat lyhyellä
puhutulla vastuuvapauslausekkeella, ja hallintapaneeli rajoittaa niitä 10:een organisaatiota kohden. Sopii
ensimmäiseen testiin, ei tuotantoon.
* **VoIP-numerot** — tuot omalta palveluntarjoajaltasi
[VoIP-yhteyden](#connections) kautta. Twilio ja Telnyx yhdistetään suoraan
(Telnyxissä on ohjattu käyttöönotto); SignalWire ja Vonage ovat tulossa pian —
tällä hetkellä yhdistät ne manuaalisella SIP-määrityksellä, joka hyväksyy minkä tahansa
SIP-runkoyhteyden. Kun VoIP-numerot on tuotu ja vahvistettu, ne tukevat saapuvia
ja lähteviä puheluita.
Jokaisella numerorivillä voit määrittää reititystilan, valita saapuvan puhelun agentin
ja lisätä numerolle tunnisteen.
**Hallintapaneelissa:** **Puhelinnumerot** (`/dashboard/phone-numbers`).
Katso [Hanki puhelinnumero](/fi/guides/get-a-phone-number).
**API:ssa:** [`/v1/phone-numbers`](/api-reference/phone-numbers),
[`/v1/voip-connections`](/api-reference/voip-connections),
[`/v1/phone-number-labels`](/api-reference/phone-number-labels).
***
## Puhelut
Jokaisesta saapuvasta puhelusta, lähtevästä puhelusta, simulaatiosta ja widget-istunnosta
luodaan **puheluloki**. Puhelu sisältää koko roolitunnisteilla varustetun litteroinnin,
jäsennellyn vuorohistorian (mukaan lukien työkalukutsut), tallenteen,
laskutuksen kokonaissumman sekä valinnaisen tekoälyarvioinnin ja ongelmaraportit.
Kun puhelu on **käynnissä**, voit avata sen ja **kuunnella mukana** — liityt
hiljaa, eikä kukaan puhelussa kuule sinua. Kuuntelun aikana voit
**kuiskata**: kirjoita ohje, joka menee suoraan agentillesi
kesken puhelun; soittaja ei koskaan kuule sitä, ja agentti noudattaa sitä reaaliajassa.
**Hallintapaneelissa:** **Puheluhistoria** (`/dashboard/call-history`) arkistolle
ja puhelukohtaisille tiedoille; **Live** käynnissä oleville puheluille. Katso
[Tarkista, kuuntele ja ohjaa puheluitasi](/fi/guides/review-calls).
**API:ssa:** [`/v1/calls`](/api-reference/calls) — luettelo, litterointi,
historia, ääni, arviointi, vienti;
[`/v1/issue-reports`](/api-reference/issue-reports).
***
## Verkkowidgetit
**Verkkowidget** tarjoaa sivustosi kävijöille mikrofonipohjaisen keskustelun
agentin kanssa — puhelinnumeroa ei tarvita. Se todentaa käyttämällä
**julkaistavaa avainta** (`pk_live_...`), joka on alkuperärajoitettu sallittuihin
verkkotunnuksiisi, joten sitä on turvallista käyttää asiakaspuolen koodissa.
Avaimet toimivat yhdessä kahdesta tilasta: `agent` (sidottu staattisesti yhteen agenttiin)
tai `webhook` (palvelimesi valitsee määrityksen kävijäkohtaisesti — katso
[Dynaaminen puhelukohtainen määritys](/fi/guides/dynamic-call-config)). Widget-istunnot
kulkevat saman puheluinfrastruktuurin kautta kuin puhelut.
**Hallintapaneelissa:** **Verkkowidgetit** (`/dashboard/web-widgets`) —
luo widgettejä, määritä tila ja agentti, hallitse sallittuja verkkotunnuksia ja
kopioi upotuskoodi. Katso
[Luo verkkowidget](/fi/guides/embed-a-web-widget-dashboard).
**API:ssa:** [`/v1/publishable-key`](/api-reference/publishable-keys),
[`/v1/mic-session`](/api-reference/mic-sessions) ja
[Widget SDK -dokumentaatio](/fi/widget/overview).
***
## Tietopohjat
**Tietopohja** on kokoelma dokumentteja, joista agenttisi voi hakea tietoa
kesken puhelun vastaustensa tueksi — lataa tiedostoja suoraan tai tuo ne
Google Drivesta ja liitä tietopohja agenttiin rakentajassa. Agentti tekee hakuja
sisäänrakennetulla hakutyökalulla aina, kun keskustelu sitä vaatii.
**Hallintapaneelissa:** **Tietopohja** (`/dashboard/knowledge`) dokumenttikirjastolle;
rakentajan **Tietopohja**-osio tietopohjan liittämiseen agenttiin. Katso
[Anna agentillesi tietopohja](/fi/guides/knowledge-base).
***
## Yhteydet
Yhteydet ovat tapa, jolla agentit tavoittavat ulkoiset järjestelmät. Neljä
tyyppiä, yksi sivupalkkiryhmä:
* **Sovellukset** (`/dashboard/app-connections`) — OAuth-yhteydet
Slackiin, HubSpotiin, Salesforceen, Google-kalenteriin, Google
Sheetiin ja Cal.comiin. Yhdistä kerran ja ota sitten käyttöön
toimintokohtaiset työkalut (lähetä Slack-viesti, päivitä tai luo
HubSpot-yhteyshenkilö, varaa Cal.com-aika…) millä tahansa agentilla.
Katso [Yhdistä sovelluksia](/fi/guides/connect-apps).
* **API:t** (`/dashboard/api-connections`) — muuta mikä tahansa HTTP API
agenttitoiminnoksi. Liitä cURL-komento, jolloin tekoälyavustaja
luonnostelee työkalun määritelmän, tai rakenna se manuaalisesti;
**Testaa pyyntö** -painike lähettää eriytetyn kutsun ennen julkaisua.
Katso [API-yhteydet](/fi/guides/api-connections) — hallintapaneelin
näkymä kohteeseen
[`/v1/integrations`](/api-reference/integrations).
* **MCP** (`/dashboard/mcp-connections`) — lisää Model Context
Protocol -palvelin URL-osoitteella ja anna agentin käyttää sen
tarjoamia työkaluja. Katso [Lisää MCP-palvelin](/fi/guides/mcp-servers).
* **VoIP** (`/dashboard/voip-connections`) — palveluntarjoajan
tunnistetiedot [omien puhelinnumeroiden käyttämiseen](#phone-numbers).
Katso [Yhdistä VoIP-palveluntarjoaja](/fi/guides/voip-providers).
**API:ssa:** [`/v1/integrations`](/api-reference/integrations) ja
[`/v1/voip-connections`](/api-reference/voip-connections); katso myös
[Rakenna työkalintegraatio](/fi/guides/build-tool-integration).
***
## Kampanjat
**Kampanja** soittaa lähteviä puheluita laajassa mittakaavassa: lataa
CSV-tiedosto yhteyshenkilöistä, valitse agentti ja lähtönumero sekä
määritä soittoaikaikkuna (päivät ja tunnit aikavyöhykkeet huomioiden),
samanaikaisten puheluiden määrä ja uudelleenyrityskäytäntö
(enimmäisyritykset ja mitkä tulokset — ei vastausta, vastaaja,
epäonnistunut — yritetään uudelleen). Kampanja etenee luettelon läpi ja
tallentaa jokaisen puhelun puheluhistoriaan.
**Hallintapaneelissa:** **Kampanjat** (`/dashboard/campaigns`). Katso
[Suorita lähtevien puheluiden kampanja](/fi/guides/outbound-campaigns).
**Yksittäisiä ohjelmallisia puheluita varten:** käytä
[lähtevien puheluiden APIa](/fi/guides/place-outbound-calls).
***
## Reaaliaikainen seuranta
**Live** näyttää kaikki organisaation käynnissä olevat puhelut ja
antaa sinun avata minkä tahansa niistä, jotta voit [kuunnella ja
kuiskata](#calls) reaaliajassa. Se on valvontanäkymä: seuraa, kun uusi
kehote vastaanottaa ensimmäisen todellisen liikenteensä, tai pidä
käynnissä olevaa kampanjaa silmällä.
**Hallintapaneelissa:** **Live** (`/dashboard/live`). Katso
[Seuraa ja valvo reaaliaikaisia puheluita](/fi/guides/monitor-live-calls).
***
## Simulaatiot
**Simulaatiossa** tekoälysoittaja käy aidon keskustelun agenttisi
kanssa — sama puhelinliikenteen reitti, aito puhelutallenne, aito
arviointi — jotta voit testata ennen julkaisua (ja sen jälkeen).
Kohdista se agenttiin tai puhelinnumeroon, kirjoita soittajan skenaario
itse tai **luo skenaarioita tekoälyllä** agentin kehotteen perusteella
(mukaan lukien reunatapaukset, jos pyydät niitä) ja seuraa puhelua
reaaliajassa.
Skenaariot ryhmitellään **sarjoiksi**, jotka asettavat vähimmäis-
läpäisyasteen ja voivat estää julkaisut CI:ssä; hyväksyttyyn
vertailutasoon nähden tapahtuvat regressiot raportoidaan skenaariokohtaisesti.
**Hallintapaneelissa:** **Simulaatiot** (`/dashboard/simulations`) sekä
agentinrakentajan **Simulaatio**-painike. Katso
[Simuloi puhelu](/fi/guides/simulate-a-call).
**API:ssa:** [`/v1/test-calls`](/api-reference/test-calls) ja sarjan
suorittaja — katso [Testaa agentti päästä päähän](/fi/guides/test-agents).
***
## Kokeet
**Koe** A/B-testaa agenttiasetuksia aidolla liikenteellä: määritä
variantit (eri kehotteet, moottorit tai asetukset), jaa liikenne niiden
välillä ja vertaa tuloksia varianteittain. Käytä sitä sen sijaan, että
rakentaisit bucket-logiikan itse webhookiin.
**Hallintapaneelissa:** **Kokeet** (`/dashboard/experiments`) ja
agentinrakentajan **A/B**-välilehti. Katso
[Kokeet (A/B-testaus)](/fi/guides/experiments-ab-testing).
***
## Ongelmat
**Ongelma** on tiettyyn puheluun merkitty ongelma, jonka on ilmoittanut
ihmistarkastaja tai jonka tekoälyarviointi on havainnut. Ongelmiin liittyy
vakavuusaste, lähde ja tila, ja Ongelmat-sivu toimii triage-jonona: suodata,
tarkastele ongelmallista puhelua ja seuraa korjauksia.
**Hallintapaneelissa:** **Ongelmat** (`/dashboard/issues`) sekä puhelukohtainen
merkintä Puheluhistoriassa. Katso [ongelmien triage](/fi/guides/issues).
**API:ssa:** [`/v1/issue-reports`](/api-reference/issue-reports).
***
## Raportit
**Raportti** vastaa puheludataa koskevaan luonnollisen kielen kysymykseen
("Mitkä olivat kolme yleisintä syytä, joiden vuoksi soittajat pyysivät ihmistä
viime viikolla?") tekoälyn kirjoittamalla analyysilla, joka rajataan valitsemiisi
agentteihin ja ajanjaksoon.
**Hallintapaneelissa:** **Raportit** (`/dashboard/reports`). Katso
[Raportit](/fi/guides/reports).
***
## Seuranta
**Seuranta** on metriikkanäkymä: puhelumäärä, tulokset ja laatu ajan myötä,
suodatettavissa agentin ja aikavälin mukaan sekä vietävissä jatkoanalyysia
varten.
**Hallintapaneelissa:** **Seuranta** (`/dashboard/observability`).
Katso [Seuranta](/fi/guides/observability).
***
## Hälytykset
**Hälytyssääntö** seuraa metriikkaa (onnistumisaste, epäonnistumisaste,
keskimääräinen pisteytys, puhelumäärä, testisarjan regressiot) tietyn aikavälin
ajan ja laukeaa, kun se ylittää määrittämäsi kynnyksen. Ilmoitukset lähetetään
sähköpostiin ja Slackiin, ja se lähettää `alert.triggered`-tapahtuman
[webhook-päätepisteisiisi](/fi/webhooks/endpoints).
**Hallintapaneelissa:** **Organisaatio → Hälytykset**. Katso
[Hälytykset](/fi/guides/alerts).
***
## Webhookit
ThunderPhone lähettää **HTTP POST -webhookeja** palvelimellesi, kun puhelun
aikana ja sen jälkeen tapahtuu asioita. Toimitusmalleja on kaksi:
* **Webhook-päätepisteet** (suositeltu): hallitse useita URL-osoitteita
kohdassa [`/v1/developer/webhook-endpoints`](/fi/webhooks/endpoints), jossa
jokaisella päätepisteellä on omat salaisuudet ja tapahtumatilaukset.
* **Vanha yhden URL-osoitteen webhook**: yksi URL-osoite organisaatiota kohden.
Hallitaan kohdassa
[`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)
tai kohdassa **Organisaatio → Yleiset**. Säilytetty taaksepäin
yhteensopivuuden vuoksi.
Tapahtumat jakautuvat kahteen luokkaan:
* **Estävät tapahtumat** odottavat palvelimesi vastaavan määrityksellä, joka
muokkaa käynnissä olevaa puhelua — kyseessä ovat
[saapuvan puhelun tapahtumat](/fi/webhooks/call-incoming)
(`telephony.incoming` / `web.incoming`). Sinulla on enintään 10 sekuntia
aikaa vastata; aikakatkaisun yhteydessä staattisesti määritetty agentti
hoitaa puhelun.
* **Ei-estävät tapahtumat** ovat lähetä-ja-unohda-ilmoituksia, joita yritetään
uudelleen eksponentiaalisella viiveellä — katso
[toimitussemantiikka](/fi/webhooks/overview).
Jokaisessa pyynnössä on HMAC-SHA256-allekirjoitus otsakkeessa
`X-ThunderPhone-Signature`. Katso
[allekirjoituksen vahvistaminen](/fi/webhooks/overview).
***
## Funktiotyökalut
**Funktiotyökalu** on HTTP-päätepiste, jota agenttisi voi kutsua kesken
keskustelun. Annat ThunderPhonelle OpenAI-tyylisen funktioskeeman ja
päätepisteen URL-osoitteen; agentti päättää, milloin sitä kutsutaan, ja
ThunderPhone tekee allekirjoitetun HTTP-pyynnön palvelimiltaan sekä palauttaa
tuloksen agentille.
Agenteissa on myös **sisäänrakennettuja puheluominaisuuksia** — puhelun
siirtäminen, näppäimistösyötteen (DTMF) lähettäminen, puhelun lopettaminen ja
pidossa odottaminen — jotka otat käyttöön pelkillä kehotteen riveillä
työkalumääritysten sijaan.
**Hallintapaneelissa:** rakentajan **API-yhteydet**-osio (katso
[Yhteydet](#connections)).
**API:ssa:** [`/v1/integrations`](/api-reference/integrations) ja
[Funktiotyökalujen määritys](/fi/tools/overview).
***
## Tiimi ja roolit
Jokaisella organisaatiolla on jäsenluettelo, jossa on kaksi roolia: **Jäsenet**
rakentavat ja käyttävät agentteja; **Ylläpitäjät** hallitsevat lisäksi tiimiä
ja laskutusta. Kutsu sähköpostitse — kutsut vanhenevat 7 päivän kuluttua ja ne
voi peruuttaa; jäsenrivin ⋯-valikosta voit muuttaa rooleja tai poistaa henkilön.
Kertakirjautuminen voidaan määrittää koko organisaatiolle — katso
[SSO](/fi/guides/sso).
**Hallintapaneelissa:** **Organisaatio → Yleiset**. Katso
[Kutsu tiimisi](/fi/guides/invite-your-team).
**API:ssa:** [`/v1/members`](/api-reference/members),
[`/v1/invites`](/api-reference/invites).
***
## Laskutus
ThunderPhone on **ennakkomaksullinen**. Jokaisella organisaatiolla on USD-saldo; puheluista veloitetaan puheagentin minuuttihinnan mukaan (moottoritaso sekä lisämaksut —
rakennustyökalu näyttää kokonaishinnan reaaliajassa, kun muutat asetuksia, ja
[premium-kielet](/fi/guides/supported-languages) lisäävät 2 ¢/min). Kun
saldo saavuttaa nollan, saapuvat puhelut hylätään ja lähtevät puhelut
palauttavat `402 Payment Required`.
Lisää saldoa manuaalisesti tai ota käyttöön **automaattinen saldon lisäys**
saldorajan, lisäyssumman ja valinnaisen kuukausittaisen kulutusrajan avulla —
jotta puhelu ei koskaan katkea kesken lauseen.
**Hallintapaneelissa:** **Organisaatio → Laskutusasetukset** ja
**Laskutushistoria**. Katso
[Lisää saldoa ja ota automaattinen saldon lisäys käyttöön](/fi/guides/billing-and-topups).
**API:ssa:** [`/v1/billing`](/api-reference/billing).
***
## Sovelluksen sisäinen copilot
Hallintapaneelissa on sisäänrakennettu **copilot** — kysy siltä "miten teen X",
niin se vastaa näiden dokumenttien perusteella, tarjoaa vaiheittaisia opastuksia,
jotka korostavat todellisia säätimiä, ja voi toistaa minkä tahansa opastetun
kierroksen. Se on nopein tapa löytää tällä sivulla mainittu säädin.
Katso [Kysy sovelluksen sisäiseltä copilotilta](/fi/guides/ask-the-copilot).
***
## Kaikki yhdessä
Viisivaiheinen ohjattu toiminto: agentti → laskutus → numero → simulointi → tarkistus.
Sama ensimmäinen puhelu neljällä REST-kutsulla.
Luo agentti, lisää sille saldoa, hanki numero, simuloi ja tarkista puhelut.
OAuth-sovellukset, mukautetut API:t, MCP-palvelimet ja VoIP-palveluntarjoajat.
Raportit, havainnoitavuus, kokeet, ongelmat ja hälytykset.
Kutsut ja roolit, API-avaimet, tietoturva ja SSO.
API-reseptit: saapuvat puhelut, lähtevät puhelut, dynaaminen määritys, työkalut, testaus.
Tee HMAC-tarkistus oikein kerran ja käytä sitä kaikkialla.