Kuidas helistada kliendile n8n töövoost

Kliendile saab n8n-ist helistada ilma ühegi koodireata: lisage oma töövoole HTTP Request node, suunake see aadressile POST https://volai.cz/v1/calls koos päisega Authorization: Bearer vk_... ja kehaga {to, agentId} - ja teie häälagent valib numbri täpselt siis, kui töövoog seda nõuab. Allpool on täielik seadistus: töövoo andmete toomine agendi viipa, kõne tulemuse toomine tagasi n8n-i ja helistamine päris ilma agendita, ühendades omavahel otse kaks numbrit.

Mida vajate

• n8n-i eksemplar - pilves või ise majutatud, mis tahes tänapäevane versioon.
• volai konto ja portaalist saadud API-võti (seaded -> API ja MCP) kujul vk_.... Salvestage see n8n-is Header Auth volituseks (päis Authorization, väärtus Bearer vk_...), et te ei peaks võtit igasse node'i kopeerima.
• Oma number, millele on määratud häälagent - looge see portaalis või lehe /docs/agent kaudu. Agenti veel pole? Helistada saab ikkagi, ühendades omavahel otse kaks numbrit (allpool kirjeldatud variant väljaga from).

1Lisage HTTP Request node

Meetod POST, URL https://volai.cz/v1/calls, autentimine teie salvestatud volituste kaudu, Body Content Type JSON. Keha vajab välja to (kliendi number) ja välja agentId (agendi ID portaalist) - mõlemad on kohustuslikud, täpselt ÜKS väljadest agentId/from/systemPrompt, mitte kunagi rohkem kui üks.

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

Väärtused kujul ={{...}} on n8n-i avaldised - $json loeb välju töövoo eelmisest node'ist (näiteks webhookist „uus tellimus“ või tabelirealt).

2Tooge töövoo andmed agendi viipa

variables on objekt stringist stringiks, mille agent saab dünaamiliste muutujatena - oma süsteemiviibas viitate neile kujul {{customer_name}}. Piirangud: kuni 20 võtit, võti kuni 64 märki, väärtus kuni 512 märki. Nimed attempt_id, caller_number ja called_number on reserveeritud - volai täidab need ise ja samanimelised väärtused teie töövoost visatakse kõrvale.

ringingTimeoutSecs (5 kuni 60 sekundit, vaikimisi 25) määrab, kui kaua telefon tohib heliseda, enne kui vastamata kõne lõpeb tulemusega endReason: "no_answer". Pikem ooteaeg suurendab võimalust, et klient vastab, kuid hoiab ka kauem kinni ühte väljamineva kõne liini.

3Lugege vastust ja soovi korral oodake tulemust

Eduka päringu vastus tuleb kohe, kuid kõne on alles alanud - status on initiated, mitte lõppolek:

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

Soovite tulemust oodata samas töövoo käivituses, mitte eraldi webhooki kaudu? Lisage kohe pärast HTTP Request node'i teine node, mis kutsub välja GET /v1/calls/{id} parameetriga waitSecs (0 kuni 45 sekundit) - server vastab niipea, kui kõne lõpeb või ooteaeg saab täis, olenevalt sellest, kumb saabub enne:

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

Tulemuse toomine tagasi: webhook n8n-i

Tootmises töötava töövoo jaoks on tavaliselt mugavam mitte oodata otse, vaid lasta tulemus eraldi kohale toimetada: lisage n8n-is Webhook node (piisab uuest töövoost), kopeerige selle Production URL ja registreerige see ühe korra volais:

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

Vastus sisaldab võtit secret (kujul whsec_...) - salvestage see, vajate seda iga sissetuleva päringu allkirja kontrollimiseks. volai saadab päise Volai-Signature kujul t=<unix>,v1=<hex> - täieliku kontrollkoodi TypeScriptis ja Pythonis leiate lehelt /docs/webhooky. Seda ei saa muutmata kujul n8n-i Code node'i üle võtta: HMAC arvutatakse TÖÖTLEMATA päringu keha põhjal, seega tuleb Webhook node'is sisse lülitada valik Raw Body (ilma selleta annab n8n juba parsitud JSON-i ja allkiri ei klapi kunagi), ning Code node'is importige crypto käsuga require, mitte import. Ärge keha töödelge enne, kui olete allkirja kontrollinud.

Kõne lõppedes jõuab kohale järgmine:

{
  "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": "Tere, helistan tellimuse A-42 pärast." },
      { "role": "caller", "message": "Jah, ma juba tean, aitäh meeldetuletuse eest." }
    ],
    "summary": "Klient kinnitas tellimuse A-42 kättesaamist.",
    "data": {
      "order_confirmed": true
    }
  }
}

Võti data objekti data sees on valikuline ja sisaldab täpselt neid välju, mille olete agendi juures tema dataFields all seadistanud - ülaltoodud näide (order_confirmed) on ainult illustratsiooniks, teie väljad kannavad teisi nimesid. Järgmine n8n-i node saab nende väljade põhjal hargneda, näiteks uuendada CRM-kirjet või kõne uuesti planeerida.

Kuidas helistada ilma agendita?

Kui häälagenti pole vaja, vaid ainult otseühendust kahe numbri vahel (näiteks müügiesindaja ja kliendi vahel), saatke agentId asemel from:

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

volai helistab esmalt numbrile from ja niipea, kui keegi vastab, valib numbri to. Mõlemat kõneosa arveldatakse eraldi hinnaga 0,92 kr minuti kohta (ilma agendi lisatasuta). from on number, millel TEIE vastate - tavaliselt teie mobiil - ja see võib olla mis tahes Tšehhi või Slovakkia number, see ei pea kuuluma teie volai kontole. Tegelik eeltingimus on teine: teie kontol peab olema vähemalt üks oma volai number, sest selle kaudu kõne arveldatakse ja seda näevad kuvalt mõlemad pooled (ilma selleta tagastab volai bridge_needs_number). Ärge ainult kirjutage väljale from volai numbrit, mis on suunatud agendile või SIP-ile - võrk ühendaks selle esimese kõneosa teie asemel agendiga ja teie telefon ei heliseks kunagi.

Kui palju selline kõne maksab?

Agendi kaudu tehtav väljaminev kõne arveldatakse kahe tariifi summana: väljaminev minut (0,92 kr) pluss agendi lisatasu PEALE (2,50 kr), mõlemad 2. septembri 2026 hinnakirja järgi. 90-sekundiline kõne maksab 5,13 kr:

Arveldatakse sekundi täpsusega, mitte alustatud minuti kaupa - lühem kõne maksab vastavalt vähem. Täielik hinnakiri (numbrid, agent, SMS) on lehel /cenik.

Turvaline kordamine (Idempotency-Key)

n8n saab vea korral node'i automaatselt kordada (Retry On Fail) - ilma kaitseta tähendaks see kahte päris kõnet samale kliendile. Lisage päis Idempotency-Key väärtusega, mis jääb ühe töövoo käivituse jooksul samaks (n8n pakub selleks muutujat {{ $execution.id }} või kasutage oma tellimuse ID-d) - sama võtmega saate 24 tunni jooksul tagasi esimese katse vastuse ja kõnet ei käivitata topelt:

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

Mida teha, kui API tagastab vea?

See tabel katab variandid agentId ja from - olekud, mis kehtivad ainult proovikõne puhul ilma oma numbrita (systemPrompt), on tahtlikult välja jäetud, see on teine kulg.

Mis edasi

Täieliku ülevaate sellest, mida n8n-ist teha saab (SMS, numbrid, mittehelistamise nimekiri), leiate n8n-i integratsiooni juhendist. Täielik REST-viide on lehel /docs/api, webhooki sündmuste täielik loend koos allkirja kontrolliga lehel /docs/webhooky.

Mis edasi