Kā zvanīt klientam no n8n darbplūsmas

Klientam no n8n var zvanīt bez neviena koda rindas: pievienojiet savai darbplūsmai HTTP Request mezglu, norādiet to uz POST https://volai.cz/v1/calls ar galveni Authorization: Bearer vk_... un pieprasījuma pamatu {to, agentId} - un jūsu balss aģents sastādīs numuru tieši tad, kad to pieprasīs darbplūsma. Tālāk ir pilns iestatījums: kā darbplūsmas datus iedot aģenta promptam, kā zvana rezultātu atgriezt n8n un kā zvanīt vispār bez aģenta, tieši savienojot divus numurus.

Kas jums būs nepieciešams

• n8n instance - mākonī vai pašu hostēta, jebkura mūsdienīga versija.
• volai konts un no portāla iegūta API atslēga (iestatījumi -> API un MCP) formā vk_.... Saglabājiet to n8n kā Header Auth akreditācijas datus (galvene Authorization, vērtība Bearer vk_...), lai atslēga nebūtu jākopē katrā mezglā.
• Savs numurs, kuram piešķirts balss aģents - izveidojiet to portālā vai caur lapu /docs/agent. Aģenta vēl nav? Zvanīt tik un tā var, tieši savienojot divus numurus (tālāk aprakstītais variants ar lauku from).

1Pievienojiet HTTP Request mezglu

Metode POST, URL https://volai.cz/v1/calls, autentifikācija ar jūsu saglabātajiem akreditācijas datiem, Body Content Type JSON. Pamatā nepieciešams lauks to (klienta numurs) un lauks agentId (aģenta ID no portāla) - abi ir obligāti, un tieši VIENS no laukiem agentId/from/systemPrompt, nekad ne vairāk kā viens.

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

Vērtības formā ={{...}} ir n8n izteiksmes - $json nolasa laukus no darbplūsmas iepriekšējā mezgla (piemēram, no webhook "jauns pasūtījums" vai tabulas rindas).

2Iedodiet darbplūsmas datus aģenta promptam

variables ir objekts no virknes uz virkni, ko aģents saņem kā dinamiskus mainīgos - savā sistēmas promptā uz tiem atsaucaties formā {{customer_name}}. Ierobežojumi: līdz 20 atslēgām, atslēga līdz 64 rakstzīmēm, vērtība līdz 512 rakstzīmēm. Nosaukumi attempt_id, caller_number un called_number ir rezervēti - volai tos aizpilda pats, un tāda paša nosaukuma vērtības no jūsu darbplūsmas tiek izmestas.

ringingTimeoutSecs (no 5 līdz 60 sekundēm, pēc noklusējuma 25) nosaka, cik ilgi tālrunim drīkst zvanīt, pirms neatbildēts zvans beidzas ar rezultātu endReason: "no_answer". Ilgāks gaidīšanas laiks palielina iespēju, ka klients atbildēs, bet arī ilgāk aizņem vienu izejošo zvanu līniju.

3Nolasiet atbildi un, ja vajag, nogaidiet rezultātu

Veiksmīga pieprasījuma atbilde nāk uzreiz, taču zvans tikko sācies - status ir initiated, nevis gala stāvoklis:

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

Vēlaties rezultātu nogaidīt tajā pašā darbplūsmas izpildē, nevis caur atsevišķu webhook? Tūlīt aiz HTTP Request mezgla pievienojiet otru mezglu, kas izsauc GET /v1/calls/{id} ar parametru waitSecs (no 0 līdz 45 sekundēm) - serveris atbild, tiklīdz zvans beidzas vai gaidīšanas laiks ir beidzies, atkarībā no tā, kas notiek agrāk:

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

Rezultāta atgriešana: webhook uz n8n

Produkcijā strādājošai darbplūsmai parasti ērtāk ir negaidīt uz vietas, bet ļaut rezultātu piegādāt atsevišķi: pievienojiet n8n Webhook mezglu (pietiek ar jaunu darbplūsmu), nokopējiet tā Production URL un vienu reizi reģistrējiet to 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"]
  }'

Atbilde satur atslēgu secret (formā whsec_...) - saglabājiet to, tā būs vajadzīga katra ienākošā pieprasījuma paraksta pārbaudei. volai sūta galveni Volai-Signature formā t=<unix>,v1=<hex> - pilnu pārbaudes kodu TypeScript un Python valodā atradīsiet lapā /docs/webhooky. To nevar pārņemt n8n Code mezglā bez izmaiņām: HMAC tiek aprēķināts no NEAPSTRĀDĀTA pieprasījuma pamata, tāpēc Webhook mezglā jāieslēdz opcija Raw Body (bez tās n8n nodod jau parsētu JSON un paraksts nekad nesakritīs), un Code mezglā crypto jāimportē ar require, nevis import. Neapstrādājiet pamatu, kamēr neesat pārbaudījuši parakstu.

Kad zvans beidzas, atnāk šāds saturs:

{
  "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": "Labdien, zvanu saistībā ar pasūtījumu A-42." },
      { "role": "caller", "message": "Jā, es to jau zinu, paldies par atgādinājumu." }
    ],
    "summary": "Klients apstiprināja pasūtījuma A-42 saņemšanu.",
    "data": {
      "order_confirmed": true
    }
  }
}

Atslēga data objektā data ir neobligāta un satur tieši tos laukus, ko pie aģenta esat iestatījuši zem viņa dataFields - iepriekš redzamais piemērs (order_confirmed) ir tikai ilustrācijai, jūsu laukiem būs citi nosaukumi. Nākamais n8n mezgls pēc šiem laukiem var sazaroties, piemēram, atjaunināt CRM ierakstu vai ieplānot zvanu no jauna.

Kā zvanīt bez aģenta?

Ja balss aģents nav vajadzīgs, bet tikai tiešs savienojums starp diviem numuriem (piemēram, starp tirdzniecības pārstāvi un klientu), sūtiet from agentId vietā:

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

volai vispirms piezvana uz numuru from un, tiklīdz kāds atbild, sastāda numuru to. Abi zvana posmi tiek rēķināti atsevišķi par 0,92 kr minūtē (bez aģenta uzcenojuma). from ir numurs, uz kura atbildat JŪS - parasti jūsu mobilais tālrunis - un tas var būt jebkurš Čehijas vai Slovākijas numurs, tam nav jāpieder jūsu volai kontam. Īstais priekšnosacījums ir cits: jūsu kontā jābūt vismaz vienam savam volai numuram, jo caur to zvans tiek rēķināts un to abas puses redz displejā (bez tā volai atgriež bridge_needs_number). Neierakstiet laukā from volai numuru, kas ir pavērsts uz aģentu vai SIP - tīkls pirmo zvana posmu savienotu ar aģentu jūsu vietā, un jūsu tālrunis nekad nezvanītu.

Cik šāds zvans maksā?

Izejošais zvans caur aģentu tiek rēķināts kā divu tarifu summa: izejošā minūte (0,92 kr) PLUSS aģenta uzcenojums (2,50 kr), abi pēc 2026. gada 2. septembra cenrāža. 90 sekunžu zvans maksā 5,13 kr:

Rēķina pa sekundēm, nevis par uzsāktām minūtēm - īsāks zvans attiecīgi maksā mazāk. Pilns cenrādis (numuri, aģents, SMS) ir lapā /cenik.

Droša atkārtošana (Idempotency-Key)

Kļūdas gadījumā n8n mezglu var atkārtot automātiski (Retry On Fail) - bez aizsardzības tas nozīmētu divus īstus zvanus vienam klientam. Pievienojiet galveni Idempotency-Key ar vērtību, kas vienas darbplūsmas izpildes laikā paliek nemainīga (n8n šim nolūkam piedāvā mainīgo {{ $execution.id }}, vai izmantojiet sava pasūtījuma ID) - ar to pašu atslēgu 24 stundu laikā saņemsiet atpakaļ pirmā mēģinājuma atbildi un zvans netiks sākts dubultā:

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

Ko darīt, ja API atgriež kļūdu?

Šī tabula aptver variantus agentId un from - stāvokļi, kas attiecas tikai uz izmēģinājuma zvanu bez sava numura (systemPrompt), ir apzināti izlaisti, tā ir cita plūsma.

Kas tālāk

Pilnu pārskatu par to, ko no n8n var darīt (SMS, numuri, zvanīšanas aizlieguma saraksts), atradīsiet n8n integrācijas ceļvedī. Pilna REST atsauce ir lapā /docs/api, pilns webhook notikumu saraksts ar paraksta pārbaudi - lapā /docs/webhooky.

Kas tālāk