Treceți la conținut
REST API

SMS-uri și apeluri direct din workflow-ul dvs. n8n

n8n apelează API-ul REST volai prin nodul HTTP Request - fără cod puteți trimite un SMS, porni un apel printr-un agent vocal și primi rezultatul înapoi prin webhook.

1Salvați cheia ca credential

În n8n creați un credential nou de tip HTTP Header Auth: numele header-ului Authorization, valoarea Bearer vk_CHEIA_DVS (cheia o găsiți în portal, în secțiunea Asistent AI). Atribuiți-l fiecărui nod HTTP Request care apelează volai.cz/v1/* - aceeași cheie este valabilă pentru SMS, apeluri și webhook.

2Trimiteți un SMS din workflow

Adăugați un nod HTTP Request: metoda POST, URL https://volai.cz/v1/messages, corp JSON cu câmpurile to și body. Răspunsul conține priceHal (prețul în sutimi din moneda de facturare, pentru toate segmentele) și segments - un mesaj cu diacritice folosește mai multe segmente decât unul în ASCII simplu. De aceea exemplul de mai jos lasă intenționat textul mesajului fără diacritice, ca să rămână într-un singur segment - cu diacritice funcționează la fel, doar că se consumă mai multe segmente.

bash
curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_CHEIA_DVS" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Comanda dumneavoastra este gata de ridicare."}'

3Sunați un client prin agentul dvs.

Al doilea nod HTTP Request: POST https://volai.cz/v1/calls cu to și agentId al unui agent vocal existent (îl creați în portal sau prin POST /v1/agents) - agentul trebuie să aibă un număr propriu atribuit, altfel cererea se încheie cu eroarea agent_no_number. Cererea doar pornește apelul și returnează id-ul acestuia - rezultatul real (finalizat, fără răspuns, eșuat) îl aflați din webhook-ul de la pasul următor.

bash
curl -X POST https://volai.cz/v1/calls \
  -H "Authorization: Bearer vk_CHEIA_DVS" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "agentId": "ag_kx91fa2b"}'

4Configurați webhook-ul, ca workflow-ul să primească răspuns

Adăugați un trigger Webhook (n8n vă generează URL-ul) și salvați exact aceeași adresă prin PUT /v1/webhook, împreună cu lista evenimentelor care vă interesează. Atenție: un array events gol nu înseamnă niciun eveniment, ci absolut toate - enumerați-le întotdeauna. Răspunsul returnează și un secret - salvați-l imediat, GET /v1/webhook nu îl mai returnează.

bash
curl -X PUT https://volai.cz/v1/webhook \
  -H "Authorization: Bearer vk_CHEIA_DVS" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://n8n-ul-dvs.app.n8n.cloud/webhook/volai", "events": ["call.completed", "message.sent"]}'

5Verificați semnătura și abia apoi procesați corpul

Fiecare cerere poartă header-ul Volai-Signature în forma t=<unix>,v1=<hex>. Într-un nod Code calculați HMAC-SHA256 peste {t}.{rawBody} cu secret-ul dvs. și comparați-l cu v1 - procesați corpul doar dacă se potrivesc. În nodul Webhook activați, la Add Options, opțiunea Raw Body - fără ea, n8n parsează corpul singur, iar octeții peste care s-a calculat semnătura se pierd. Cu opțiunea activată, corpul ajunge însă ca date binare (proprietatea data), nu în json.body - codul de mai jos îl citește de aceea prin getBinaryDataBuffer, ceea ce funcționează indiferent dacă n8n păstrează datele binare în memorie, pe disc sau în S3. Modulul încorporat crypto poate fi folosit în nodul Code doar pe n8n self-hosted cu NODE_FUNCTION_ALLOW_BUILTIN=crypto activat - n8n Cloud nu acceptă deloc importul de module, deci verificarea nu încape acolo într-un singur nod. Pe Cloud prelungiți de aceea lanțul cu un nod Extract From File (operația Extract From Text File) - acesta convertește mai întâi datele binare în text, într-un câmp la alegere (de exemplu rawBody) - și abia apoi un nod Crypto (acțiunea Hmac, tip SHA256, codare HEX, valoarea o expresie care alătură marcajul de timp din header cu câmpul rawBody, secretul introdus printr-un credential Crypto, nu într-un câmp de text obișnuit) calculează amprenta fără cod; comparația cu v1 o încheie apoi un nod IF.

javascript
// Intrare din nodul Webhook cu opțiunea Raw Body activată: header este valoarea
// "Volai-Signature", de ex. "t=1756111640,v1=8f2ac1d4..."; corpul brut
// ajunge ca date binare (numele implicit al proprietății este "data"), nu în json.body.
const header = $input.first().json.headers['volai-signature'];

// getBinaryDataBuffer funcționează în toate modurile de stocare a datelor binare din n8n
// (implicit în memorie, precum și filesystem/S3) - citirea directă a
// $input.first().binary.data.data ar funcționa doar în modul de stocare în memorie.
const rawBody = (await this.helpers.getBinaryDataBuffer(0, 'data')).toString('utf8');

// secret este valoarea de la pasul 4 (PUT /v1/webhook) - în producție citiți-o
// dintr-un credential n8n sau dintr-o variabilă de mediu, nu o scrieți niciodată direct în cod
const secret = 'whsec_inlocuiti_cu_al_dvs';

const crypto = require('crypto'); // doar n8n self-hosted, vezi textul pasului

const [tPart, v1Part] = header.split(',');
const t = tPart.replace('t=', '');
const v1 = v1Part.replace('v1=', '');

const expected = crypto
  .createHmac('sha256', secret)
  .update(`${t}.${rawBody}`)
  .digest('hex');

if (expected !== v1) {
  throw new Error('Semnătură Volai-Signature nevalidă');
}

Ce puteți face cu el

SMS de confirmare după o comandă

Magazinul dvs. online sau sistemul de rezervări trimite către n8n un webhook la o comandă nouă - workflow-ul expediază imediat un SMS cu confirmarea și ora estimată de ridicare.

Apeluri efectuate dintr-un planificator sau dintr-un tabel

Un rând din Google Sheets, Airtable sau din CRM-ul dvs. declanșează un nod HTTP Request care sună clientul prin agentul dvs. vocal - reamintirea unei programări, un îndemn de a finaliza comanda, un scurt sondaj.

Scrierea rezultatului apelului înapoi în sistem

Webhook-ul call.completed aduce transcrierea, rezumatul și datele colectate în timpul apelului (data) - workflow-ul le scrie în CRM, într-un tabel sau le trimite pe Slack, fără ascultarea manuală a înregistrării.

Întrebări frecvente

Există un nod n8n oficial pentru volai?
Încă nu - astăzi sunt suficiente nodurile generale HTTP Request și Webhook, pe care n8n le are mereu la dispoziție. Un nod de comunitate verificat ar trebui să treacă prin review-ul din n8n Creator Portal - deocamdată nu pregătim unul.
Cum știu că webhook-ul a fost trimis cu adevărat de volai și nu de altcineva?
După header-ul Volai-Signature - o semnătură HMAC-SHA256 cu secret-ul pe care vi-l returnează fiecare PUT /v1/webhook (salvați-l imediat, GET nu îl mai returnează). Formula completă, cu exemple în Python și TypeScript, se află la /docs/webhooky.
Ce se întâmplă dacă HTTP Request expiră (timeout) și n8n îl repetă?
Adăugați header-ul Idempotency-Key cu orice valoare stabilă (de exemplu ID-ul comenzii). În 24 de ore primiți, la o cerere repetată cu aceeași cheie, exact același răspuns - SMS-ul sau apelul nu se trimit a doua oară.
Cât costă în plus automatizarea față de apelarea manuală a API-ului?
Nimic - nu există niciun supliment pentru n8n. Se aplică aceleași tarife ca în lista de prețuri: SMS 1,36 kr (≈ 0,28 RON), apel efectuat 0,92 kr/min (≈ 0,19 RON), agent vocal în plus 2,50 kr/min (≈ 0,52 RON). Lista completă de prețuri este la /cenik.

Încercați chiar acum

Înregistrați-vă și primii 50 kr sunt din partea noastră.