Oppaat
Puheagentti
Agentti on juuri niin hyvä kuin sen järjestelmäkehote on kirjoitettu. Tämä sivu on opas sen kirjoittamiseen: mukana kolme valmista pohjaa kopioitavaksi sekä rajoitukset, jotka on otettava huomioon.
Avustajan numero
Agentti vastaa ja soittaa siitä numerosta, joka sille on määritetty agentin tietosivulla (kenttä numberE164 API:ssa). Puhenumero vastaanottaa ja tekee puheluita, mutta ei tekstiviestejä. Jos avustajalle halutaan numero, johon voi sekä soittaa että lähettää tekstiviestejä ja josta avustaja sekä soittaa että lähettää tekstiviestejä, tilataan numero puheluille ja tekstiviesteille: Prahan lankanumero, johon agentti vastaa volain omalla puhemoottorilla, kun numero on rekisteröity operaattorille (yleensä 1 arkipäivän, enintään 48 tunnin kuluessa). Siitä voi soittaa vain tšekkiläisiin numeroihin (+420), eikä siitä lähetetyistä tekstiviesteistä saada toimitusraportteja. Lisätiedot ovat API-dokumentaation kohdassa numero puheluille ja tekstiviesteille.
1systemPromptin rakenne
Hyvässä kehotteessa on neljä osaa. Jos jokin puuttuu, agentti jumittuu ennemmin tai myöhemmin eikä tiedä, mitä tehdä - se vaikenee tai keksii jotain.
- Kuka olen - yksi tai kaksi lausetta: yrityksen nimi, rooli, sävy. Agentin on tunnistettava itsensä siitä jo ensimmäisestä repliikistä alkaen.
- Mitä osaan - konkreettisia tehtäviä, joista agentti oikeasti selviää (tilaus, aika, tiedot) - ei yleistä ”autan missä tahansa”.
- Mitä en KOSKAAN tee - rajat: mitä agentti ei saa keksiä, luvata tai kertoa. Tämä osa jää useimmiten pois, mutta juuri se erottaa agentin, joka keksii hintoja, agentista, joka rehellisesti sanoo ”sitä en tiedä, soita numeroon...”.
- Näin puhelu päättyy - milloin ja miten puhelu lopetetaan (yhteenveto, hyvästely) ja mitä tehdään, kun asiakas haluaa jotain kehyksen ulkopuolelta.
Pidemmät ohjeet hidastavat vastausta noin kymmenyksen sekunnissa kahtatuhatta merkkiä kohden - agenttieditori varoittaa 3000 merkistä alkaen. Ehdoton raja on 6000 merkkiä.
Kolme täydellistä pohjaa - kopioi ja muokkaa:
Vastaanottovirkailija tilauksilla
Olet Vinohradyn kahvila Nulan puheohjattu vastaanottovirkailija. Puhut rauhallisesti,
ystävällisesti ja ytimekkäästi - kuin kokenut tarjoilija, et kuin robotti.
TÄMÄN OSAAT
- Otat vastaan tilauksia noudettavaksi (kahvi, tee, croissantit, voileivät).
- Osaat kertoa voimassa olevat aukioloajat: maanantaista perjantaihin 8:00-18:00,
viikonloppuisin 9:00-15:00.
- Tilauksen lopuksi toistat koko tilauksen ja vahvistat noutoajan
(aikaisintaan 15 minuutin kuluttua).
TÄTÄ ET KOSKAAN TEE
- Et keksi hintoja etkä tuotteita, joita valikoimassa ei ole - sano, että
tarkan hinnan vahvistaa henkilökunta paikan päällä.
- Et lupaa kotiinkuljetusta, kahvila ei kuljeta.
- Et koskaan esitä ihmistä, kun asiakas kysyy suoraan - kerro, että
olet kahvilan puheavustaja.
NÄIN LOPETAT PUHELUN
Tee yhteenveto tilauksesta ja noutoajasta, toivota hyvää päivänjatkoa ja lopeta puhelu. Jos
asiakas haluaa jotain, mitä et voi hoitaa (reklamaatio, catering), pyydä häntä
soittamaan uudelleen aukioloaikoina ja puhumaan suoraan omistajan kanssa.Tyytyväisyyskysely
Soitat verkkokauppa Botanikan puolesta ja teet lyhyen tyytyväisyyskyselyn
äskettäin tehdystä tilauksesta. Olet kohtelias, menet suoraan asiaan etkä
venytä puhelua turhaan.
TÄMÄN OSAAT
- Kysyt, onko asiakkaalla hetki aikaa kolmeen lyhyeen kysymykseen.
- Kysymys 1: Kuinka tyytyväinen asiakas on tilaukseen asteikolla 1-5?
- Kysymys 2: Saapuiko paketti ajoissa?
- Kysymys 3: Onko jotain, mitä voisimme parantaa?
- Muistat vastaukset ja teet niistä lyhyen yhteenvedon puhelun lopussa.
TÄTÄ ET KOSKAAN TEE
- Et painosta asiakasta, jos hän kieltäytyy tai sanoo, ettei hänellä ole aikaa -
sano kohteliaasti näkemiin heti.
- Et käsittele reklamaatioita etkä palautuksia - ne kuuluvat asiakaspalvelulle,
jonka numeron luet ääneen, jos asiakas pyytää.
- Et tarjoa alennuksia etkä kuponkeja, siihen sinulla ei ole valtuuksia.
NÄIN LOPETAT PUHELUN
Kiitä ajasta ja palautteesta ja toivota hyvää päivänjatkoa. Jos asiakas milloin tahansa
sanoo, ettei halua jatkaa, lopeta puhelu kohteliaasti heti ilman lisäkysymyksiä.Portti / luovutus
Olet yrityksen Nordwex puheohjattu portti Pankrácin toimistorakennuksessa.
Kuriirit, vieraat ja toimittajat ilmoittautuvat soittamalla tähän numeroon.
TÄMÄN OSAAT
- Selvität, kuka soittaa ja missä asiassa (kuriiri paketin kanssa,
vieras kokoukseen, toimittaja).
- Vieraalta kysyt nimen ja sen, kenen kanssa kokous on, ja pyydät häntä
ilmoittautumaan alakerran vastaanotossa ja odottamaan, kunnes joku hakee hänet.
- Kuriirille kerrot, että paketti jätetään vastaanottoon
yrityksen nimi ja vastaanottaja merkittyinä.
- Otat lyhyen viestin, kun haettu henkilö ei ole juuri nyt tavoitettavissa.
TÄTÄ ET KOSKAAN TEE
- Et anna työntekijöiden yksityisten matkapuhelinten numeroita - tarjoat
yhdistämistä vastaanottoon tai viestin jättämistä.
- Et päästä ketään sisään "ihan itse" - kaikki vieraat kulkevat
vastaanoton kautta.
- Et kerro, kuka rakennuksessa on ja milloin - sano,
että asia pitää tarkistaa vastaanotosta.
NÄIN LOPETAT PUHELUN
Toista sovitut asiat (viesti, odotus vastaanotossa, yhdistäminen), toivota
hyvää päivänjatkoa ja lopeta puhelu.2Pohjat toimialoittain
Ei huvita kirjoittaa kehotetta alusta asti? Verkkosivustolla on valmiit pohjat kuudelle toimialalle (hammashoito, autokorjaamo, ravintola, verkkokauppa, kiinteistönvälittäjät, käsityöläiset) - valmis järjestelmäkehote, esimerkkipuhelu ja esimerkki siitä, mitä tällainen vastaanottovirkailija maksaisi. Kopioi ja muokkaa, aivan kuten yllä olevia pohjia.
Yleiskatsaus pohjista toimialoittain
3firstMessage
firstMessage on ensimmäinen lause, jonka asiakas kuulee - saapuvassa puhelussa heti, kun agentti vastaa, lähtevässä heti, kun soitettu vastaa puhelimeen.
- Lyhyt, puhuttu kieli - sellaisena kuin ihminen sanoisi sen, ei kuin sähköpostissa.
- Kerro heti, kuka tai mikä soittaa tai vastaa - asiakkaan pitää kolmen sekunnin kuluessa tietää, kenen kanssa puhuu.
- Lopeta avoimeen kysymykseen (”miten voin auttaa”, ”onko sinulla hetki aikaa”) - ei pitkään monologiin.
- Lue ääneen - mikä näyttää hyvältä kirjoitettuna, voi kuulostaa jäykältä puhuttuna.
- Lähtevissä puheluissa agentin pitää esittäytyä ja kertoa soiton syy heti - ihmiset vastaavat tuntemattomista numeroista vastahakoisesti.
4Työkalut
Työkalu on oman API:n osoite, jota agentti kutsuu kesken puhelun, ja vastausta käytetään heti puheessa. Ilman työkaluja agentti osaa vain puhua; työkalujen avulla se voi tarkistaa tilauksen, löytää vapaan ajan tai kirjata varauksen.
Työkalut luodaan portaalissa osoitteessa /agent/nastroje (tai kutsulla POST /v1/tools) ja otetaan sitten käyttöön agentille valintaruudulla agentin tietosivulla (kenttä toolIds API:ssa). Työkalu kuuluu tilille, ei agentille - samaa työkalua voi siis käyttää useampi agentti. Sille määritetään neljä asiaa:
- Nimi - luettava (”Tarkista tilaus”). Malli näkee automaattisesti johdetun nimen (
tarkista_tilaus), ja se näytetään kentän alla. - Milloin agentin pitää käyttää sitä - ainoa asia, joka ratkaisee, kutsuuko malli työkalua lainkaan. Kirjoita se ohjeena: ”Käytä, kun soittaja kysyy, missä tilaus on.”
- Osoite ja metodi - vain
https, julkisesti tavoitettavissa.GETlähettää parametrit queryssä,POSTJSON-rungossa. Lisäksi otsakkeet, tavallisestiAuthorization. - Parametrit - jokaiselle parametrille määritetään, mistä arvo tulee: malli poimii sen puhelusta, täytetään soittajan numero tai soitettu numero, tai se on kiinteä arvo.
Tältä näyttää pyyntö, joka saapuu omaan päätepisteeseen puhelun aikana:
POST https://api.sovelluksesi.fi/tilaukset
Content-Type: application/json
Authorization: Bearer sinun_avaimesi
{
"tilausnumero": "A-42",
"puhelin": "+358401234567"
}Ja tältä näyttää vastaus, jonka kanssa agentti voi työskennellä - lyhyt JSON, jonka perusteella voi sanoa yhden lauseen:
{
"tila": "lahetetty",
"toimitus": "huomenna aamupäivällä"
}Kokeile työkalua ennen tallentamista
Lomakkeessa on Testaa-painike: se lähettää oikean pyynnön esimerkkiarvoilla annettuun osoitteeseen ja näyttää tilan, vasteajan ja vastauksen alun. Mitään ei tallenneta. Se kannattaa - hitaasti vastaava päätepiste kuulostaa soittajalle hiljaisuudelta puhelussa.
Rajoitukset: enintään 10 työkalua tiliä kohden, 10 parametria ja 5 otsaketta työkalua kohden, aikakatkaisu 5-30 sekuntia (oletus 20) - niin kauan agentti odottaa vastausta ja sanoo sillä välin ylimenolauseen, jotta soittaja ei kuule hiljaisuutta. Otsakkeiden arvot näytetään vain peitettyinä (Bear***) - koko arvoa ei voi lukea tililtä.
Vahvistuslukko työkalulle, joka lähettää jotain
Työkalulle, jolla on sivuvaikutus (lähettää tekstiviestin, luo tapauksen), vahvistuslukko otetaan käyttöön kentällä requireConfirmation: true (POST ja PATCH /v1/tools, MCP:ssä create_tool ja update_tool). volain oma puhemoottori suorittaa tällöin työkalun vain, kun soittajan viimeisin repliikki sanoo selvästi kyllä. Jos vastaus on epäselvä (”Haloo”, ”Joo?”, ”Kyllä, mutta myöhemmin”), työkalua ei suoriteta, agentti saa ohjeen kysyä uudelleen ja puhelun lopettaminen samalla vuorolla siirtyy myöhemmäksi. Oletuksena pois päältä.
Koskee vain agentteja omalla moottorilla tšekin tai slovakin kielellä: moottori tuntee vahvistussanat vain näillä kahdella kielellä (kielillä en, de ja pl myös selkeä ”Yes” estettäisiin), joten kenttä ohitetaan agentilla, jonka kieli on jokin muu, eikä ElevenLabs käytä sitä. Työkalu kuuluu tilille ja sitä jakaa useampi agentti, joten tallennusta ei hylätä kielen perusteella. Lukko lukee vain viimeisimmän repliikin eikä tunne agentin kysymystä: se pysäyttää epäselvän suostumuksen, ei jokaista ”Kyllä”-vastausta, joka sanotaan vastauksena johonkin toiseen kysymykseen. Työkalun muutos tavoittaa moottorilla jo pyörivän agentin vasta agentin seuraavassa tallennuksessa tai julkaisussa - työkalun muokkaus ei ylikirjoita agentteja itsestään. Käynnissä olevalle kampanjalle vaikutus riippuu menettelystä: testatun luonnoksen julkaiseminen uudelleen ilman muutoksia säilyttää merkinnän ”testattu”, tehtävä jatkuu, mutta nyt lukolla, jota testi ei kattanut; agentin suora tallennus (PATCH /v1/agents/{id}) kumoaa merkinnän ja tehtävä pysähtyy koodilla agent_version_changed. Ota lukko siksi käyttöön käynnissä olevan kampanjan ulkopuolella ja testaa kampanja sen jälkeen uudelleen.
Portaalissa lukko otetaan käyttöön kytkimellä Vaadi soittajan selkeä suostumus työkalueditorissa (/agent/nastroje). Sama pätee kuin yllä on kuvattu; moottorilla jo pyörivälle agentille muutos tulee voimaan Julkaise-painikkeella agentin tietosivulla.
5Yhdistäminen ihmiselle
Agentti voi luovuttaa puhelun omaan numeroon, kun soittaja pyytää ihmistä tai kohtaa jotain, mitä agentti ei osaa ratkaista. Se otetaan käyttöön agentin tietosivulla (kenttä transferTo API:ssa), ja ehto kirjoitetaan mallille ohjeena kenttään transferCondition. Ilman ehtoa käytetään oletuslausetta.
volain omalla puhemoottorilla
volain omalla puhemoottorilla yhdistäminen tapahtuu sillan kautta: agentti sanoo, että puhelu yhdistetään, soittaja kuulee soittoäänen ja oman numeron henkilö näkee agentin numeron. Kun puheluun vastataan, agentti vaikenee ja puhelu jatkuu kahden osapuolen välillä volain kautta. Jos jompikumpi teistä katkaisee puhelun, se päättyy molemmille. Jos puheluun ei vastata 25 sekunnin kuluessa, agentti pyytää soittajalta anteeksi, tarjoaa viestin jättämistä ja jatkaa.
Kaksi asiaa, jotka kannattaa tietää etukäteen
Yhteenvetoa puhelusta ei välitetä ihmiselle. Soittaja kuulee, että puhelu yhdistetään, mutta toisessa päässä oleva operaattori vastaa suoraan soittajalle - ”warm transferia”, jossa agentti ensin tiivistää asian, emme pysty toteuttamaan puhelinverkon kautta. Ota se huomioon ohjeissa: pyydä agenttia kertomaan soittajalle, että asia täytyy toistaa.
Yhdistäminen on tavallinen lähtevä puhelu ja laskutetaan sellaisena: 0,0384 €/min vastauksesta luurin laskemiseen, ilman agenttilisää (agentti ei enää ole mukana tuossa osassa). Puhelulokissa sen tunnistaa tyypistä transfer, ja alkuperäisen puhelun tiedoissa on Yhdistäminen-kortti, jossa on linkki tuohon osaan. Saapuva osa jatkuu ja laskutetaan erikseen.
Oletusalusta (ElevenLabs)
Oletusalustalla (ElevenLabs) yhdistäminen ei toimi - operaattori ei viimeistele SIP-yhdistämistä. Kun yhdistäminen otetaan käyttöön, volai yrittää heti tallennuksen jälkeen siirtää agentin omalle puhemoottorille. Yritys voi olla keskeytettynä, moottori voi olla poissa käytöstä tai vaihto voi epäonnistua; tarkista siksi palautetusta kentästä provider, että agentti todella toimii moottorilla. Niin kauan kuin se on ElevenLabsissa, yhdistäminen ei toimi. Onnistunut vaihto voi muuttaa agentin ääntä, moottorin oletusääni on Milena.
Yhdistäminen omaan volai-numeroon ei onnistu - puhelu soittaisi takaisin itselleen, kunnes saldo loppuu. Premium-numerot (90x) on kielletty samasta syystä.
Agentti, joka käyttää tuotetta numero puheluille ja tekstiviesteille, yhdistää vain tšekkiläisiin numeroihin (+420): siitä numerosta voi soittaa vain tšekkiläisiin numeroihin, joten numeroa +420-alueen ulkopuolelta ei tallenneta tällaiselle agentille ja API palauttaa destination_not_allowed.
6Mitä puhelusta kirjataan ylös
Koko litteroinnin lukemisen sijaan voidaan määrittää tarkasti, mitä puhelusta halutaan - nimi, määrä, onko asia kiireellinen. Agentti täyttää tiedot puhelun jälkeen ja tulos toimitetaan JSON-muodossa.
Jokaisella kentällä on avain, tyyppi ja kuvaus. Enintään kymmenen kenttää agenttia kohden:
- Avain (
key) - pieniä kirjaimia ilman diakriittisiä merkkejä, numeroita ja alaviivoja, enintään 40 merkkiä - pitää alkaa pienellä kirjaimella. Arvo löytyy tuloksesta tällä nimellä. - Tyyppi (
type) -string,numbertaiboolean. - Kuvaus (
description) - mitä tarkalleen mallin pitää poimia, 5-500 merkkiä. Kirjoita myös, mitä tehdään, jos asiaa ei mainita puhelussa. - Vaihtoehdot (
enumValues) - valinnainen luettelo, vain tekstikentille. Malli valitsee silloin vain annetuista arvoista, joten tuloksen voi suodattaa suoraan. Enintään 20 vaihtoehtoa, kukin enintään 60 merkkiä.
curl -X PATCH https://volai.cz/v1/agents/ag_kx91fa2b \
-H "Authorization: Bearer vk_SINUN_AVAIMESI" \
-H "Content-Type: application/json" \
-d '{
"dataFields": [
{"key": "nimi", "type": "string", "description": "Soittajan nimi sellaisena kuin soittaja sen itse sanoi. Jätä tyhjäksi, jos nimeä ei mainittu."},
{"key": "kahvien_maara", "type": "number", "description": "Montako kupillista kahvia soittaja tilasi."},
{"key": "kiireellisyys", "type": "string", "description": "Kuinka kiireellinen asia oli.", "enumValues": ["matala", "normaali", "korkea"]}
]
}'Tulos näkyy kolmessa paikassa: puhelun tietosivulla portaalissa korttina ”Kirjatut tiedot”, puhelun kentässä data (GET /v1/calls ja GET /v1/calls/{id}) ja webhookin call.completed rungossa.
{
"call": {
"id": "c_8f2ac1d4",
"status": "completed",
"hasRecording": true,
"data": {
"nimi": "Anna Virtanen",
"kahvien_maara": 2,
"kiireellisyys": "normaali"
}
}
}Arvo null tarkoittaa ”sitä ei mainittu puhelussa” - sama pätee, kun malli vastaa tyhjällä tekstillä. Jos agentilla ei ole kenttiä, avainta data ei ole vastauksessa lainkaan.
7Agentin tavoite ja arviointi
Tavoite on yksi lause siitä, mihin puhelulla pyritään - ”varaa aika näytölle”, ”selvitä, onko asiakas kiinnostunut tarjouksesta”. Se täytetään portaalissa kenttään ”Agentin tavoite” (agenttia luotaessa ja milloin tahansa myöhemmin muokatessa) tai REST API:n ja MCP:n kautta kentällä goal kutsuissa POST/PATCH /v1/agents ja create_agent/update_agent (enintään 300 merkkiä).
Tavoite kulkee agentin mukana puhelun arvioinnin kriteerinä: kun puhelu on päättynyt, malli lukee litteroinnin ja ratkaisee, saavutettiinko tavoite, jäikö se saavuttamatta vai ei voida päätellä puhelun perusteella. Tulos näytetään puhelulle portaalissa - tietosivulla ja puhelulistassa - sekä puhelun jälkeisessä sähköpostissa yhteenvedon vieressä.
Se on mallin arvio, ei fakta
Arviointi lukee vain puhelun litteroinnin, ei sitä, mitä tapahtui sen jälkeen (tuliko asiakas todella tapaamiseen). Rehellinen varaus: agentin tavoite (goal) voidaan asettaa ja lukea REST API:n ja MCP:n kautta, mutta yksittäisen puhelun arvioinnin TULOS on vain portaalissa ja puhelun jälkeisessä sähköpostissa - GET /v1/calls ja get_call eivät palauta sitä. Arviointi ajetaan lisäksi vain agenteille, jotka toimivat volain uudella puhemoottorilla - millä alustalla agentti toimii, näkyy kentästä provider (GET /v1/agents, list_agents ja agentin tietosivu portaalissa); vaihdosta huolehtii volai. Vanhemmat agentit, jotka ovat yhä alkuperäisellä alustalla, saavat arvioinnin vasta siirryttyään tälle moottorille.
Mitä agentti tietää (aineisto)
Ohjeiden lisäksi agentille voi antaa aineistoa - aukioloajat, hinnasto, usein kysytyt kysymykset. Se täytetään portaalissa kenttään ”Mitä agentti tietää” (Lisäasetukset-osio), API:ssa kentällä knowledge kutsuissa POST/PATCH /v1/agents. Teksti liitetään kehotteen loppuun, mahtuu 20000 merkkiin ja PATCH tyhjällä arvolla poistaa sen. Toisin kuin työkalu, aineisto ei muutu puhelun aikana - se, mikä muuttuu (tilauksen tila, vapaat ajat), kuuluu työkaluun, ei tähän.
8Sähköposti puhelun jälkeen
Kun agentin puhelu on päättynyt, volai lähettää sähköpostin, jossa on yhteenveto ja linkki puhelun tietosivulle portaalissa - sama yhteenveto, joka näkyy API:ssa kentässä summary. Se lähetetään agenteille, jotka toimivat volain omalla puhemoottorilla (kenttä provider: "engine"); ElevenLabsin agentti (provider: "elevenlabs") ei saa sitä vielä.
Kytkin ”Sähköposti jokaisen puhelun jälkeen” on sivulla Asetukset - kun se kytketään pois, lähetys loppuu heti koko tililtä. Yksittäiselle agentille se kytketään pois erikseen valintaruudulla ”Lähetä sähköposti jokaisen puhelun jälkeen” agentin tietosivulla (kenttä notifyEmail: false API:ssa). Puhelusta lähetetään enintään yksi sähköposti, ja puhelusta, josta ei ole mitään raportoitavaa (ei yhteenvetoa, ei kirjattuja tietoja eikä lopetussyytä), ei lähde sähköpostia.
9Tallenteet
Agentin puhelut tallennetaan, ja ne voi toistaa suoraan puhelun tietosivulla portaalissa - litteroinnin kohtaa napsauttamalla toisto hyppää oikeaan kohtaan. Tallenteen voi ladata tai toistaa muualla osoitteesta GET /v1/calls/{id}/recording (sama API-avain) - muodon ratkaisee vastauksen otsake content-type: ElevenLabsin agentilla audio/mpeg (MP3), volain moottorin agentilla tällä hetkellä audio/ogg. Onko puhelulla tallenne, selviää kentästä hasRecording.
- Ne säilytetään 90 päivää puhelusta lukien, minkä jälkeen ne poistetaan. Litterointi ja yhteenveto säilyvät, niitä ei poisteta tallenteen mukana. Yhdeksänkymmenen päivän jälkeen päätepiste palauttaa
recording_expired. - Voidaan kytkeä pois jokaiselta agentilta erikseen - kytkimellä agentin tietosivulla, API:ssa kentällä
recordCalls: false. Tallennetta ei luoda puheluille, jotka alkavat siitä hetkestä lähtien; puhelu, joka jo soi tai on käynnissä, noudattaa asetusta siltä ajalta, kun se alkoi (lähtevissä soiton alkamishetkestä), ja tallennetaan siksi silti. - Tallennetaan vain puhelut sisäänrakennetun agentin kanssa. Kahden numeron suoraa yhdistämistä (bridge), relayta ja SIP-puheluita ei tallenneta.
Vastuu soittajan informoinnista on asiakkaalla
Puhelun tallentaminen on henkilötietojen käsittelyä. Agentti ei kerro siitä soittajalle itse - tarvittaessa agentille otetaan käyttöön vaihtoehto ”Kerro soittajalle, että puhelu tallennetaan” (recordingNotice: true API:ssa), ja volai lisää agentin ensimmäisen lauseen jälkeen lyhyen lauseen tallennuksesta. Sen voi yhtä hyvin kirjoittaa suoraan ensimmäiseen lauseeseen. Siitä, että tiedot vastaavat omaa tilannetta koskevaa lakia, vastaa asiakas rekisterinpitäjänä.
Jokainen API-virhe sisältää cause (kuka korjaa) ja action (mitä pitää tehdä) - katso Virheen muoto REST API -viitteessä.
10Rajoitukset
- Puhelu kestää enintään 10 minuuttia (600 sekuntia), minkä jälkeen agentti lopettaa sen itse.
- Jos soittaja on hiljaa 20 sekuntia, agentti tulkitsee sen puhelun päättymiseksi ja katkaisee puhelun.
- Agentin vasteaika on noin 1 sekunti siitä, kun soittaja lopettaa puhumisen - todellisessa käytössä se vaihtelee hieman kuormituksen mukaan.
11Kielet
Agentti osaa puhua 23 kieltä - tšekki on oletus, koodiluettelo on API:n kentän language kohdalla (cs, sk, en, de, pl, nl, pt, sl, ro, da, et, lv, bg, fi, el, fr, it, hu, lt, sv, hr, es, is) - kieli asetetaan agentin tietosivulla (kenttä language kutsuissa POST/PATCH /v1/agents, create_agent/update_agent) - oma ääni jokaiselle kielelle (Cartesia) on vain volain omalla puhemoottorilla (katso luku Äänet alla), ElevenLabsin agentti puhuu valittua kieltä kyseisen kielen oletusäänellä, yleiskatsauksen äänistä palauttaa GET /v1/voices (MCP list_voices).
12Testipuhelu
Painike ”Soita minulle testiksi” agentin tietosivulla portaalissa käynnistää oikean puhelun agentilta annettuun numeroon - nopea tapa tarkistaa, miltä agentti kuulostaa ja miten se reagoi järjestelmäkehotteeseen, ilman että tarvitsee soittaa käsin sen numeroon.
Se laskutetaan tavallisena lähtevänä puheluna agentin kanssa, agenttilisä mukaan lukien (katso luku Hinnat alla) - ei alennusta eikä erillistä taksaa.
Agentti volain omalla puhemoottorilla pystyy testipuheluihin myös ilman omaa puhelinnumeroa - silloin käytetään volain yhteistä linjaa, joten soitettu näkee näytöllä volain numeron, ei agentin. ElevenLabsin agentti ilman omaa numeroa ei voi aloittaa testipuhelua, ennen kuin numero on määritetty.
Enintään 3 testipuheluyritystä päivässä tiliä kohden, kaikki agentit yhteensä - jokainen yritys, jossa todella soitettiin, lasketaan, vaikka kukaan ei vastannut; yritystä, joka epäonnistui jo ennen soittoa (riittämätön saldo, varattu linja), ei lasketa rajaan. Tavallisilla puheluilla kutsun POST /v1/calls kautta ei ole tätä tiukempaa rajaa.
13Äänet
Palveluntarjoajan valinnalla luotaessa on kolme tilaa: useForOutboundTasks: true kutsussa POST /v1/agents tai create_agent valitsee volain oman puhemoottorin, false käynnistää oletusalustalla (ElevenLabs), vaikka yhdistäminen asetetaan samalla, ja pois jätetty kenttä käyttää jakelun senhetkistä oletusasetusta, joka riippuu siitä, onko moottori päällä ja mitkä kielet sallitaan. Pelkkä cs tai sk ei takaa moottoria; kun oletusmoottori on pois päältä, agentti luodaan ElevenLabsiin. Kun nimenomainen false ohittaa kielen oletusmoottorin, luontivastauksessa on varoitus elevenlabs_by_explicit_choice; vain saapuville puheluille tarkoitettu agentti luodaan siksi ilman kenttää. Kun transferTo otetaan käyttöön ElevenLabsin agentille, volai yrittää siirtää sen moottorille tallennuksen jälkeen. Yritys voi olla keskeytettynä, poissa käytöstä tai epäonnistua, joten tarkista tulos aina: REST:ssä seuraavalla kutsulla GET /v1/agents/{id}, MCP:ssä palautetusta agentista. Millä alustalla agentti toimii, näkyy kentästä provider; niin kauan kuin se on ElevenLabsissa, yhdistäminen ei toimi. Onnistuneessa vaihdossa ääni voi muuttua. Sama yritys käynnistyy, kun ElevenLabsin agentin language vaihdetaan kielestä, jolla uudet agentit luodaan ElevenLabsiin (nykyisin en, de, pl), kieleen, jolla ne luodaan moottorille (cs, sk); agentti saa silloin moottorin oletusäänen uudelle kielelle (Milena, Katarina). Vaihto kielten cs ja sk välillä ei siirrä mitään. Muuten volai (tuki) vaihtaa alustojen välillä. ElevenLabsin agentti hyväksyy vain kattyn tai raa'an ElevenLabsin voice id:n; muut katalogin äänet toimivat vain moottorilla.
voiceId kutsuissa create_agent/update_agent (ja samannimisessä kentässä kutsuissa POST/PATCH /v1/agents) valitsee agentin äänen. Suodattamaton luettelo GET /v1/voices (MCP list_voices ilman argumenttia provider) ei näytä ElevenLabs-ääntä katty - REST palauttaa sen vasta parametrilla ?provider=elevenlabs, MCP argumentilla provider: "elevenlabs". Cartesia-äänet (Milena, Jan ja muiden kielten äänet) on tarkoitettu volain omalla moottorilla toimiville agenteille, Katty ElevenLabsin agenteille (millä alustalla agentti toimii, käsitellään yllä olevassa huomautuksessa). Vanhempi ääni anet on jäljellä vain agenteille, joilla se jo on - ElevenLabs ei enää anna sitä uusille agenteille 12. 9. 2026 alkaen, ja volai hylkää sellaisen pyynnön selityksen kera. Luotaessa nimenomaisella useForOutboundTasks: true tunnettu ääni, jota moottori ei tue, katty mukaan lukien, korvataan moottorin oletusäänellä valitulle kielelle; jos moottori valitaan vasta oletusasetuksella kentän jäädessä pois, sama yhteensopimaton ääni hylätään. Raa'an ElevenLabsin id:n moottori hylkää aina. Ilman voiceId:tä agentti saa palveluntarjoajansa oletusäänen - moottorilla Milena, ElevenLabsissa pohjan äänen (Katty).
Katalogi tarjoaa jokaiselle kielelle vähintään yhden naisäänen ja yhden miesäänen (tšekille tällä hetkellä neljä): cs: Milena, Jan, Tereza, Marek; sk: Katarina, Peter; en: Skylar, Daniel; de: Alina, Lukas; pl: Ewa, Kacper; nl: Ariel, Alexander; pt: Christine, Filipe; sl: Sarah, Daniel; ro: Mikidutza, Oliver; da: Isabella, Søren; et: Alice, Chris; lv: Matilda, George; bg: Yoana, Peter K; fi: Soili, Jussi; el: Crhysa, Iordanis; fr: Natasha, Max; it: Rossana, Marco; hu: Zsófia, Gábor; lt: Sarah, Daniel; sv: Sanna, Filip; hr: Ivana, Davor; es: Diana, Rayito; is: Sarah, Daniel. Portaali näyttää vain agentin valitun kielen äänet - ne vaihtuvat yhdessä (katso luku Kielet yllä).
Kaikki taulukon äänet kuuluvat volain omalle puhemoottorille. ElevenLabsin agentilla API hylkää ne virheellä 400 - se ottaa katalogista vain kattyn (piilotettu suodattamattomassa luettelossa) ja raa'an ElevenLabsin voice id:n.
| id | Kuvaus | Kuuntelu |
|---|---|---|
| milena | Milena - volain oletusääni: rauhallinen ja luonnollinen, sopii useimmille agenteille. | |
| jan | Jan - Milenan miespuolinen vastine: asiallinen, helposti seurattava esitystapa. | |
| tereza | Tereza - Toinen naisääni - ammattimainen, jäsennelty esitystapa. | |
| marek | Marek - Toinen miesääni - rauhallinen, sointuva esitystapa pidempiin puheluihin. | |
| katarina | Katarina - Slovakialainen naisääni - rauhallinen, luonnollinen esitystapa. | |
| peter | Peter - Slovakialainen miesääni - asiallinen, helposti seurattava esitystapa. | |
| skylar | Skylar - Englantilainen naisääni - rauhallinen, ystävällinen esitystapa. | |
| daniel | Daniel - Englanninkielinen miesääni - asiallinen, varma esitystapa. | |
| alina | Alina - Saksankielinen naisääni - rauhallinen, lämmin esitystapa. | |
| lukas | Lukas - Saksalainen miesääni: asiallinen, helposti seurattava esitystapa. | |
| ewa | Ewa - Puolankielinen naisääni - rauhallinen, luonnollinen esitystapa. | |
| kacper | Kacper - Puolalainen miesääni - asiallinen, itsevarma esitystapa. | |
| ariel | Ariel - Hollantilainen naisääni - luonnollinen, keskusteleva esitystapa. | |
| alexander | Alexander - Hollantilainen miesääni - lämmin, luonnollinen esitystapa. | |
| christine | Christine - Portugalilainen naisääni - rento, keskusteleva esitystapa. | |
| filipe | Filipe - Portugalilainen miesääni - luonnollinen, ilmaisuvoimainen esitystapa. | |
| mikidutza | Mikidutza - Romanialainen naisääni - selkeä, ystävällinen esitystapa. | |
| oliver | Oliver - Romanialainen miesääni - asiallinen, selkeä esitystapa. | |
| isabella | Isabella - Tanskalainen naisääni - lämmin, rauhallinen esitystapa. | |
| soren | Søren - Tanskalainen miesääni - selkeä, itsevarma esitystapa. | |
| yoana | Yoana - Bulgarialainen naisääni - raikas, mukaansatempaava esitystapa. | |
| peterk | Peter K - Bulgarialainen miesääni - lämmin, sujuva esitystapa. | |
| soili | Soili - Suomalainen naisääni - neutraali, kevyt esitystapa. | |
| jussi | Jussi - Suomalainen miesääni - voimakas, eloisa esitystapa. | |
| crhysa | Crhysa - Kreikkalainen naisääni - ammattimainen, eloisa esitystapa. | |
| iordanis | Iordanis - Kreikkalainen miesääni - luonnollinen, keskusteleva esitystapa. | |
| natasha | Natasha - Ranskalainen naisääni - pehmeä, keskusteleva esitystapa. | |
| max | Max - Ranskalainen miesääni - karismaattinen, ystävällinen esitystapa. | |
| rossana | Rossana - Italialainen naisääni - lämmin, keskusteleva esitystapa. | |
| marco | Marco - Italialainen miesääni - karismaattinen, ystävällinen esitystapa. | |
| zsofia | Zsófia - Unkarilainen naisääni - pehmeä, kutsuva esitystapa. | |
| gabor | Gábor - Unkarilainen miesääni - lämmin, luonnollinen, itsevarma esitystapa. | |
| sanna | Sanna - Ruotsalainen naisääni - suora, luonnollinen esitystapa. | |
| filip | Filip - Ruotsalainen miesääni - energinen, ilmaisuvoimainen esitystapa. | |
| ivana-hr | Ivana - Kroatialainen naisääni - eloisa, ystävällinen esitystapa. | |
| davor | Davor - Kroatialainen miesääni - luonnollinen, keskusteleva esitystapa. | |
| sarah-sl | Sarah - Slovenialainen naisääni - rauhallinen, itsevarma esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| daniel-sl | Daniel - Slovenialainen miesääni - tasainen, uutislukijamainen esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| alice-et | Alice - Virolainen naisääni - selkeä, mukaansatempaava esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| chris-et | Chris - Virolainen miesääni - maanläheinen, charmikas esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| matilda-lv | Matilda - Latvialainen naisääni - asiantunteva, ammattimainen esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| george-lv | George - Latvialainen miesääni - lämmin, lumoava esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| sarah-lt | Sarah - Liettualainen naisääni - rauhallinen, itsevarma esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| daniel-lt | Daniel - Liettualainen miesääni - tasainen, uutislukijamainen esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| sarah-is | Sarah - Islantilainen naisääni - rauhallinen, itsevarma esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| daniel-is | Daniel - Islantilainen miesääni - tasainen, uutislukijamainen esitystapa (monikielinen ääni, malli ohjaa ääntämistä). | |
| diana-es | Diana - Espanjalainen naisääni - miellyttävä asiakaspalvelutyylinen esitystapa. | |
| rayito | Rayito - Espanjalainen miesääni - lämmin, luonnollinen meksikolainen esitystapa. |
voiceId hyväksyy myös raa'an ElevenLabsin id:n, mutta vain oletusalustan agentille (provider: "elevenlabs"). Moottorin agentille käytetään katalogin ääni-id:tä. Tuntematon arvo tai sellainen, joka ei sovi palveluntarjoajalle, tuottaa virheen, joka luettelee kelvolliset vaihtoehdot.
14Tilastot
Agentin tietosivu portaalissa näyttää vastattujen puheluiden määrän, niiden keskimääräisen ja pisimmän keston sekä määrän viimeisten 30 päivän ajalta - tähän ei ole omaa API:a, mutta luvut voi laskea itse GET /v1/calls -kutsun tuloksesta.
15Hinnat
Puheagentti laskutetaan puhelun hinnan lisäksi sekunnin tarkkuudella - ei pyöristystä täysiin minuutteihin. Taksat ovat ilman ALV:tä, kuten koko hinnasto.
| Suunta | Puhelu | Agentti | Yhteensä |
|---|---|---|---|
| Lähtevä | 0,0384 €/min | 0,105 €/min | 0,143 €/min |
| Saapuva | 0,0209 €/min | 0,105 €/min | 0,125 €/min |
Yksityiskohtainen hinnasto esimerkkeineen on sivulla Hinnat.
Käytätkö mieluummin ElevenLabsia, Vapia tai jotain muuta alustaa? Ilman agenttilisää se onnistuu oman agentin kautta - katso Oma agentti.
16Litteroinnit ja webhook
Kun puhelu on päättynyt, litterointi ja yhteenveto noudetaan kutsulla GET /v1/calls/{id} (kentät transcript ja summary) - tai volai lähettää ne itse omaan URL-osoitteeseesi tapahtumana, jonka tyyppi on call.completed, heti kun ne ovat valmiita. Litteroinnin muoto, allekirjoituksen todennus ja toiminta virhetilanteessa on kuvattu sivulla Webhookit.
Ei huvita odottaa webhookia tai kysellä API:a? Portaalissa jokaisella agentilla on tietosivulla myös yleiskatsaus viimeisimpiin puheluihin, ja litteroinnin voi lukea suoraan.
17volain puhemoottori
Osa agenteista toimii nykyisin volain omalla puhemoottorilla ElevenLabsin sijaan. Vaihto muuttaa puhelun reititystä, ja koko agentin kokoonpano siirtyy mukana - ohjeet, ensimmäinen lause, keruukentät, puhelun tavoite, tietämys, työkalut ja yhdistäminen ihmiselle. Tämä muuttuu ja tämä ei muutu:
- Äänet agentti, jolla oli valittu ElevenLabs-ääni (Katty tai vanhempi Anet), saa vaihdon jälkeen moottorin oletusäänen omalle kielelleen - tšekille Milena. Moottori ei tarjoa ElevenLabs-ääntä pääasiallisena äänenään, ElevenLabs on siellä jäljellä vain varana Cartesian katkon varalta. Agentin asetuksista voi sen jälkeen valita minkä tahansa muun äänen katalogista agentin kielelle, tšekille esimerkiksi Janin. Ääntä, joka agentilla jo on moottorin katalogista, vaihto ei muuta.
- Vasteaika pysyy samana kuin ElevenLabsilla - noin 1 sekunti siitä, kun soittaja lopettaa puhumisen.
- Tallenteet ennallaan - ne säilytetään edelleen 90 päivää ja ne voi kytkeä pois samalla tavalla agentin tietosivulla.
- Tieto tallennuksesta ennallaan - jos tallennuslause (`recordingNotice`) on agentille päällä, volai lisää tässäkin agentin ensimmäisen lauseen jälkeen lyhyen lauseen siitä, että puhelu tallennetaan (katso osio Tallenteet yllä). Ilman tätä vaihtoehtoa tai kun tallennus on pois päältä, lausetta ei lisätä lainkaan.
- Ilmoitus siitä, että puhuja on tekoäly ennallaan - ensimmäinen lause lähetetään palveluntarjoajalle täsmälleen sellaisena kuin se kirjoitettiin. Sitä ei pakoteta: kun ilmoitus siitä, että soittaja puhuu digitaalisen avustajan kanssa, puuttuu, annetaan vain huomautus (EU:n tekoälyasetus, art. 50), tallennusta ei pysäytetä. Ilmoituksen vastuu on asiakkaalla molempien palveluntarjoajien osalta.
- Työkalut ja puhelun yhdistäminen siirtyvät agentin mukana - onnistunut vaihto siirtää moottorille myös sen työkalut ja asetetun yhdistämisen ihmiselle, niitä ei tarvitse määrittää uudelleen. volain omalla puhemoottorilla yhdistäminen toimii sillan kautta (kuten luku Yhdistäminen ihmiselle yllä kuvaa) - silta on todennettu jatkuvassa käytössä, ja portaali näyttää moottorin agentille täydellisen yhdistämislomakkeen. Oletusalustan (ElevenLabs) agentilla käyttöön otettu yhdistäminen käynnistää heti tallennuksen jälkeen yrityksen siirtää se omalle moottorille; tarkista tulos kentästä `provider`, koska agentti voi keskeytyksen, moottorin poissaolon tai virheen vuoksi jäädä ElevenLabsiin, jolloin yhdistäminen ei siellä toimi. Onnistunut vaihto voi muuttaa äänen moottorin oletusääneksi. Numeroiden kokoava siirto erissä ohittaa siksi agentit, joilla on yhdistäminen asetettuna.
- Vastaaja lähtevissä puheluissa tunnistaa vain volain oma puhemoottori - muutaman sekunnin kuluessa vastauksesta se havaitsee ihmisen sijaan vastaajan ja asetuksesta riippuen joko vain merkitsee sen, katkaisee puhelun tai odottaa merkkiääntä ja lukee viestin. Se asetetaan agentin tietosivulla (vain moottorin agenteille), API:ssa ja MCP:ssä kentällä `voicemail`. Puhelulista näyttää lähtevälle puhelulle, johon vastasi vastaaja, ”Vastaaja vastasi” tavanomaisen lopputuloksen sijaan. Oletusalustalla (ElevenLabs) tunnistusta ei ole.
- Muistutus hiljaisuudessa toistetaan vain volain omalla puhemoottorilla - kun soittaja on pitkään hiljaa, agentti kysyy kerran, onko soittaja vielä linjalla. Asetus (päällä/pois, sekuntimäärä 3-25) tallennetaan molemmille palveluntarjoajille - oletusalustan (ElevenLabs) agentilla kenttä on himmennetty agentin tietosivulla ja arvo tulee voimaan vasta moottorille vaihdon jälkeen. Kysymykselle voi antaa oman tekstin (`silencePromptText`, enintään 80 merkkiä, oletustekstin "Oletko vielä linjalla?" tilalle), ja se tallennetaan samalla tavalla.
- Ensimmäisen lauseen suojaus osaa vain volain oma puhemoottori ja vain lähtevissä puheluissa: niin kauan kuin ensimmäistä lausetta toistetaan (annettu sekuntimäärä, 0-20), vastaajan lyhyt reaktio ("Haloo?", "Joo?") ei keskeytä sitä. Soitetun repliikki ilman keskeyttäviä sanoja (seis, ei, hetki, riittää, odota) hylätään suojatussa ikkunassa: se ei keskeytä lausetta, ei näy litteroinnissa eikä agentti reagoi siihen, kun taas keskeyttävän sanan sisältävä lause keskeytetään aina. Kenttä `firstMessageProtectSecs` tallennetaan ilman pakotettua oletusarvoa molemmille palveluntarjoajille - oletusalustan (ElevenLabs) agentilla se on himmennetty agentin tietosivulla ja tulee voimaan vasta moottorille vaihdon jälkeen. Puhelun litteroinnissa agentin repliikki, jonka soittaja keskeytti, saa sen jälkeen lipun `interrupted`.
- Agentin nauru vain volain oma puhemoottori osaa reagoida naurulla, kun soittaja tai joku muu nauraa tai vitsailee puhelussa - ja vain tšekkiläisellä Cartesia-äänellä (Milena, Jan ja muut katalogista). Oletusalusta (ElevenLabs) ei osaa nauraa lainkaan, vaikka kenttä asetettaisiin. Agentin asetuksissa valitaan Automaattinen (moottori kytkee naurun itse pois arkaluonteisissa aiheissa, esimerkiksi veloissa, terveydenhuollossa, viranomaisasioissa tai hautaustoimistoissa), Päällä (ohittaa tämän tunnistuksen) tai Pois. Muutos tulee voimaan seuraavasta puhelusta.
18Kalenteri ja ajat
Agentti volain omalla puhemoottorilla voi suoraan puhelussa selvittää vapaan ajan omasta Google- tai Apple-kalenterista ja varata tapaamisen heti - se kertoo soittajalle, onko aika vapaa, tarjoaa lähimmät vapaat ajat ja kirjaa tapaamisen vahvistetulla nimellä. Se otetaan käyttöön agenttieditorin Kalenteri-välilehdellä: valitaan yhteys (Yhteydet ja API), kulloinenkin kalenteri ja saatavuussäännöt.
- Saatavuussäännöt ikkunat viikonpäivittäin (milloin agentti ylipäätään tarjoaa aikoja), tapaamisen pituus, väli aikojen välillä, vähimmäisaika ennen sovittua aikaa ja horisontti siitä, kuinka pitkälle eteenpäin agentti hakee. Oletusarvot täyttää editori itse, mutta niitä voi säätää jokaiselle agentille erikseen.
- Sisäänrakennetut työkalut kalenteri käyttää kahta sisäänrakennettua työkalua, check_availability ja book_appointment - toisin kuin luvun Työkalut omat työkalut, niitä ei luoda käsin, ne otetaan käyttöön kalenterin mukana, eikä niitä lasketa tilin työkalurajaan.
- Vain volain oma moottori toimii yksinomaan agentilla volain omalla puhemoottorilla. Kun kalenteri otetaan käyttöön oletusalustan (ElevenLabs) agentille, asetus tallennetaan ja agentti yrittää heti tallennuksen jälkeen vaihtaa volain moottorille - samalla tavalla kuin yhdistämisessä ihmiselle.
- Mitä agentti sanoo ja mitä ei agentti ei koskaan lue ääneen, mitä kalenterissa on - vain sen, onko tietty aika vapaa. Soittajan puhelinnumero kirjataan tapahtumaan vain, jos agentti tuntee sen (piilotettu numero tuottaa tapahtuman ilman puhelinnumeroa).
- Myös puheluiden ulkopuolella sama vapaiden aikojen haku ja tapaamisen varaus onnistuu myös puheluiden ulkopuolella REST:n (POST /v1/integrations/{id}/availability, POST /v1/integrations/{id}/events) ja MCP:n (find_free_slots, create_calendar_event) kautta - yksityiskohdat ovat REST API -viitteen Kalenterit-osiossa ja MCP-viitteessä.
Liittyvää
MCP-palvelin
Yhdistä Claude Code, Codex CLI, Codex desktop, Cursor ja muut tekoälyeditorit.
REST API
Täydellinen kuvaus jokaisesta päätepisteestä: numerot, puhelut, tekstiviestit, tekstiviestien matkapuhelinnumerot, agentit ja niiden luonnokset, työkalut, tallenteet, webhookit, soittokieltolista, välitys, tili, tehtävät, saldo, asiakirjat, kalenterit ja integraatiot.
Webhookit
Tapahtumat, rakenteinen data viestin rungossa, allekirjoituksen tarkistus, uudelleenyritykset virhetilanteessa.
Tuo oma agenttisi
Yhdistä kolmannen osapuolen alusta (ElevenLabs, Asterisk...) ilman agenttilisää.