Pošiljanje SMS prek API-ja v 10 minutah v Node.js

Če želite poslati SMS iz Node.js, potrebujete en zahtevek POST na https://volai.cz/v1/messages z glavo Authorization: Bearer vk_... in telesom JSON s polji {to, body}. Node 20 ima fetch vgrajen, zato vam ni treba nameščati nobenega paketa. Delujoč primer sledi takoj spodaj, vključno z obravnavo napak in idempotentnostjo, da omrežna težava ne pošlje istega sporočila dvakrat.

Kaj boste potrebovali

• Node.js 18 ali novejši - fetch je vgrajen od te različice; priporočamo trenutno podprto vrstico LTS (24, stanje 2. 9. 2026).
• Račun volai in ključ API iz portala (Nastavitve -> API in MCP) v obliki vk_....
• Vsaj eno dopolnitev dobroimetja. Za SMS je potrebna prva dopolnitev; pozdravno dobroimetje jih ne pokrije - z njim lahko preizkusite klice, ne pa sporočil SMS.
• Številko prejemnika na Češkem ali Slovaškem (+420 ali +421) - v druge države SMS ne pošiljamo.
• Lastne telefonske številke NE potrebujete. Sporočila odhajajo pod skupnim imenom pošiljatelja SMSinfo - operaterji v čeških omrežjih dovoljujejo le odobrena imena pošiljateljev, zato lastno ime pošiljatelja s skupnim pošiljateljem ni mogoče, prejemniki pa SMSinfo ne morejo odgovoriti. Svojo identiteto zapišite v samo besedilo sporočila, kot v spodnjem primeru. Če želite odgovore, pošiljajte z lastne mobilne številke (dodatek, glejte opombo spodaj).

Pošljite prvi SMS

Zahtevek potrebuje le dve polji: to (številka prejemnika) in body (besedilo sporočila). Odgovor vrne id sporočila, njegov status, ceno v stotinih krone (priceHal) in število segmentov (segments) - več o obojem spodaj.

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

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 }

Koliko stanejo SMS in kaj so segmenti?

Enosegmentni SMS stane 1.36 CZK brez DDV (cena na dan 2. 9. 2026). Koliko segmentov sporočilo zavzame, je odvisno od tega, ali vsebuje znake zunaj abecede GSM-7 - operaterji SMS segmentirajo po standardu GSM 03.38:

En sam znak zunaj osnovne abecede GSM-7 (šumniki, emoji, večina nelatiničnih pisav) preklopi CELOTNO sporočilo na UCS-2, tudi če je edini tak znak v besedilu. Nasvet: če želite zanesljivo ostati znotraj enega segmenta, uporabljajte le navadne znake GSM-7.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_VAS_KLJUC",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Pošiljamo vam opomnik: jutri ob 10. uri imate termin pri nas, če ga ne morete obiskati, nam to prosim sporočite.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotentnost: varno ponavljanje zahtevkov

Dodajte glavo Idempotency-Key z nizom po svoji izbiri, na primer z identifikatorjem naročila. Če zahtevek odpove zaradi omrežne napake in ga vaš potek dela ponovi z ISTO glavo, volai vrne shranjeni odgovor prvega poskusa, namesto da bi sporočilo poslal drugič - ključ velja 24 ur.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_VAS_KLJUC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: narocilo-4471" \
  -d '{"to": "+420777123456", "body": "Vaše naročilo št. 4471 je bilo sprejeto."}'

Ključ API hranite na varnem

Ključ API (vk_...) ima enako težo kot geslo - kdor ga ima, lahko v vašem imenu pošilja sporočila in porablja dobroimetje. Nikoli ga ne zapisujte v izvorno kodo, ki jo potrjujete v repozitorij. Sodi v okoljsko spremenljivko (process.env.VOLAI_API_KEY v Node.js) ali v upravljalnik skrivnosti, ki ga ponuja vaš ponudnik gostovanja.

// .env.local (te datoteke nikoli ne potrdite v repozitorij)
// VOLAI_API_KEY=vk_vas_kljuc

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 }),
});

Končno točko kličite s strežnika, nikoli iz brskalnika - kdor koli bi lahko ključ prebral v razvijalskih orodjih brskalnika in začel pošiljati sporočila na vaš račun. Če ključ kdaj pušča (na primer ob nenamernem potrditvi v repozitorij), v portalu ustvarite novega in starega prekličite - stara vrednost preneha delovati takoj.

Najprej varno preizkusite

Preden pošiljanje SMS vključite v resničen proces (na primer potrditve naročil), prvih nekaj sporočil pošljite na lastno telefonsko številko. Videli boste natanko to, kar vidi stranka - kako izgleda ime pošiljatelja SMSinfo, kako dolgo traja dostava in ali se segmentacija obnaša, kot pričakujete. Šele nato polje to preklopite na številko resnične stranke.

Kaj storiti, ko API vrne napako?

Odgovor z napako ima vedno obliko {error: {code, message}}, s stanjem HTTP, ki ustreza vrsti napake:

Katera stanja ima lahko sporočilo?

Polje status, tako na seznamu (GET /v1/messages) kot pri posameznem sporočilu, ima pet možnih vrednosti: pending (shranjeno, še se pošilja), sent (operater je potrdil pošiljanje), failed (operater ga je zavrnil - ni obračunano), unknown (potrditev dostave ni prispela, običajno zaradi izteka časa na strani operaterja - obračunano je v celoti, saj je sporočilo morda prispelo) in received (samo za dohodna sporočila, torej z direction=in; poslana sporočila te vrednosti nikoli nimajo).

Vsako sporočilo ima tudi polja direction (out za poslana sporočila, in za prejeta), smsNumber (številka, s katere je bilo sporočilo poslano ali na katero je bilo prejeto; null za sporočila pod skupnim imenom pošiljatelja SMSinfo) in deliveryStatus (delivered ali undelivered, poročilo o dostavi operaterja; obstaja le pri sporočilih, poslanih s mobilne številke, pri vseh drugih je null).

Kako poslati več sporočil SMS naenkrat?

Omejitev dovoljuje največ en SMS na dve sekundi na račun, do 100 SMS na dan. Pri pošiljanju več sporočil naenkrat (na primer opomnikov na termine) je kratek premor med zahtevki preprostejši kot lovljenje rate_limited in ponovno poskušanje:

const message = "Opomnik: jutri imate termin - Moja aplikacija";

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

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

  // Omejitev je največ 1 SMS na 2 sekundi na račun - kratek premor med
  // zahtevki je preprostejši kot obravnava rate_limited in ponovni poskusi.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Skratka: en klic POST /v1/messages s poljema to in body pošlje SMS, glava Idempotency-Key varuje potek dela s ponavljanjem pred dvojnim pošiljanjem, cena pa se računa na segment glede na to, ali besedilo vsebuje znake zunaj GSM-7. Ključ hranite zunaj repozitorija in prvo sporočilo pošljite sebi.

Kako naprej

Celotna referenca REST API (številke, klici, webhooki, agenti) je na /docs/api. Želite izvedeti trenutek, ko volai preda sporočilo operaterju, brez poizvedovanja po GET /v1/messages? Naročite se na dogodek message.sent - ta potrjuje le, da je operater sporočilo sprejel, ne da je prispelo na telefon (volai tega pri sporočilih pod skupnim imenom ne vidi, glejte zgoraj; sporočila, poslana z lastne mobilne številke, imajo poročilo o dostavi) - glejte dokumentacijo webhookov. In če potrebujete telefonsko številko, ki sprejema tudi klice, ne le SMS, si oglejte AI receptorja.

Kaj naprej