Kako nazvati klijenta iz n8n workflowa

Iz n8n-a možete nazvati klijenta bez ijednog retka koda: u workflow dodajte čvor HTTP Request, postavite ga na POST https://volai.cz/v1/calls sa zaglavljem Authorization: Bearer vk_... i tijelom {to, agentId} - i vaš glasovni agent birat će broj točno u trenutku kad ga workflow zatreba. U nastavku je cijeli postupak: kako podatke iz workflowa preslikati u prompt agenta, kako rezultat poziva vratiti u n8n i kako nazvati i bez agenta, izravnim spajanjem dvaju brojeva.

Što će vam trebati

• Instancu n8n-a - cloud ili self-hosted, verzija nije važna.
• Račun u volai i API ključ iz portala (Postavke -> API i MCP), u obliku vk_.... U n8n-u ga spremite kao credential tipa Header Auth (zaglavlje Authorization, vrijednost Bearer vk_...) - tako izbjegavate prepisivanje ključa u svaki čvor zasebno.
• Vlastiti telefonski broj s glasovnim agentom - izrađuje se u portalu ili preko /docs/agent. Bez agenta se može nazvati i izravnim spajanjem dvaju brojeva (varijanta from u nastavku).

1Dodajte čvor HTTP Request

Metoda POST, URL https://volai.cz/v1/calls, autentifikacija preko spremljenog credentiala, Body Content Type JSON. U tijelo idu to (klijentov broj) i agentId (ID agenta iz portala) - oba obavezna, a točno JEDNO od agentId/from/systemPrompt, nikad više njih odjednom.

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

Vrijednosti s ={{...}} n8n su izrazi - $json čita polja iz prethodnog čvora workflowa (na primjer webhooka „nova narudžba“ ili retka iz tablice).

2Preslikajte podatke iz workflowa u prompt agenta

variables je objekt niz-niz koji agent dobiva kao dinamičke varijable - u svojem sistemskom promptu na njih se pozivate zapisom {{customer_name}}. Ograničenja: najviše 20 ključeva, ključ do 64 znaka, vrijednost do 512 znakova. Nazivi attempt_id, caller_number, called_number rezervirani su - dodaje ih volai sam, a istoimene vrijednosti iz workflowa bile bi odbačene.

ringingTimeoutSecs (5 do 60 sekundi, zadano 25) određuje koliko dugo pustiti da zvoni prije nego što se poziv bez odgovora završi s endReason: "no_answer". Dulje zvonjenje povećava šansu da klijent stigne podići slušalicu, ali i dulje drži zauzet odlazni slot.

3Pročitajte odgovor i po potrebi pričekajte rezultat

Uspješan odgovor stiže odmah, ali poziv se u tom trenutku tek započinje - status je initiated, a ne konačno stanje:

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

Ako u istom workflowu želite pričekati rezultat umjesto zasebnog webhooka, odmah iza čvora HTTP Request dodajte drugi koji poziva GET /v1/calls/{id} s parametrom waitSecs (0 do 45 sekundi) - poslužitelj odgovara kad poziv završi ili kad istekne ograničenje, što god nastupi prije:

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

Rezultat natrag: webhook u n8n

Za produkcijske workflowe praktičnije je ne čekati rezultat u istom izvršavanju, nego ga dobiti zasebno: u n8n (slobodno i u novi workflow) dodajte čvor Webhook, kopirajte njegov Production URL i jednokratno ga registrirajte u 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 sadrži secret (oblika whsec_...) - spremite ga, trebat će vam za provjeru potpisa svakog dolaznog zahtjeva. volai šalje zaglavlje Volai-Signature u obliku t=<unix>,v1=<hex> - potpuni kod za provjeru u TypeScriptu i Pythonu nalazi se na /docs/webhooky. U čvor Code u n8n-u ne može se prenijeti bez izmjene: HMAC se računa nad IZVORNIM tijelom zahtjeva, pa na čvoru Webhook morate uključiti opciju Raw Body (bez nje n8n predaje već parsirani JSON i potpis se ne poklapa), a modul crypto uvezite preko require, a ne preko import. Tijelo ne obrađujte prije nego što potpis provjerite.

Primjer onoga što u webhook stiže nakon završetka poziva:

{
  "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": "Dobar dan, zovem u vezi narudžbe A-42." },
      { "role": "caller", "message": "Da, već znam, hvala na podsjetniku." }
    ],
    "summary": "Klijent je potvrdio preuzimanje narudžbe A-42.",
    "data": {
      "order_confirmed": true
    }
  }
}

Ključ data unutar data nije obavezan i sadrži točno ona polja koja ste agentu postavili u njegovu dataFields - gornji primjer (order_confirmed) samo je ilustrativan, vi ćete imati druga. Sljedeći čvor n8n-a prema tim poljima može odlučiti hoće li, na primjer, ažurirati CRM ili poziv ponovno zakazati.

Kako nazvati bez agenta?

Ako vam glasovni agent nije potreban i želite samo spojiti dva broja (na primjer prodavača s klijentom), umjesto agentId pošaljite polje from:

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

volai prvo nazove from i čim se netko javi, bira to. Obje noge poziva naplaćuju se zasebno po 0,92 kr po minuti (bez agentove dodatne naknade). from je broj na kojem poziv primate vi - obično vaš mobitel - i može biti bilo koji češki ili slovački broj, slobodno i izvan vašeg računa u volai. Uvjet je drugi: na računu morate imati barem jedan VLASTITI broj u volai, jer se poziv naplaćuje s njega i to je broj koji se prikazuje na zaslonu objema stranama (bez njega volai vraća grešku bridge_needs_number). Samo pazite da to nije broj u volai usmjeren na agenta ili na SIP - mreža bi prvu nogu spojila s njim, a ne s vama, i poziv vam nikad ne bi stigao do kraja zvonjenja.

Koliko takav poziv košta?

Odlazni poziv preko agenta naplaćuje se kao zbroj dviju cijena: odlazna minuta (0,92 kr) i agentova dodatna naknada UZ nju (2,50 kr), obje iz cjenika važećeg na dan 2. 9. 2026. Poziv dug minutu i pol tako izlazi na 5,13 kr:

Naplaćuje se po sekundi, a ne po cijelim minutama - kraći poziv razmjerno manje košta. Točan cjenik svih stavki (brojevi, agent, SMS) nalazi se na /cenik.

Sigurno ponavljanje pri retryju (Idempotency-Key)

n8n može čvor u slučaju greške automatski ponoviti (Retry On Fail) - bez osigurača bi to kod telefonskog poziva značilo dva stvarna poziva istom klijentu. Dodajte zaglavlje Idempotency-Key sa stabilnom vrijednošću za jedno izvršavanje workflowa (n8n je nudi kao {{ $execution.id }}, ili upotrijebite vlastiti ID narudžbe) - s istim ključem unutar 24 sata dobit ćete natrag odgovor prvog pokušaja i poziv se neće otvoriti drugi put:

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

Što učiniti kad API vrati grešku?

Ova tablica pokriva varijantu s agentId i from - stanja specifična za probni poziv bez broja (systemPrompt) ovdje namjerno nisu, njih rješava drugi postupak.

Što dalje

Potpun pregled svega što se iz n8n-a može pozvati (SMS, brojevi, DNC) nalazi se u integraciji n8n. Puna REST referenca je na /docs/api, a potpuni opis događaja webhooka i provjere potpisa na /docs/webhooky.

Što dalje