Jak zavolat zákazníkovi z n8n workflow

Z n8n zavoláš zákazníkovi bez jediného řádku kódu: do workflow přidej uzel HTTP Request, nastav ho na POST https://volai.cz/v1/calls s hlavičkou Authorization: Bearer vk_... a tělem {to, agentId} - a tvůj hlasový agent vytočí číslo přesně v momentě, kdy to workflow potřebuje. Níž je celý postup: jak namapovat data z workflow do promptu agenta, jak dostat výsledek hovoru zpátky do n8n a jak zavolat i bez agenta, přímým spojením dvou čísel.

Co budeš potřebovat

• Instanci n8n - cloud nebo self-hosted, na verzi nezáleží.
• Účet na volai a API klíč z portálu (Nastavení -> API a MCP), ve tvaru vk_.... V n8n si ho ulož jako credential typu Header Auth (hlavička Authorization, hodnota Bearer vk_...) - vyhneš se opisování klíče do každého uzlu zvlášť.
• Vlastní telefonní číslo s hlasovým agentem - založíš ho v portálu nebo přes /docs/agent. Bez agenta jde volat i přímým spojením dvou čísel (varianta from níž).

1Přidej HTTP Request node

Metoda POST, URL https://volai.cz/v1/calls, autentizace přes uložený credential, Body Content Type JSON. Do těla patří to (číslo zákazníka) a agentId (ID agenta z portálu) - obojí povinné, a právě JEDNO z agentId/from/systemPrompt, nikdy víc naráz.

{
  "to": "={{ $json.telefon }}",
  "agentId": "ag_kx91fa2b",
  "variables": {
    "jmeno_zakaznika": "={{ $json.jmeno }}",
    "cislo_objednavky": "={{ $json.objednavka }}"
  },
  "ringingTimeoutSecs": 30
}

Hodnoty s ={{...}} jsou n8n výrazy - $json čte pole z předchozího uzlu workflow (třeba webhooku „nová objednávka“ nebo řádku z tabulky).

2Namapuj data z workflow do promptu agenta

variables je objekt řetězec-řetězec, který agent dostane jako dynamické proměnné - ve svém systémovém promptu se na ně odkážeš zápisem {{jmeno_zakaznika}}. Limity: nejvýš 20 klíčů, klíč do 64 znaků, hodnota do 512 znaků. Jména attempt_id, caller_number, called_number jsou rezervovaná - doplňuje je volai samo a stejnojmenné hodnoty z workflow by se zahodily.

ringingTimeoutSecs (5 až 60 vteřin, výchozí 25) určuje, jak dlouho nechat vyzvánět, než se nezvednutý hovor ukončí s endReason: "no_answer". Delší vyzvánění zvedne šanci, že to zákazník stihne zvednout, ale taky déle drží obsazený odchozí slot.

3Přečti odpověď a případně počkej na výsledek

Úspěšná odpověď dorazí hned, ale hovor v tu chvíli teprve začíná - status je initiated, ne konečný stav:

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

Chceš-li v témže workflow počkat na výsledek místo zvláštního webhooku, přidej hned za HTTP Request node druhý, který zavolá GET /v1/calls/{id} s parametrem waitSecs (0 až 45 vteřin) - server odpoví, až hovor skončí, nebo po uplynutí limitu, podle toho, co nastane dřív:

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

Dostat výsledek zpátky: webhook do n8n

Pro produkční workflow je praktičtější nečekat na výsledek ve stejném běhu, ale nechat si ho doručit samostatně: přidej do n8n (klidně do nového workflow) uzel Webhook, zkopíruj jeho Production URL a jednorázově ho zaregistruj u volai:

curl -X PUT https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tvoje-instance.app.n8n.cloud/webhook/volai-hovory",
    "events": ["call.completed", "call.failed", "call.no_answer"]
  }'

Odpověď obsahuje secret (tvar whsec_...) - ulož si ho, budeš ho potřebovat k ověření podpisu každého došlého požadavku. Volai posílá hlavičku Volai-Signature ve tvaru t=<unix>,v1=<hex> - úplný ověřovací kód v TypeScriptu i Pythonu najdeš na /docs/webhooky. Do n8n Code node ho nelze přenést beze změny: HMAC se počítá nad SYROVÝM tělem požadavku, takže na Webhook node musíš zapnout volbu Raw Body (bez ní n8n předá už rozparsovaný JSON a podpis nesedne) a modul crypto importuj přes require, ne import. Tělo nezpracovávej dřív, než podpis ověříš.

Ukázka toho, co 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ý den, volám ohledně objednávky A-42." },
      { "role": "caller", "message": "Ano, už o tom vím, díky za připomenutí." }
    ],
    "summary": "Zákazník potvrdil převzetí objednávky A-42.",
    "data": {
      "objednavka_potvrzena": true
    }
  }
}

Klíč data uvnitř data je volitelný a obsahuje přesně ta pole, která sis pro agenta nastavil v jeho dataFields - příklad výš (objednavka_potvrzena) je jen ilustrační, u tebe budou jiná. Další n8n uzel pak může podle těchhle polí rozhodnout, jestli třeba aktualizovat CRM, nebo hovor znovu naplánovat.

Jak zavolat bez agenta?

Když nepotřebuješ hlasového agenta, jen propojit dvě čísla (třeba obchodníka se zákazníkem), pošli místo agentId pole from:

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

volai nejdřív zavolá na from, a jakmile ho někdo zvedne, vytočí to. Obě nohy hovoru se účtují zvlášť po 0,92 Kč za minutu (bez agentní přirážky). from je číslo, na kterém hovor zvedneš ty - typicky tvůj mobil - a je to libovolné české nebo slovenské číslo, klidně mimo tvůj volai účet. Podmínka je jiná: na účtu musíš mít aspoň jedno VLASTNÍ volai číslo, protože z něj se hovor účtuje a je to číslo, které se zobrazí na displeji oběma stranám (bez něj vrátí volai chybu bridge_needs_number). Jen si dej pozor, aby to nebylo volai číslo směrované na agenta nebo na SIP - Odorik by první nohu spojil s ním, ne s tebou, a hovor by ti nikdy nedozvonil.

Kolik takový hovor stojí?

Odchozí hovor přes agenta se účtuje jako součet dvou sazeb: odchozí minuta (0,92 Kč) a agentní přirážka NAVÍC k ní (2,50 Kč), obě z ceníku platného k 2. 9. 2026. Půldruhé minuty dlouhý hovor tak vyjde na 5,13 Kč:

Účtuje se po vteřinách, ne po celých minutách - kratší hovor stojí poměrně míň. Přesný ceník všech položek (čísla, agent, SMS) je na /cenik.

Bezpečné opakování při retry (Idempotency-Key)

n8n umí uzel při chybě automaticky zopakovat (Retry On Fail) - bez pojistky by to u telefonátu znamenalo dvě reálná volání téhož zákazníka. Přidej hlavičku Idempotency-Key se stabilní hodnotou pro jeden běh workflow (n8n ji nabízí jako {{ $execution.id }}, nebo použij vlastní ID objednávky) - se stejným klíčem do 24 hodin dostaneš zpátky odpověď z prvního pokusu a hovor se nezaloží podruhé:

curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pripomenuti-objednavky-A-42" \
  -d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'

Co dělat, když API vrátí chybu?

Tahle tabulka pokrývá agentId a from variantu - stavy specifické pro zkušební hovor bez čísla (systemPrompt) tu záměrně nejsou, řeší je jiný postup.

Co dál

Kompletní přehled toho, co všechno jde z n8n zavolat (SMS, čísla, DNC) je v integraci n8n. Plná REST reference je na /docs/api, úplný popis webhookových událostí a ověření podpisu na /docs/webhooky.

Co dál