Soita asiakkaalle n8n-työnkulusta
2. syyskuuta 2026 · lukuaika 7 min
n8n:stä voi soittaa asiakkaalle ilman riviäkään koodia: lisää työnkulkuun HTTP Request -solmu, aseta se kutsumaan POST https://volai.cz/v1/calls otsakkeella Authorization: Bearer vk_... ja bodylla {to, agentId} - puheagentti soittaa numeroon täsmälleen silloin, kun työnkulku sitä tarvitsee. Alla on koko kokonaisuus: miten työnkulun tiedot yhdistetään agentin kehotteeseen, miten puhelun tulos tuodaan takaisin n8n:ään ja miten soitetaan kokonaan ilman agenttia yhdistämällä kaksi numeroa suoraan.
Tarvittavat asiat
- n8n-instanssi - pilvessä tai omassa ajossa, mikä tahansa nykyinen versio.
- volai-tili ja API-avain portaalista (Asetukset -> Käyttöoikeus ja API), muotoa
vk_.... Tallenna se n8n:ään Header Auth -tyyppisenä credentialina (otsakeAuthorization, arvoBearer vk_...), jotta avainta ei tarvitse kopioida jokaiseen solmuun erikseen. - Oma puhelinnumero ja puheagentti - luo ne portaalissa tai sivun /docs/agent ohjeella. Ilman agenttia voi silti soittaa yhdistämällä kaksi numeroa suoraan (alla oleva
from-vaihtoehto).
1Lisää HTTP Request -solmu
Metodi POST, URL https://volai.cz/v1/calls, todennus tallennetulla credentialilla, Body Content Type JSON. Bodyssa pitää olla to (asiakkaan numero) ja agentId (agentin tunnus portaalista) - molemmat ovat pakollisia, ja täsmälleen YKSI arvoista agentId/from/systemPrompt on annettava, ei koskaan useampaa yhtä aikaa.
{
"to": "={{ $json.phone }}",
"agentId": "ag_kx91fa2b",
"variables": {
"customer_name": "={{ $json.name }}",
"order_number": "={{ $json.order }}"
},
"ringingTimeoutSecs": 30
}Arvot, jotka on kirjoitettu muodossa ={{...}}, ovat n8n-lausekkeita - $json lukee kenttiä työnkulun edellisestä solmusta (esimerkiksi ”uusi tilaus” -webhookista tai taulukkolaskennan riviltä).
2Yhdistä työnkulun tiedot agentin kehotteeseen
variables on merkkijonosta merkkijonoon -tyyppinen objekti, jonka agentti saa dynaamisina muuttujina - järjestelmäkehotteessa niihin viitataan muodossa {{customer_name}}. Rajoitukset: enintään 20 avainta, avaimet enintään 64 merkkiä, arvot enintään 512 merkkiä. Nimet attempt_id, caller_number ja called_number on varattu - volai täyttää ne itse, ja työnkulun samannimiset arvot hylättäisiin.
ringingTimeoutSecs (5-60 sekuntia, oletus 25) määrää, kuinka kauan puhelin saa soida, ennen kuin vastaamaton puhelu päätetään arvolla endReason: "no_answer". Pidempi aikaraja kasvattaa mahdollisuutta, että asiakas ehtii vastata, mutta pitää myös lähtevän puhelun linjan varattuna pidempään.
3Lue vastaus ja odota tarvittaessa tulosta
Onnistunut vastaus tulee heti, mutta puhelu on silloin vasta alkanut - status on initiated, ei lopullinen tila:
{
"id": "c_9d4e2b7f",
"status": "initiated"
}Jos tulosta halutaan odottaa samassa työnkulun ajossa erillisen webhookin sijaan, lisää HTTP Request -solmun perään toinen solmu, joka kutsuu GET /v1/calls/{id} parametrilla waitSecs (0-45 sekuntia) - palvelin vastaa, kun puhelu on päättynyt tai aikaraja on täyttynyt sen mukaan, kumpi tapahtuu ensin:
curl "https://volai.cz/v1/calls/c_9d4e2b7f?waitSecs=30" \
-H "Authorization: Bearer vk_YOUR_KEY"Tulos takaisin: webhook n8n:ään
Tuotantotyönkulussa on yleensä käytännöllisempää olla odottamatta samassa ajossa ja saada tulos sen sijaan erillisenä toimituksena: lisää n8n:ään Webhook-solmu (uusi työnkulku käy hyvin), kopioi sen Production URL ja rekisteröi se kerran volaissa:
curl -X PUT https://volai.cz/v1/webhook \
-H "Authorization: Bearer vk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-instance.app.n8n.cloud/webhook/volai-calls",
"events": ["call.completed", "call.failed", "call.no_answer"]
}'Vastaus sisältää kentän secret (muotoa whsec_...) - tallenna se, sitä tarvitaan jokaisen saapuvan pyynnön allekirjoituksen todentamiseen. volai lähettää otsakkeen Volai-Signature muotoa t=<unix>,v1=<hex> - täydellinen todennuskoodi TypeScriptillä ja Pythonilla löytyy sivulta /docs/webhooky. Sitä ei voi siirtää sellaisenaan n8n:n Code-solmuun: HMAC lasketaan RAAKAPYYNNÖN rungosta, joten Webhook-solmussa on otettava käyttöön Raw Body -asetus (ilman sitä n8n antaa eteenpäin jo jäsennetyn JSONin ja allekirjoitus ei koskaan täsmää), ja crypto-moduuli on tuotava Code-solmussa komennolla require, ei komennolla import. Älä käsittele bodya ennen kuin allekirjoitus on todennettu.
Tämä saapuu, kun puhelu on valmis:
{
"event": "call.completed",
"ts": 1756111640000,
"data": {
"id": "c_9d4e2b7f",
"direction": "out",
"from": "+420601234567",
"to": "+420777123456",
"status": "completed",
"durationSecs": 90,
"priceHal": 513,
"answeredBy": "human",
"endReason": "completed",
"transcript": [
{ "role": "agent", "message": "Hei, soitan tilauksesta A-42." },
{ "role": "caller", "message": "Joo, tiedän, kiitos muistutuksesta." }
],
"summary": "Asiakas vahvisti, että tilaus A-42 on saapunut perille.",
"data": {
"order_confirmed": true
}
}
}Avain data kentän data sisällä on valinnainen ja sisältää täsmälleen ne kentät, jotka agentille on määritetty sen dataFields-asetuksessa - yllä oleva esimerkki (order_confirmed) on vain havainnollistava, omat kentät ovat toisia. Seuraava n8n-solmu voi sitten haarautua näiden kenttien perusteella, esimerkiksi päivittääkseen CRM-tietueen tai ajoittaakseen puhelun uudelleen.
Miten soitetaan ilman agenttia?
Kun puheagenttia ei tarvita, vain suora yhteys kahden numeron välillä (esimerkiksi myyjän ja asiakkaan), lähetetään from kentän agentId sijaan:
{
"to": "+420777123456",
"from": "+420601234567"
}volai soittaa ensin numeroon from, ja heti kun joku vastaa, yhdistetään to. Molemmat puhelun osuudet veloitetaan erikseen hinnalla 0,0384 € minuutilta (ilman agenttilisää). from on numero, jossa SINÄ vastaat - yleensä oma matkapuhelin - ja se voi olla mikä tahansa tšekkiläinen tai slovakialainen numero, sen ei tarvitse kuulua volai-tiliin. Todellinen vaatimus on toinen: tilillä on oltava vähintään yksi oma numero volaissa, koska puhelu veloitetaan sen kautta ja koska se on numero, joka näkyy molempien osapuolten näytöllä (ilman sitä volai palauttaa virheen bridge_needs_number). Älä vain anna kenttään from volai-numeroa, joka on ohjattu agentille tai SIP:iin - verkko yhdistäisi ensimmäisen osuuden agenttiin sinun sijastasi, eikä puhelu koskaan soisi puhelimessasi.
Mitä tällainen puhelu maksaa?
Agentin kautta tehty lähtevä puhelu veloitetaan kahden hinnan summana: lähtevä minuutti (0,0384 €) plus sen PÄÄLLE tuleva agenttilisä (0,105 €), molemmat 2. syyskuuta 2026 voimassa olevan hinnaston mukaan. 90 sekunnin puhelu maksaa siten 0,214 €:
| Erä | Hinta | Puhelu, 90 s |
|---|---|---|
| Lähtevä minuutti | 0,0384 €/min | 0,0575 € |
| Agenttilisä | 0,105 €/min | 0,157 € |
| Yhteensä | 0,214 € |
Veloitus tapahtuu sekunneittain, ei aloitetuittain minuuteittain - lyhyempi puhelu maksaa suhteessa vähemmän. Koko hinnasto (numerot, agentti, tekstiviestit) löytyy sivulta /cenik.
Turvalliset uudelleenyritykset (Idempotency-Key)
n8n voi yrittää solmua automaattisesti uudelleen virheen sattuessa (Retry On Fail) - ilman suojaa se tarkoittaisi kahta oikeaa puhelua samalle asiakkaalle. Lisää otsake Idempotency-Key arvolla, joka pysyy samana työnkulun yhden ajon ajan (n8n tarjoaa sen muodossa {{ $execution.id }}, tai käytä omaa tilaustunnusta) - samalla avaimella 24 tunnin sisällä palautuu ensimmäisen yrityksen vastaus, eikä puhelua tehdä kahdesti:
curl -X POST https://volai.cz/v1/calls \
-H "Authorization: Bearer vk_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: reminder-order-A-42" \
-d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'Mitä tehdä, kun API palauttaa virheen?
Taulukko koskee vaihtoehtoja agentId ja from - tilat, jotka ovat ominaisia ilman omaa numeroa tehtävälle testipuhelulle (systemPrompt), on tarkoituksella jätetty pois, se on eri kulku.
| Tila | Koodi | Mitä se tarkoittaa |
|---|---|---|
| 400 | invalid_number | Kenttä to ei ole kelvollinen puhelinnumero. |
| 400 | validation | agentId/from puuttuu tai molemmat on annettu; tai variables ylittää rajansa, tai ringingTimeoutSecs on välin 5-60 ulkopuolella. |
| 400 | on_dnc | Numero on soittokieltolistalla (/v1/dnc). |
| 400 | destination_auto_blocked | Kohde on toistuvien epäonnistumisten jälkeen estetty automaattisesti 30 päiväksi. |
| 400 | cannot_call_own_number | Suoja silmukoita vastaan - omaan volai-numeroon ei voi soittaa. |
| 404 | agent_not_found | agentId ei ole olemassa tai ei kuulu tilille. |
| 404 | agent_no_number | Agentille ei ole määritetty puhelinnumeroa. |
| 404 | bridge_needs_number | Vaihtoehdossa from: tilillä on oltava vähintään yksi oma numero volaissa. |
| 409 | destination_busy | Toinen puhelu samaan numeroon on jo käynnissä. |
| 402 | insufficient_credit | Saldo ei kata puhelun aloittamisen vähimmäismäärää. |
| 503 | capacity_busy | Kaikki lähtevät linjat ovat juuri nyt varattuja, yritä uudelleen minuutin kuluttua. |
Yleinen API-raja
Yllä olevan taulukon lisäksi koko API:lla on yhteinen raja: enintään 60 pyyntöä minuutissa API-avainta kohden (HTTP 429, rate_limited). Se kannattaa pitää mielessä työnkulussa, joka soittaa kymmeniin numeroihin peräkkäin - sama raja koskee kutsua POST /v1/messages ja kaikkia muita samalla avaimella käytettäviä endpointeja.
Seuraavat askeleet
Täydellinen läpikäynti siitä, mitä n8n:stä voi tehdä (tekstiviestit, numerot, soittokieltolista), löytyy n8n-integraation oppaasta. Täydellinen REST-viite on sivulla /docs/api, ja täydellinen lista webhook-tapahtumista allekirjoituksen todennuksineen löytyy sivulta /docs/webhooky.
Kokeile volaita - ensimmäiset 2 € saat meiltä
Tili luodaan minuutissa, ja aloitussaldo puheluihin ja yhteen numeroon on heti käytettävissä - tekstiviestejä voi lähettää ensimmäisen latauksen jälkeen.
Aiheeseen liittyvät artikkelit
Viisi kysymystä ennen tekoälyvastaanottovirkailijan hankintaa
Hinta, käyttöönotto 5 minuutissa, numeron siirto O2:lta, T-Mobilelta ja Vodafonelta, slovakialaiset numerot ja ALV: viisi vastausta suoraan volain hinnastosta ja asetuksista.
Tekstiviestirajapinta 10 minuutissa Node.js:llä
Näin lähetät tekstiviestejä Node.js:llä volain REST-rajapinnan kautta: yksi fetch-kutsu osoitteeseen POST /v1/messages, idempotenssi, virhetilat ja tarkka hinta viestin segmenttiä kohden.
ElevenLabs-agentti tšekkiläisellä numerolla SIP:n kautta
Vaihe vaiheelta: kytke oman työtilan ElevenLabs-agentti tšekkiläiseen volai-numeroon SIP-trunkin kautta - sekä saapuvat että lähtevät puhelut.