SMS brána cez API za 10 minút v Node.js

Aby ste z Node.js poslali SMS, stačí jedna požiadavka POST na https://volai.cz/v1/messages s hlavičkou Authorization: Bearer vk_... a telom JSON {to, body}. Node 20 má fetch zabudovaný, takže nepotrebujete žiadny balík navyše. Funkčný príklad je hneď pod týmto odsekom, vrátane ošetrenia chýb a idempotencie, aby vám výpadok siete neodoslal tú istú správu dvakrát.

Čo budete potrebovať

• Node.js 18 alebo novší - fetch je zabudovaný od tejto verzie; odporúčame aktuálnu podporovanú líniu LTS (24, stav k 2. 9. 2026).
• Účet vo volai a kľúč API z portálu (Nastavenia -> API a MCP) v tvare vk_....
• Aspoň jedno dobitie kreditu. SMS idú až po prvom dobití, uvítací kredit na ne použiť nejde - hovory si z neho vyskúšate, textovky nie.
• Telefónne číslo príjemcu v Česku alebo na Slovensku (+420 alebo +421) - do iných krajín SMS neposielame.
• Vlastné telefónne číslo NEPOTREBUJETE. Správy odchádzajú pod zdieľaným menom SMSinfo - operátori v českých sieťach povoľujú iba schválené mená, vlastné meno odosielateľa pri zdieľanom odosielateľovi nastaviť nejde a na SMSinfo príjemca odpovedať nemôže. Svoju identitu preto uveďte priamo v texte správy, ako v príklade nižšie. Ak chcete, aby sa dalo odpovedať, pošlite správu z vlastného mobilného čísla (doplnok, pozrite upozornenie nižšie).

Pošlite prvú SMS

Požiadavke stačia dve polia: to (číslo príjemcu) a body (text správy). Odpoveď vráti id správy, status, cenu v halieroch (priceHal) a počet segmentov (segments) - k obom sa o chvíľu vrátime.

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_VAS_KLUC",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Ahoj z volai! - Moja appka",
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error("volai " + error.code + ": " + error.message);
}

const message = await response.json();
console.log(message);
// { id: "msg_7c1f9a2e", status: "sent", priceHal: 136, segments: 1 }

Koľko stoja SMS a čo sú segmenty?

Jedna SMS v jednom segmente stojí 1,36 kr bez DPH (cena platná k 2. 9. 2026). Koľko segmentov správa zaberie, závisí od toho, či obsahuje znaky mimo abecedy GSM-7 - operátori delia SMS podľa štandardu GSM 03.38:

Stačí JEDEN znak mimo základnej abecedy GSM-7 (znaky s diakritikou, emoji, väčšina nelatinkových písem) a CELÁ správa sa prepne na UCS-2, aj keby bol v texte iba jeden mäkčeň. Tip: ak sa chcete spoľahlivo zmestiť do jedného segmentu, píšte bez diakritiky.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_VAS_KLUC",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Dobrý deň, pripomíname Vám zajtrajší termín o 10:00 - ak Vám nevyhovuje, odpíšte nám a nájdeme iný čas. Ďakujeme.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotencia: bezpečné opakovanie požiadavky

Pošlite navyše hlavičku Idempotency-Key s ľubovoľným vlastným reťazcom, napríklad ID objednávky. Ak požiadavka zlyhá na výpadku siete a váš workflow ju zopakuje s ROVNAKOU hlavičkou, volai vráti uloženú odpoveď z prvého pokusu a správu neodošle druhýkrát - kľúč platí 24 hodín.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_VAS_KLUC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: objednavka-4471" \
  -d '{"to": "+420777123456", "body": "Vaša objednávka č. 4471 bola prijatá."}'

Bezpečne zaobchádzajte s kľúčom API

Kľúč API (vk_...) má rovnakú váhu ako heslo - kto ho pozná, môže vaším menom posielať správy a míňať kredit z vášho účtu. Do zdrojového kódu, ktorý commitujete do repozitára, ho preto nikdy nepíšte. Patrí do premennej prostredia (process.env.VOLAI_API_KEY v Node.js) alebo do správcu tajomstiev, ktorý používa váš hosting.

// .env.local (nikdy necommitujte do repozitára)
// VOLAI_API_KEY=vk_vas_kluc

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.VOLAI_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to, body }),
});

Endpoint volajte vždy zo servera, nie z prehliadača - kto by si kľúč prečítal vo vývojárskych nástrojoch prehliadača, mohol by na váš účet začať posielať vlastné správy. Ak kľúč unikol (napríklad omylom v commite), vygenerujte si v portáli nový a ten starý zneplatnite - stará hodnota prestane fungovať okamžite.

Najprv si to bezpečne vyskúšajte

Skôr než odosielanie SMS napojíte na skutočný proces (napríklad potvrdenie objednávky), pošlite prvých pár správ na vlastné telefónne číslo. Uvidíte presne to, čo uvidí zákazník - ako vyzerá odosielateľ SMSinfo, ako dlho trvá doručenie a či sa segmenty počítajú tak, ako očakávate. Až potom prepnite to na skutočné číslo zákazníka.

Čo robiť, keď API vráti chybu?

Neúspešná odpoveď má vždy tvar {error: {code, message}} a stav HTTP podľa typu chyby:

Aké stavy môže správa mať?

Pole status vo výpise (GET /v1/messages) aj v detaile jednej správy nadobúda päť hodnôt: pending (uložená, ešte sa odosiela), sent (operátor odoslanie potvrdil), failed (operátor odmietol - neúčtuje sa), unknown (potvrdenie o doručení nedorazilo, typicky timeout na strane operátora - napriek tomu sa účtuje v plnej cene, pretože správa mohla prísť) a received (iba pri prijatých správach, teda s direction=in; odoslané správy ho nemajú).

Každá správa nesie aj polia direction (out pri odoslaných, in pri prijatých), smsNumber (číslo, z ktorého správa odišla alebo na ktoré prišla; pri správach pod zdieľaným menom SMSinfo je null) a deliveryStatus (delivered alebo undelivered, doručenka od operátora; vzniká iba pri SMS odoslaných z mobilného čísla, pri ostatných správach je null).

Ako rozposlať viac SMS naraz?

Rate limit dovoľuje najviac jednu SMS za dve sekundy na účet a najviac 100 SMS denne. Pri rozosielaní viacerých správ naraz (napríklad pripomienok stretnutí) je jednoduchšie medzi požiadavkami krátko počkať, než chytať rate_limited a skúšať znova:

const message = "Pripomíname Vám zajtrajší termín - Moja appka";

for (const to of recipients) {
  const response = await fetch("https://volai.cz/v1/messages", {
    method: "POST",
    headers: {
      Authorization: "Bearer vk_VAS_KLUC",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ to, body: message }),
  });

  if (!response.ok) {
    const { error } = await response.json();
    console.error("volai " + to + ": " + error.code);
  }

  // Limit je najviac 1 SMS za 2 sekundy na účet - krátka pauza medzi
  // požiadavkami je jednoduchšia než riešiť rate_limited a skúšať znova.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Zhrnutie: jedno volanie POST /v1/messages s poľami to a body pošle SMS, hlavička Idempotency-Key chráni workflow pred dvojitým odoslaním pri opakovaní požiadavky a cena sa počíta po segmentoch podľa toho, či text obsahuje znaky mimo GSM-7. Kľúč držte mimo repozitára a prvú správu si pošlite sami sebe.

Čo ďalej

Plná referencia REST API (čísla, hovory, webhooky, agenti) je na /docs/api. Chcete vedieť hneď, ako volai odovzdá správu operátorovi, bez pollingu GET /v1/messages? Prihláste sa na odber udalosti message.sent - potvrdzuje iba prevzatie operátorom, nie doručenie do telefónu (pri správach pod zdieľaným menom to volai nevidí, pozrite vyššie; správy odoslané z vlastného mobilného čísla majú doručenku) - pozrite dokumentáciu webhookov. A ak okrem SMS potrebujete aj telefónne číslo, ktoré samo zdvíha hovory, pozrite sa na AI recepčnú.

Čo ďalej