SMS pristupnik preko API-ja za 10 minuta u Node.js-u

Da biste iz Node.js-a poslali SMS, dovoljan je jedan zahtjev POST na https://volai.cz/v1/messages sa zaglavljem Authorization: Bearer vk_... i tijelom JSON {to, body}. Node 20 ima ugrađen fetch, pa vam nije potreban nikakav dodatni paket. Radni primjer nalazi se odmah ispod ovog odlomka, uključujući obradu pogrešaka i idempotentnost, kako vam ispad mreže ne bi dvaput poslao istu poruku.

Što će vam trebati

• Node.js 18 ili noviji - fetch je ugrađen od te verzije; preporučujemo trenutačnu podržanu LTS liniju (24, stanje na dan 2. 9. 2026.).
• Račun u volai i API ključ iz portala (Postavke -> API i MCP) u obliku vk_....
• Barem jednu dopunu stanja. SMS poruke rade tek nakon prve dopune, početno stanje za njih nije moguće iskoristiti - pozive njime možete isprobati, tekstualne poruke ne.
• Telefonski broj primatelja u Češkoj ili Slovačkoj (+420 ili +421) - u druge zemlje SMS ne šaljemo.
• Vlastiti telefonski broj NE trebate. Poruke odlaze pod zajedničkim imenom SMSinfo - operateri u češkim mrežama dopuštaju samo odobrena imena, vlastito ime pošiljatelja kod zajedničkog pošiljatelja nije moguće postaviti, a na SMSinfo primatelj ne može odgovoriti. Zato svoj identitet navedite izravno u tekstu poruke, kao u primjeru u nastavku. Ako želite da je moguće odgovoriti, pošaljite poruku sa svojeg mobilnog broja (dodatak, vidi napomenu u nastavku).

Pošaljite prvi SMS

Zahtjevu su dovoljna dva polja: to (broj primatelja) i body (tekst poruke). Odgovor vraća id poruke, status, cijenu u halerima (priceHal) i broj segmenata (segments) - na oboje se uskoro vraćamo.

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: "Pozdrav 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 koštaju SMS poruke i što su segmenti?

Jedan SMS u jednom segmentu košta 1,36 kr bez PDV-a (cijena vrijedi na dan 2. 9. 2026.). Koliko će segmenata poruka zauzeti, ovisi o tome sadrži li znakove izvan abecede GSM-7 - operateri dijele SMS prema standardu GSM 03.38:

Dovoljan je JEDAN znak izvan osnovne abecede GSM-7 (znakovi s dijakritikom, emotikoni, većina nelatiničnih pisama) i CIJELA se poruka prebacuje na UCS-2, čak i ako je u tekstu samo jedno slovo s kvačicom. Savjet: ako se želite pouzdano zadržati unutar jednog segmenta, pišite bez dijakritika.

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: "Dobar dan, podsjećamo vas na sutrašnji termin u 10:00 - ako vam ne odgovara, odgovorite nam i dogovorit ćemo drugo vrijeme. Hvala.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotentnost: sigurno ponavljanje zahtjeva

Dodatno pošaljite zaglavlje Idempotency-Key s proizvoljnim vlastitim nizom, na primjer ID-jem narudžbe. Ako zahtjev zakaže zbog ispada mreže, a vaš workflow ga ponovi s ISTIM zaglavljem, volai vraća spremljeni odgovor iz prvog pokušaja i poruku ne šalje drugi put - ključ vrijedi 24 sata.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_VAS_KLJUC" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: narudzba-4471" \
  -d '{"to": "+420777123456", "body": "Vaša narudžba br. 4471 je zaprimljena."}'

Sigurno rukujte API ključem

API ključ (vk_...) ima istu težinu kao lozinka - tko ga zna, može u vaše ime slati poruke i trošiti stanje s vašeg računa. Zato ga nikada ne upisujte u izvorni kod koji commitate u repozitorij. Mjesto mu je u varijabli okruženja (process.env.VOLAI_API_KEY u Node.js-u) ili u upravitelju tajni koji koristi vaš hosting.

// .env.local (nikada ne commitajte u 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 }),
});

Endpoint uvijek pozivajte sa servera, a ne iz preglednika - tko bi ključ pročitao u alatima za razvojne programere u pregledniku, mogao bi s vašeg računa početi slati vlastite poruke. Ako je ključ procurio (primjerice greškom u commitu), generirajte u portalu novi, a stari poništite - stara vrijednost prestaje raditi odmah.

Prvo to sigurno isprobajte

Prije nego što slanje SMS poruka povežete sa stvarnim procesom (primjerice potvrdom narudžbe), pošaljite prvih nekoliko poruka na vlastiti telefonski broj. Vidjet ćete točno ono što će vidjeti klijent - kako izgleda pošiljatelj SMSinfo, koliko traje isporuka i računaju li se segmenti onako kako očekujete. Tek onda prebacite to na stvarni broj klijenta.

Što učiniti kada API vrati pogrešku?

Neuspješan odgovor uvijek ima oblik {error: {code, message}} i HTTP status prema vrsti pogreške:

Koja stanja poruka može imati?

Polje status u ispisu (GET /v1/messages) i u detalju pojedine poruke poprima pet vrijednosti: pending (spremljena, još se šalje), sent (operater je potvrdio slanje), failed (operater je odbio - ne naplaćuje se), unknown (potvrda o isporuci nije stigla, tipično istek vremena na strani operatera - unatoč tome naplaćuje se u punom iznosu jer je poruka mogla stići) i received (samo kod primljenih poruka, dakle s direction=in; poslane poruke ga nemaju).

Svaka poruka nosi i polja direction (out kod poslanih, in kod primljenih), smsNumber (broj s kojeg je poruka otišla ili na koji je stigla; kod poruka pod zajedničkim imenom SMSinfo iznosi null) i deliveryStatus (delivered ili undelivered, potvrda o isporuci od operatera; nastaje samo kod SMS poruka poslanih s mobilnog broja, kod ostalih poruka iznosi null).

Kako poslati više SMS poruka odjednom?

Rate limit dopušta najviše jedan SMS u dvije sekunde po računu i najviše 100 SMS-ova dnevno. Pri slanju više poruka odjednom (primjerice podsjetnika na termine) jednostavnije je između zahtjeva kratko pričekati nego hvatati rate_limited i pokušavati ponovno:

const message = "Podsjećamo vas na sutrašnji 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);
  }

  // Ograničenje je najviše 1 SMS u 2 sekunde po računu - kratka stanka
  // između zahtjeva jednostavnija je od obrade rate_limited i ponovnih pokušaja.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Sažetak: jedan poziv POST /v1/messages s poljima to i body šalje SMS, zaglavlje Idempotency-Key štiti workflow od dvostrukog slanja pri ponavljanju zahtjeva, a cijena se računa po segmentima ovisno o tome sadrži li tekst znakove izvan GSM-7. Ključ držite izvan repozitorija, a prvu poruku pošaljite sami sebi.

Što dalje

Cjelovita referenca REST API-ja (brojevi, pozivi, webhooci, agenti) nalazi se na /docs/api. Želite li znati čim volai preda poruku operateru, bez pollinga GET /v1/messages? Pretplatite se na događaj message.sent - on potvrđuje samo preuzimanje od strane operatera, a ne isporuku na telefon (kod poruka pod zajedničkim imenom volai to ne vidi, vidi gore; poruke poslane s vlastitog mobilnog broja imaju potvrdu o isporuci) - pogledajte dokumentaciju webhookova. A ako uz SMS trebate i telefonski broj koji sam podiže pozive, pogledajte AI recepcionara.

Što dalje