Cum sunați un client dintr-un workflow n8n

Din n8n puteți suna un client fără să scrieți nicio linie de cod: adăugați în workflow un nod HTTP Request și îndreptați-l către POST https://volai.cz/v1/calls cu antetul Authorization: Bearer vk_... și cu un corp de forma {to, agentId} - iar agentul vocal formează numărul exact atunci când workflow-ul are nevoie. Mai jos găsiți configurarea completă: cum transferați datele din workflow în promptul agentului, cum aduceți rezultatul apelului înapoi în n8n și cum sunați fără agent, conectând direct două numere.

Ce veți avea nevoie

• O instanță n8n - în cloud sau găzduită propriu, în orice versiune recentă.
• Un cont volai și o cheie API din portal (Setări -> API și MCP), de forma vk_.... Salvați-o în n8n ca credențial de tip Header Auth (antetul Authorization, valoarea Bearer vk_...), ca să nu copiați cheia în fiecare nod în parte.
• Un număr de telefon propriu cu un agent vocal atașat - îl puteți crea în portal sau prin /docs/agent. Nu aveți încă un agent? Tot puteți suna, conectând direct două numere (varianta cu from de mai jos).

1Adăugați un nod HTTP Request

Metoda POST, adresa URL https://volai.cz/v1/calls, autentificare prin credențialul salvat, tipul conținutului (Body Content Type) JSON. Corpul cererii are nevoie de to (numărul clientului) și agentId (identificatorul agentului din portal) - ambele obligatorii, iar din agentId/from/systemPrompt trebuie indicat exact UNUL, niciodată mai mult de unul.

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

Valorile scrise ca ={{...}} sunt expresii n8n - $json citește câmpuri din nodul anterior al workflow-ului (de exemplu dintr-un webhook „comandă nouă” sau dintr-un rând de foaie de calcul).

2Transferați datele din workflow în promptul agentului

variables este un obiect de tip text-la-text pe care agentul îl primește ca variabile dinamice - în promptul de sistem le menționați ca {{customer_name}}. Limite: cel mult 20 de chei, chei de până la 64 de caractere, valori de până la 512 de caractere. Numele attempt_id, caller_number și called_number sunt rezervate - volai le completează singur, iar valorile corespunzătoare din workflow ar fi ignorate.

ringingTimeoutSecs (de la 5 la 60 de secunde, implicit 25) stabilește cât timp lăsați telefonul să sune înainte ca un apel fără răspuns să se încheie cu endReason: "no_answer". Un timp mai lung crește șansa ca clientul să răspundă, dar ocupă mai mult timp și un slot de apeluri efectuate.

3Citiți răspunsul și, opțional, așteptați rezultatul

Un răspuns de succes revine imediat, dar apelul abia a început - status este initiated, nu o stare finală:

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

Vreți să așteptați rezultatul în aceeași rulare a workflow-ului, în loc să folosiți un webhook separat? Adăugați imediat după nodul HTTP Request un al doilea nod, care apelează GET /v1/calls/{id} cu parametrul waitSecs (de la 0 la 45 de secunde) - serverul răspunde fie când apelul se încheie, fie când expiră timpul, oricare survine mai întâi:

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

Primirea rezultatului: un webhook către n8n

Într-un workflow de producție este de obicei mai practic să nu așteptați pe loc, ci să primiți rezultatul separat: adăugați în n8n un nod Webhook (un workflow nou este perfect suficient), copiați Production URL-ul lui și înregistrați-l o singură dată în 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"]
  }'

Răspunsul conține un secret (de forma whsec_...) - salvați-l, vă va fi necesar pentru verificarea semnăturii fiecărei cereri primite. volai trimite un antet Volai-Signature de forma t=<unix>,v1=<hex> - codul complet de verificare în TypeScript și Python se află la /docs/webhooky. Acesta nu poate fi preluat neschimbat într-un nod Code din n8n: HMAC-ul se calculează din corpul BRUT al cererii, așa că trebuie să activați opțiunea Raw Body pe nodul Webhook (fără ea, n8n vă oferă un JSON deja parsat, iar semnătura nu se va potrivi niciodată), iar modulul crypto trebuie încărcat în nodul Code cu require, nu cu import. Nu prelucrați corpul cererii înainte de a verifica semnătura.

Ce sosește după încheierea apelului:

{
  "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": "Bună ziua, vă sun în legătură cu comanda A-42." },
      { "role": "caller", "message": "Da, știu, mulțumesc pentru reamintire." }
    ],
    "summary": "Clientul a confirmat primirea comenzii A-42.",
    "data": {
      "order_confirmed": true
    }
  }
}

Cheia data imbricată în data este opțională și conține exact câmpurile pe care le-ați configurat agentului în dataFields - exemplul de mai sus (order_confirmed) are doar rol ilustrativ, la dumneavoastră va fi diferit. Un nod n8n următor poate apoi ramifica fluxul după aceste câmpuri, de exemplu pentru a actualiza o înregistrare din CRM sau pentru a reprograma apelul.

Cum sunați fără agent?

Când nu aveți nevoie de un agent vocal, ci doar de o conexiune directă între două numere (de exemplu între un agent de vânzări și un client), trimiteți from în loc de agentId:

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

volai sună mai întâi la from, iar când cineva răspunde, formează to. Ambele segmente ale apelului sunt taxate separat, cu 0.92 CZK pe minut (fără suprataxa pentru agent). from este numărul la care răspundeți DUMNEAVOASTRĂ - de obicei mobilul - și poate fi orice număr ceh sau slovac, nu trebuie să aparțină contului volai. Cerința reală este alta: contul trebuie să aibă cel puțin un număr volai propriu, deoarece prin el este taxat apelul și el apare pe afișaj ambelor părți (fără el, volai returnează bridge_needs_number). Doar să nu introduceți în from un număr volai rutat către un agent sau către SIP - rețeaua ar conecta primul segment la agent, nu la dumneavoastră, iar telefonul dumneavoastră nu ar suna niciodată.

Cât costă un astfel de apel?

Un apel efectuat prin agent este taxat ca suma a două tarife: minutul de apel efectuat (0.92 CZK) plus suprataxa pentru agent, ADĂUGATĂ peste acesta (2.50 CZK), ambele conform listei de prețuri din 2 septembrie 2026. Un apel de 90 de secunde costă 5.13 CZK:

Taxarea se face la secundă, nu pe minute întregi - un apel mai scurt costă proporțional mai puțin. Lista completă de prețuri (numere, agent, SMS) se află la /cenik.

Reîncercări în siguranță (Idempotency-Key)

n8n poate reîncerca automat un nod după o eroare (Retry On Fail) - fără o protecție, asta ar însemna două apeluri telefonice reale către același client. Adăugați un antet Idempotency-Key cu o valoare care rămâne stabilă pe durata unei rulări a workflow-ului (n8n o expune ca {{ $execution.id }}, sau folosiți propriul număr de comandă) - cu aceeași cheie, în decurs de 24 de ore primiți înapoi răspunsul primei încercări, iar apelul nu va fi efectuat de două ori:

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

Ce faceți dacă API-ul returnează o eroare?

Tabelul acoperă variantele agentId și from - stările specifice apelului de probă fără număr propriu (systemPrompt) sunt omise intenționat, fiind un alt flux.

Ce urmează

O prezentare completă a ceea ce se poate face cu n8n (SMS, numere, lista de numere interzise la apelare) se află în ghidul de integrare cu n8n. Documentația REST completă este la /docs/api, iar lista completă a evenimentelor webhook, cu verificarea semnăturii, la /docs/webhooky.

Pașii următori