SMS-ide saatmine API kaudu Node.js-iga 10 minutiga

SMS-i saatmiseks Node.js-ist on vaja üht POST-päringut aadressile https://volai.cz/v1/messages päisega Authorization: Bearer vk_... ja JSON-kehaga {to, body}. Node 20-s on fetch sisse ehitatud, seega pole vaja midagi paigaldada. Töötav näide on kohe allpool, sealhulgas veakäsitlus ja idempotentsus, et võrgukatkestus ei saadaks sama sõnumit kaks korda.

Mida vaja läheb

• Node.js 18 või uuem - fetch on sisse ehitatud sellest versioonist alates; soovitame praegu toetatud LTS-haru (24, seisuga 2. september 2026).
• volai konto ja API-võti portaalist (Seaded -> API ja MCP), kujul vk_....
• Vähemalt üks saldo täiendus. SMS-id nõuavad esimest täiendust; tervitussaldo neid ei kata - sellega saab proovida kõnesid, mitte SMS-e.
• Vastuvõtja number Tšehhis või Slovakkias (+420 või +421) - teistesse riikidesse me SMS-e ei saada.
• Teil EI ole vaja oma telefoninumbrit. Sõnumid lähevad välja jagatud saatjanime SMSinfo all - Tšehhi võrkudes lubavad operaatorid ainult kinnitatud saatjanimesid, seega jagatud saatjaga oma saatjanime kasutada ei saa ja vastuvõtjad ei saa SMSinfo-le vastata. Kirjutage oma nimi sõnumi tekstis, nagu allolevas näites. Kui soovite vastuseid, saatke oma mobiilinumbrilt (see on täiendus, vt allpool olevat märkust).

Saatke oma esimene SMS

Päring vajab ainult kahte välja: to (vastuvõtja number) ja body (sõnumi tekst). Vastus tagastab sõnumi id, selle status, hinna krooni sajandikes (priceHal) ja segmentide arvu (segments) - mõlema kohta lähemalt allpool.

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_TEIE_VOTI",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Tere volai-st! - Minu rakendus",
  }),
});

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 }

Mis maksavad SMS-id ja mis on segmendid?

Ühe segmendiga SMS maksab 1,36 kr ilma käibemaksuta (hind 2. septembri 2026 seisuga). Mitu segmenti sõnum võtab, sõltub sellest, kas see sisaldab märke väljaspool GSM-7 tähestikku - operaatorid jagavad SMS-id segmentideks GSM 03.38 standardi järgi:

Üks ainus märk väljaspool GSM-7 baastähestikku (diakriitikaga tähed, emotikonid, enamik mitteladina kirju) lülitab KOGU sõnumi UCS-2 peale, isegi kui see on tekstis ainus selline märk. Eesti keeles teeb seda näiteks täht õ. Soovitus: et kindlalt ühe segmendi sisse mahtuda, kasutage ainult tavalisi GSM-7 märke.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_TEIE_VOTI",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Tänane õhtu on õnnelik ning see lause on kindlasti pikem kui seitsekümmend märki, mistõttu läheb see teise segmenti.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotentsus: ohutu kordamine

Lisage päis Idempotency-Key mis tahes teie valitud sõnega, näiteks tellimuse ID-ga. Kui päring ebaõnnestub võrguvea tõttu ja teie töövoog kordab seda SAMA päisega, tagastab volai esimese katse salvestatud vastuse, mitte ei saada sõnumit teist korda - võti kehtib 24 tundi.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_TEIE_VOTI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tellimus-4471" \
  -d '{"to": "+420777123456", "body": "Teie tellimus nr 4471 on kätte saadud."}'

Hoidke oma API-võti turvaliselt

API-võti (vk_...) kaalub sama palju kui parool - igaüks, kes seda omab, saab teie nimel sõnumeid saata ja saldot kulutada. Ärge kunagi kirjutage seda lähtekoodi, mille hoidlasse lisate. See kuulub keskkonnamuutujasse (process.env.VOLAI_API_KEY Node.js-is) või mis tahes saladuste halduresse, mida teie majutusteenus pakub.

// .env.local (ärge seda faili kunagi hoidlasse lisage)
// VOLAI_API_KEY=vk_teie_voti

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

Kutsuge lõpp-punkti serverist, mitte kunagi brauserist - igaüks saaks võtme brauseri arendajatööriistadest välja lugeda ja hakata teie kontolt sõnumeid saatma. Kui võti peaks kunagi lekkima (näiteks kogemata lisatud hoidlasse), looge portaalis uus ja tühistage vana - vana väärtus lakkab kohe töötamast.

Proovige kõigepealt ohutult

Enne kui ühendate SMS-ide saatmise päris protsessiga (näiteks tellimuste kinnitused), saatke esimesed sõnumid oma enda telefoninumbrile. Näete täpselt seda, mida klient näeb - kuidas saatjanimi SMSinfo välja näeb, kui kaua kohaletoimetamine aega võtab ja kas segmentimine käitub nii, nagu ootate. Alles siis vahetage to päris kliendi numbri vastu.

Mida teha, kui API tagastab vea?

Veavastusel on alati kuju {error: {code, message}}, HTTP-olekuga, mis vastab tõrke liigile:

Millised olekud võivad sõnumil olla?

Väljal status, nii loendis (GET /v1/messages) kui ka üksikus sõnumis, on viis võimalikku väärtust: pending (salvestatud, veel saadetakse), sent (operaator kinnitas saatmise), failed (operaator lükkas tagasi - ei arveldata), unknown (kohaletoimetamise kinnitust ei tulnud, tavaliselt operaatori poole ajalõpp - see arveldatakse täies mahus, sest sõnum võis kohale jõuda) ja received (ainult sissetulevatel sõnumitel, see tähendab direction=in korral; saadetud sõnumitel seda kunagi ei ole).

Igal sõnumil on ka väljad direction (out saadetud sõnumite, in vastuvõetud sõnumite jaoks), smsNumber (number, mille pealt sõnum saadeti või millele see vastu võeti; jagatud saatjanime SMSinfo all saadetud sõnumite puhul null) ja deliveryStatus (delivered või undelivered, operaatori kohaletoimetamisaruanne; see on olemas ainult mobiilinumbrilt saadetud sõnumitel ja kõigil teistel on null).

Kuidas saata SMS-ide partiid?

Kiirusepiirang lubab konto kohta kuni ühe SMS-i iga kahe sekundi järel, kuni 100 SMS-i päevas. Mitme sõnumi korraga saatmisel (näiteks kohtumiste meeldetuletused) on lühike paus päringute vahel lihtsam kui rate_limited püüdmine ja kordamine:

const message = "Meeldetuletus: homme on Teie broneeritud aeg - Minu rakendus";

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

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

  // Piirang on kuni 1 SMS 2 sekundi kohta konto kohta - lühike
  // paus päringute vahel on lihtsam kui rate_limited korduskatsete käsitlemine.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Lühidalt: üks POST /v1/messages kutse väljadega to ja body saadab SMS-i, päis Idempotency-Key kaitseb korduskatseid tegevat töövoogu topeltsaatmise eest ja hind on segmendi kohta, olenevalt sellest, kas tekst sisaldab märke väljaspool GSM-7. Hoidke võti oma hoidlast eemal ja saatke esimene sõnum iseendale, enne kui saadate kellelegi teisele.

Mis edasi

Täielik REST API viide (numbrid, kõned, veebikonksud, agendid) asub aadressil /docs/api. Tahate teada hetke, mil volai annab sõnumi operaatorile üle, ilma päringut GET /v1/messages korduvalt tegemata? Tellige sündmus message.sent - see kinnitab ainult, et operaator võttis sõnumi vastu, mitte seda, et see telefonini jõudis (volai ei näe seda jagatud nime all saadetud sõnumite puhul, vt eespool; teie enda mobiilinumbrilt saadetud sõnumitel on kohaletoimetamisaruanne) - vt veebikonksude dokumentatsiooni. Ja kui vajate telefoninumbrit, mis vastab ka kõnedele, mitte ainult SMS-idele, vaadake AI vastuvõtjat.

Mis edasi