Ako zavolať zákazníkovi z n8n workflow

Z n8n môžete zavolať zákazníkovi bez jediného riadku kódu: do workflow pridajte uzol HTTP Request, nastavte ho na POST https://volai.cz/v1/calls s hlavičkou Authorization: Bearer vk_... a telom {to, agentId} - a váš hlasový agent vytočí číslo presne v momente, keď to workflow potrebuje. Nižšie je celý postup: ako namapovať dáta z workflow do promptu agenta, ako dostať výsledok hovoru späť do n8n a ako zavolať aj bez agenta, priamym spojením dvoch čísel.

Čo budete potrebovať

• Inštanciu n8n - cloud alebo self-hosted, na verzii nezáleží.
• Účet vo volai a API kľúč z portálu (Nastavenia -> API a MCP), v tvare vk_.... V n8n si ho uložte ako credential typu Header Auth (hlavička Authorization, hodnota Bearer vk_...) - vyhnete sa prepisovaniu kľúča do každého uzla zvlášť.
• Vlastné telefónne číslo s hlasovým agentom - založíte ho v portáli alebo cez /docs/agent. Bez agenta sa dá volať aj priamym spojením dvoch čísel (variant from nižšie).

1Pridajte uzol HTTP Request

Metóda POST, URL https://volai.cz/v1/calls, autentifikácia cez uložený credential, Body Content Type JSON. Do tela patrí to (číslo zákazníka) a agentId (ID agenta z portálu) - obe povinné, a práve JEDNO z agentId/from/systemPrompt, nikdy viac naraz.

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

Hodnoty s ={{...}} sú výrazy n8n - $json číta polia z predchádzajúceho uzla workflow (napríklad webhooku „nová objednávka“ alebo riadku z tabuľky).

2Namapujte dáta z workflow do promptu agenta

variables je objekt reťazec-reťazec, ktorý agent dostane ako dynamické premenné - vo svojom systémovom prompte sa na ne odkážete zápisom {{customer_name}}. Limity: najviac 20 kľúčov, kľúč do 64 znakov, hodnota do 512 znakov. Mená attempt_id, caller_number, called_number sú rezervované - dopĺňa ich volai samo a rovnomenné hodnoty z workflow by sa zahodili.

ringingTimeoutSecs (5 až 60 sekúnd, predvolene 25) určuje, ako dlho nechať zvoniť, kým sa nezdvihnutý hovor ukončí s endReason: "no_answer". Dlhšie zvonenie zvyšuje šancu, že to zákazník stihne zdvihnúť, ale aj dlhšie drží obsadený odchádzajúci slot.

3Prečítajte odpoveď a prípadne počkajte na výsledok

Úspešná odpoveď dorazí hneď, ale hovor sa v tej chvíli iba začína - status je initiated, nie konečný stav:

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

Ak chcete v tom istom workflow počkať na výsledok namiesto zvláštneho webhooku, pridajte hneď za uzol HTTP Request druhý, ktorý zavolá GET /v1/calls/{id} s parametrom waitSecs (0 až 45 sekúnd) - server odpovie, keď hovor skončí, alebo po uplynutí limitu, podľa toho, čo nastane skôr:

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

Výsledok späť: webhook do n8n

Pre produkčné workflow je praktickejšie nečakať na výsledok v tom istom behu, ale nechať si ho doručiť samostatne: pridajte do n8n (pokojne do nového workflow) uzol Webhook, skopírujte jeho Production URL a jednorazovo ju zaregistrujte vo 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"]
  }'

Odpoveď obsahuje secret (tvar whsec_...) - uložte si ho, budete ho potrebovať na overenie podpisu každého prichádzajúceho požiadavku. volai posiela hlavičku Volai-Signature v tvare t=<unix>,v1=<hex> - úplný overovací kód v TypeScripte aj Pythone nájdete na /docs/webhooky. Do uzla Code v n8n ho nemožno preniesť bez zmeny: HMAC sa počíta nad SUROVÝM telom požiadavku, takže na uzle Webhook musíte zapnúť voľbu Raw Body (bez nej n8n odovzdá už rozparsovaný JSON a podpis nesedí) a modul crypto importujte cez require, nie cez import. Telo nespracúvajte skôr, než podpis overíte.

Ukážka toho, čo do webhooku dorazí po skončení hovoru:

{
  "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": "Dobrý deň, volám ohľadom objednávky A-42." },
      { "role": "caller", "message": "Áno, už o tom viem, ďakujem za pripomenutie." }
    ],
    "summary": "Zákazník potvrdil prevzatie objednávky A-42.",
    "data": {
      "order_confirmed": true
    }
  }
}

Kľúč data vnútri data je voliteľný a obsahuje presne tie polia, ktoré ste agentovi nastavili v jeho dataFields - príklad vyššie (order_confirmed) je len ilustračný, vy budete mať iné. Ďalší uzol n8n potom môže podľa týchto polí rozhodnúť, či napríklad aktualizovať CRM, alebo hovor znova naplánovať.

Ako zavolať bez agenta?

Ak hlasového agenta nepotrebujete a chcete len prepojiť dve čísla (napríklad obchodníka so zákazníkom), pošlite namiesto agentId pole from:

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

volai najprv zavolá na from a hneď ako ho niekto zdvihne, vytočí to. Obe nohy hovoru sa účtujú zvlášť po 0,92 kr za minútu (bez prirážky za agenta). from je číslo, na ktorom hovor zdvihnete vy - typicky váš mobil - a môže to byť ľubovoľné české alebo slovenské číslo, pokojne mimo vášho účtu vo volai. Podmienka je iná: na účte musíte mať aspoň jedno VLASTNÉ číslo vo volai, pretože z neho sa hovor účtuje a je to číslo, ktoré sa zobrazí na displeji obom stranám (bez neho vráti volai chybu bridge_needs_number). Len si dajte pozor, aby to nebolo číslo vo volai smerované na agenta alebo na SIP - sieť by prvú nohu spojila s ním, nie s vami, a hovor by vám nikdy nedozvonil.

Koľko takýto hovor stojí?

Odchádzajúci hovor cez agenta sa účtuje ako súčet dvoch sadzieb: odchádzajúca minúta (0,92 kr) a prirážka za agenta NAVYŠE k nej (2,50 kr), obe z cenníka platného k 2. 9. 2026. Hovor dlhý jeden a pol minúty tak vyjde na 5,13 kr:

Účtuje sa po sekundách, nie po celých minútach - kratší hovor stojí pomerne menej. Presný cenník všetkých položiek (čísla, agent, SMS) je na /cenik.

Bezpečné opakovanie pri retry (Idempotency-Key)

n8n vie uzol pri chybe automaticky zopakovať (Retry On Fail) - bez poistky by to pri telefonáte znamenalo dve skutočné volania tomu istému zákazníkovi. Pridajte hlavičku Idempotency-Key so stabilnou hodnotou pre jeden beh workflow (n8n ju ponúka ako {{ $execution.id }}, alebo použite vlastné ID objednávky) - s rovnakým kľúčom do 24 hodín dostanete späť odpoveď z prvého pokusu a hovor sa nezaloží druhýkrát:

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

Čo robiť, keď API vráti chybu?

Táto tabuľka pokrýva variant s agentId a from - stavy špecifické pre skúšobný hovor bez čísla (systemPrompt) tu zámerne nie sú, rieši ich iný postup.

Čo ďalej

Kompletný prehľad toho, čo všetko sa dá z n8n zavolať (SMS, čísla, DNC), je v integrácii n8n. Plná REST referencia je na /docs/api, úplný popis udalostí webhooku a overenia podpisu na /docs/webhooky.

Čo ďalej