Kako poklicati stranko iz delovnega toka n8n

Stranko lahko iz n8n pokličete brez ene same vrstice kode: v delovni tok dodajte vozlišče HTTP Request, ga usmerite na POST https://volai.cz/v1/calls z glavo Authorization: Bearer vk_... in telesom {to, agentId} - in vaš glasovni agent bo poklical številko natanko takrat, ko ga delovni tok potrebuje. Spodaj je celoten postopek: kako podatke iz delovnega toka preslikati v poziv agenta, kako rezultat klica vrniti v n8n in kako poklicati tudi brez agenta, z neposredno povezavo dveh številk.

Kaj boste potrebovali

• Instanco n8n - v oblaku ali na lastnem strežniku, katera koli novejša različica.
• Račun pri volai in API ključ iz portala (Nastavitve -> API in MCP) v obliki vk_.... V n8n ga shranite kot poverilnico tipa Header Auth (glava Authorization, vrednost Bearer vk_...), da ključa ni treba prepisovati v vsako vozlišče posebej.
• Lastno telefonsko številko z glasovnim agentom - ustvarite ga v portalu ali prek strani /docs/agent. Še nimate agenta? Še vedno lahko kličete z neposredno povezavo dveh številk (različica from spodaj).

1Dodajte vozlišče HTTP Request

Metoda POST, URL https://volai.cz/v1/calls, overitev prek shranjene poverilnice, Body Content Type JSON. V telo sodita to (številka stranke) in agentId (ID agenta iz portala) - obe sta obvezni, poleg tega pa natanko ENO od polj agentId/from/systemPrompt, nikoli več hkrati.

{
  "to": "={{ $json.phone }}",
  "agentId": "ag_kx91fa2b",
  "variables": {
    "customer_name": "={{ $json.name }}",
    "order_number": "={{ $json.order }}"
  },
  "ringingTimeoutSecs": 30
}

Vrednosti, zapisane kot ={{...}}, so izrazi n8n - $json prebere polja iz prejšnjega vozlišča v delovnem toku (na primer iz webhooka »novo naročilo« ali vrstice iz preglednice).

2Podatke iz delovnega toka preslikajte v poziv agenta

variables je objekt iz parov niz-niz, ki ga agent prejme kot dinamične spremenljivke - v sistemskem pozivu se nanje sklicujete z {{customer_name}}. Omejitve: največ 20 ključev, ključi do 64 znakov, vrednosti do 512 znakov. Imena attempt_id, caller_number in called_number so rezervirana - volai jih izpolni sam, enako poimenovane vrednosti iz vašega delovnega toka pa bi bile zavržene.

ringingTimeoutSecs (od 5 do 60 sekund, privzeto 25) določa, kako dolgo naj telefon zvoni, preden se klic brez odgovora konča z endReason: "no_answer". Daljše zvonjenje poveča možnost, da stranka dvigne, vendar tudi dlje zaseda odhodno linijo.

3Preberite odgovor in po potrebi počakajte na rezultat

Uspešen odgovor prispe takoj, a klic se je takrat šele začel - status je initiated, ne končno stanje:

{
  "id": "c_9d4e2b7f",
  "status": "initiated"
}

Želite na izid počakati v istem zagonu delovnega toka namesto prek ločenega webhooka? Takoj za vozlišče HTTP Request dodajte drugo, ki pokliče GET /v1/calls/{id} s parametrom waitSecs (od 0 do 45 sekund) - strežnik odgovori, ko se klic konča ali ko poteče omejitev, karkoli nastopi prej:

curl "https://volai.cz/v1/calls/c_9d4e2b7f?waitSecs=30" \
  -H "Authorization: Bearer vk_YOUR_KEY"

Vrnitev rezultata: webhook v n8n

Pri produkcijskem delovnem toku je običajno bolj praktično, da ne čakate sproti, ampak rezultat prejmete ločeno: v n8n dodajte vozlišče Webhook (primeren je tudi nov delovni tok), kopirajte njegov Production URL in ga enkrat registrirajte pri volai:

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"]
  }'

Odgovor vsebuje secret (oblike whsec_...) - shranite ga, potrebovali ga boste za preverjanje podpisa vsakega prispelega zahtevka. volai pošilja glavo Volai-Signature v obliki t=<unix>,v1=<hex> - celotna koda za preverjanje v TypeScriptu in Pythonu je na strani /docs/webhooky. V vozlišče Code v n8n je ni mogoče prenesti nespremenjene: HMAC se izračuna nad IZVORNIM telesom zahtevka, zato morate na vozlišču Webhook vklopiti možnost Raw Body (brez nje n8n preda že razčlenjen JSON in podpis se ne ujema), modul crypto pa v vozlišču Code uvozite z require, ne z import. Telesa ne obdelujte, preden preverite podpis.

Kaj prispe, ko se klic konča:

{
  "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": "Dober dan, kličem glede naročila A-42." },
      { "role": "caller", "message": "Ja, že vem, hvala za opomnik." }
    ],
    "summary": "Stranka je potrdila prejem naročila A-42.",
    "data": {
      "order_confirmed": true
    }
  }
}

Ključ data znotraj data je neobvezen in vsebuje natanko tista polja, ki ste jih agentu nastavili v njegovem dataFields - zgornji primer (order_confirmed) je le ponazoritev, pri vas bodo polja drugačna. Naslednje vozlišče n8n se nato lahko na podlagi teh polj odloči, ali bo na primer posodobilo CRM ali klic znova načrtovalo.

Kako poklicati brez agenta?

Če glasovnega agenta ne potrebujete, ampak le neposredno povezavo dveh številk (na primer prodajalca in stranke), namesto agentId pošljite polje from:

{
  "to": "+420777123456",
  "from": "+420601234567"
}

volai najprej pokliče from, ko nekdo dvigne, pa še to. Oba kraka klica se zaračunata ločeno po 0,92 kr na minuto (brez pribitka za agenta). from je številka, na kateri dvignete VI - običajno vaš mobilni telefon - in je lahko katera koli češka ali slovaška številka, ni nujno, da je v vašem računu pri volai. Prava zahteva je drugačna: v računu morate imeti vsaj eno LASTNO številko volai, ker se klic zaračuna prek nje in ker je to številka, ki se obema stranema prikaže na zaslonu (brez nje volai vrne napako bridge_needs_number). Le pazite, da v from ne vpišete številke volai, usmerjene na agenta ali na SIP - omrežje bi prvi krak povezalo z njo namesto z vami in klic vašega telefona nikoli ne bi zazvonil.

Koliko stane takšen klic?

Odhodni klic prek agenta se zaračuna kot vsota dveh cen: odhodna minuta (0,92 kr) in pribitek za agenta NAD tem (2,50 kr), obe po ceniku, veljavnem od 2. 9. 2026. Klic, dolg 90 sekund, tako stane 5,13 kr:

Zaračunava se po sekundah, ne po celih minutah - krajši klic stane sorazmerno manj. Celoten cenik vseh postavk (številke, agent, SMS) je na strani /cenik.

Varno ponavljanje zahtevkov (Idempotency-Key)

n8n zna vozlišče ob napaki samodejno ponoviti (Retry On Fail) - brez zaščite bi to pri telefonskem klicu pomenilo dva resnična klica isti stranki. Dodajte glavo Idempotency-Key s stabilno vrednostjo za en zagon delovnega toka (n8n jo ponuja kot {{ $execution.id }}, lahko pa uporabite tudi lasten ID naročila) - z istim ključem v 24 urah dobite nazaj odgovor prvega poskusa, klic pa se ne ustvari drugič:

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"}'

Kaj storiti, ko API vrne napako?

Ta tabela zajema različici agentId in from - stanja, značilna za preizkusni klic brez lastne številke (systemPrompt), so namenoma izpuščena, to je drug postopek.

Kaj sledi

Celoten pregled tega, kar lahko iz n8n sprožite (SMS, številke, seznam za nekličenje), je v vodniku za integracijo n8n. Polna referenca REST je na /docs/api, popoln seznam dogodkov webhooka s preverjanjem podpisa pa na /docs/webhooky.

Kaj naprej