Siirry sisältöön

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 (otsake Authorization, arvo Bearer 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.

json
{
  "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:

json
{
  "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:

bash
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:

bash
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:

json
{
  "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:

json
{
  "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äHintaPuhelu, 90 s
Lähtevä minuutti0,0384 €/min0,0575 €
Agenttilisä0,105 €/min0,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:

bash
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.

TilaKoodiMitä se tarkoittaa
400invalid_numberKenttä to ei ole kelvollinen puhelinnumero.
400validationagentId/from puuttuu tai molemmat on annettu; tai variables ylittää rajansa, tai ringingTimeoutSecs on välin 5-60 ulkopuolella.
400on_dncNumero on soittokieltolistalla (/v1/dnc).
400destination_auto_blockedKohde on toistuvien epäonnistumisten jälkeen estetty automaattisesti 30 päiväksi.
400cannot_call_own_numberSuoja silmukoita vastaan - omaan volai-numeroon ei voi soittaa.
404agent_not_foundagentId ei ole olemassa tai ei kuulu tilille.
404agent_no_numberAgentille ei ole määritetty puhelinnumeroa.
404bridge_needs_numberVaihtoehdossa from: tilillä on oltava vähintään yksi oma numero volaissa.
409destination_busyToinen puhelu samaan numeroon on jo käynnissä.
402insufficient_creditSaldo ei kata puhelun aloittamisen vähimmäismäärää.
503capacity_busyKaikki 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.

Kokeile ilmaiseksi