Gå til indholdet
REST API

SMS og opkald direkte fra n8n-workflowen

n8n kalder volai REST API'et via HTTP Request-noden - uden kode kan en workflow sende en SMS, starte et opkald via en stemmeagent og få resultatet tilbage som en webhook.

Kom i gang med den native connector

Den offentlige pakke n8n-nodes-volai@0.1.2 kan installeres på selvhostet n8n. n8n-verificeringen er stadig i gang; tilgængelighed i n8n Cloud er ikke bekræftet.

1Forbind kontoen og læs saldoen

Åbn som Owner eller Admin af en selvhostet instans Settings > Community Nodes > Install, indtast n8n-nodes-volai@0.1.2, og læs advarslen om den uverificerede pakke. Opret en Volai API-credential med en nøgle fra API og MCP. Vælg Resource Balance, Operation Get i Volai. Det læser kun saldoen og sender intet. GitHub README.

2Vælg et eksempel og kontrollér resultatet

Brug Import from URL til forbindelsestjek, opkaldsresultat eller indgående SMS. Vælg egne legitimationsoplysninger. Alle eksempler er inaktive og har ingen afsendelsesnode. Kør det første manuelt. Vælg en hændelse i Volai Trigger, og test først modtagelsen. Triggeren opretter sit eget abonnement og verificerer hændelsen gennem det autentificerede API. Tilknyt event_id, data.id og data.status; brug event_id mod dobbelte registreringer. SMS-modtagelse kræver et SMS-kompatibelt nummer. Triggere venter på en ny hændelse fra normal aktivitet; de afspiller ikke historiske registreringer igen.

3Tilføj først derefter en betalt handling

SMS, opkald og talebeskeder bruger saldo efter priserne; automatiseringsplatformen afregner egne kørsler efter sin plan. Kontrollér modtager, nødvendigt nummer/agent og fejlhåndtering før aktivering. Tilknyt Idempotency Key til et stabilt hændelses-ID som order-42-sms. Genbrug nøglen ved gentagelser af samme handling, og brug en ny til en ny handling. En accepteret anmodning bekræfter hverken levering eller et vellykket opkald.

Manuelt alternativ med HTTP og Webhooks

1Gem nøglen som credential

Opret i n8n en ny credential af typen HTTP Header Auth: headernavn Authorization, værdi Bearer vk_DIN_NOEGLE (nøglen findes i portalen under AI-assistent). Tildel den til hver HTTP Request-node, der kalder volai.cz/v1/* - den samme nøgle gælder for SMS, opkald og webhook.

2Send en SMS fra workflowen

Tilføj en HTTP Request-node: metode POST, URL https://volai.cz/v1/messages, JSON-body med felterne to og body. Svaret indeholder priceHal (prisen i hundrededele af en kredit, for alle segmenter af beskeden) og segments - en tekst med diakritiske tegn fylder flere segmenter end en ren ASCII-besked. Eksemplet herunder lader derfor med vilje beskedteksten stå uden diakritiske tegn, så den bliver i ét segment - med diakritiske tegn virker det på samme måde, der bruges blot flere segmenter.

bash
curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_DIN_NOEGLE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420777123456", "body": "Din bestilling er klar til afhentning."}'

3Ring til en kunde via agenten

En anden HTTP Request-node: POST https://volai.cz/v1/calls med to og agentId for en eksisterende stemmeagent (den oprettes i portalen eller via POST /v1/agents) - agenten skal have tildelt et eget nummer, ellers ender anmodningen med fejlen agent_no_number. Anmodningen starter kun opkaldet og returnerer dets id - det faktiske udfald (gennemført, ikke besvaret, mislykket) fremgår af webhooken i næste trin.

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

4Opsæt en webhook, så workflowen får svar tilbage

Tilføj en Webhook-trigger (n8n genererer en URL) og gem den samme adresse via PUT /v1/webhook sammen med listen over de hændelser, der er relevante. Pas på: et tomt events-array betyder ikke ingen hændelser, men alle - angiv derfor altid de ønskede hændelser eksplicit. Svaret returnerer også en secret - gem den med det samme, GET /v1/webhook returnerer den aldrig igen.

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

5Bekræft signaturen, før body behandles

Hver anmodning har en Volai-Signature-header i formen t=<unix>,v1=<hex>. I en Code-node beregnes HMAC-SHA256 over {t}.{rawBody} med den gemte secret og sammenlignes med v1 - body behandles først, når de to er ens. Slå i Webhook-noden indstillingen Raw Body til under Add Options - uden den parser n8n body'en med det samme, og de præcise bytes, som signaturen blev beregnet over, går tabt. Med indstillingen slået til ankommer body'en i stedet som binære data (egenskaben data), ikke i json.body - koden herunder læser den derfor via getBinaryDataBuffer, som virker, uanset om n8n gemmer binære data i hukommelsen, på disk eller i S3. n8n Cloud indeholder det indbyggede modul crypto. På selvhostet n8n tillades det med NODE_FUNCTION_ALLOW_BUILTIN=crypto. Webhookens hemmelige nøgle må ikke indgå i delte workflows eller udførelseslogfiler; den native trigger ovenfor håndterer sin egen verificering uden denne brugerdefinerede kode.

javascript
// Input fra Webhook-noden med indstillingen Raw Body slået til: headeren er værdien af
// "Volai-Signature", fx "t=1756111640,v1=8f2ac1d4..."; den rå body
// ankommer som binære data (standardnavn på egenskaben "data"), ikke i json.body.
const header = $input.first().json.headers['volai-signature'];

// getBinaryDataBuffer virker i alle lagringstilstande for binære data i n8n
// (standard i hukommelsen samt filesystem/S3) - direkte læsning af
// $input.first().binary.data.data ville kun virke i hukommelsestilstand.
const rawBody = (await this.helpers.getBinaryDataBuffer(0, 'data')).toString('utf8');

// secret er værdien fra trin 4 (PUT /v1/webhook) - i produktion læses den
// fra en n8n-credential eller en miljøvariabel, aldrig skrevet direkte i koden
const secret = 'whsec_erstat_med_din';

const crypto = require('crypto');

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('Ugyldig signatur i Volai-Signature');
}

return [{ json: JSON.parse(rawBody) }];

Hvad den kan bruges til

Bekræftelses-SMS efter en bestilling

Webshoppen eller bookingsystemet sender en webhook til n8n om en ny bestilling - workflowen sender straks en bekræftelses-SMS med det forventede afhentningstidspunkt.

Udgående opkald fra en planlægger eller et regneark

En række i Google Sheets, Airtable eller CRM-systemet udløser en HTTP Request-node, der ringer til kunden via stemmeagenten - en påmindelse om en aftale, en opfordring til at gennemføre en bestilling, en kort undersøgelse.

Opkaldsresultatet skrives tilbage i systemet

Webhooken call.completed leverer udskrift, resumé og de oplysninger, som agenten har noteret under opkaldet (data) - workflowen skriver dem ind i CRM-systemet eller et regneark eller sender dem til Slack, uden at nogen manuelt skal lytte til optagelsen.

Ofte stillede spørgsmål

Findes der en officiel n8n-node til volai?
Kildepakken til volais community-forbindelse n8n-nodes-volai findes og understøtter SMS, opkald, talebeskeder og automatiske webhook-triggere. GitHub-README-filen beskriver den aktuelle tilgængelighed samt installation og udgivelse. Brug i n8n Cloud kræver platformsgodkendelse, som endnu ikke er bekræftet.
Hvordan kan det ses, at webhooken virkelig kom fra volai og ikke fra en uvedkommende?
Ud fra signaturen i headeren Volai-Signature (HMAC-SHA256 med secret fra PUT /v1/webhook, gem den med det samme). Formlen med eksempler findes på /docs/webhooky.
Hvad sker der, hvis HTTP Request løber ind i en timeout, og n8n gentager den?
Tilføj headeren Idempotency-Key med en vilkårlig stabil værdi (fx bestillings-ID'et). Inden for 24 timer returneres der på en gentaget anmodning med samme nøgle præcis det samme svar - hverken SMS eller opkald sendes en gang til.
Hvad koster automatiseringen ekstra i forhold til at kalde API'et manuelt?
Intet - der er intet tillæg for n8n. Der gælder de samme takster som i prisoversigten: SMS 0,425 kr., udgående opkald 0,288 kr./min, stemmeagent oveni 0,782 kr./min. De præcise priser findes på /cenik.

Prøv det med det samme

Opret en konto, og de første 15 kr. i saldo er på os.