Siirry sisältöön

Tekstiviestirajapinta 10 minuutissa Node.js:llä

2. syyskuuta 2026 · lukuaika 6 min · Päivitetty 9. lokakuuta 2026

Tekstiviestin lähettämiseen Node.js:llä riittää yksi POST-kutsu osoitteeseen https://volai.cz/v1/messages, otsake Authorization: Bearer vk_... ja JSON-runko {to, body}. Node 20:ssä fetch on sisäänrakennettu, joten lisäpakettia ei tarvita. Toimiva esimerkki on heti tämän kappaleen alla, virheenkäsittelyn ja idempotenssin kanssa, jotta verkkokatko ei lähetä samaa viestiä kahdesti.

Mitä tarvitaan

  • Node.js 18 tai uudempi - fetch on sisäänrakennettu siitä versiosta alkaen; suosittelemme tuettua ajankohtaista LTS-haaraa (24, tilanne 2. syyskuuta 2026).
  • volai-tili ja API-avain portaalista (Asetukset -> Käyttöoikeus ja API) muodossa vk_....
  • Vähintään yksi saldon lataus. Tekstiviestit lähtevät vasta ensimmäisen latauksen jälkeen, tervetulosaldoa ei voi käyttää niihin - sillä voi kokeilla puheluita, mutta ei tekstiviestejä.
  • Vastaanottajan puhelinnumero Tšekissä tai Slovakiassa (+420 tai +421) tai jossakin Hinnasto-sivulla mainituista muista maista.
  • Omaa puhelinnumeroa EI tarvita. Viestit lähtevät yhteisellä nimellä SMSinfo - tšekkiläisten verkkojen operaattorit sallivat vain hyväksytyt nimet, yhteiselle lähettäjälle ei voi asettaa omaa lähettäjänimeä, eikä SMSinfoon voi vastata. Kerro lähettäjän henkilöllisyys siksi suoraan viestin tekstissä, kuten alla olevassa esimerkissä. Jos vastaaminen pitää olla mahdollista, viesti lähetetään omasta matkapuhelinnumerosta (lisäpalvelu, ks. huomautus alempana).

Ensimmäisen tekstiviestin lähettäminen

Kutsu tarvitsee vain kaksi kenttää: to (vastaanottajan numero) ja body (viestin teksti). Vastauksessa ovat viestin id, status, hinta satasosina (priceHal) ja segmenttien määrä (segments) - molempiin palaamme pian.

javascript
const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_SINUN_AVAIMESI",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Hei volaista! - Oma sovellus",
  }),
});

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 }

Mitä tekstiviesti maksaa ja mitä ovat segmentit?

Yhden segmentin tekstiviesti maksaa 0,0567 € ilman arvonlisäveroa (hinta tilanteen 2. syyskuuta 2026 mukaan). Viestin segmenttien määrä riippuu siitä, sisältääkö se GSM-7-aakkoston ulkopuolisia merkkejä - operaattorit jakavat tekstiviestit standardin GSM 03.38 mukaan:

MerkistöMerkkejä 1. segmentissäMerkkejä seuraavissa osissa
GSM-7 (tavallinen latinalainen teksti, jossa ei ole GSM-7:n ulkopuolisia merkkejä)160153
UCS-2 (GSM-7:n ulkopuolisilla tai ei-latinalaisilla merkeillä)7067

YKSI GSM-7-perusaakkoston ulkopuolinen merkki (esimerkiksi č, š, ž tai á, emoji, useimmat ei-latinalaiset kirjoitusjärjestelmät) riittää, ja KOKO viesti siirtyy UCS-2:een, vaikka koko tekstissä olisi vain yksi tällainen kirjain. Suomen ä, ö ja å kuuluvat GSM-7:ään, joten ne eivät yksin riitä. Vinkki: jos haluat varmasti pysyä yhdessä segmentissä, käytä vain GSM-7-merkkejä.

Esimerkki: viesti, jossa on GSM-7:n ulkopuolisia merkkejä ja yli 70 merkkiä

Tässä viestissä on 128 merkkiä ja se sisältää GSM-7:n ulkopuolisen merkin (á), joten se lasketaan UCS-2:ksi (usean osan viestissä raja on 67 merkkiä segmenttiä kohden) - tuloksena on 2 segmenttiä eli 0,114 €, ei 0,0567 €:

javascript
await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_SINUN_AVAIMESI",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Hei Tomáš, muistutamme huomisesta ajastasi klo 10.00 - jos aika ei sovi, vastaa tähän viestiin, niin sovimme uuden ajan. Kiitos!",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotenssi: kutsun turvallinen uudelleenlähetys

Lähetä lisäksi otsake Idempotency-Key ja siinä vapaavalintainen oma merkkijono, esimerkiksi tilaustunnus. Jos kutsu epäonnistuu verkkokatkon vuoksi ja prosessi toistaa sen SAMALLA otsakkeella, volai palauttaa ensimmäisen yrityksen tallennetun vastauksen eikä lähetä viestiä toista kertaa - avain on voimassa 24 tuntia.

bash
curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_SINUN_AVAIMESI" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tilaus-4471" \
  -d '{"to": "+420777123456", "body": "Tilauksesi nro 4471 on vastaanotettu."}'

API-avaimen turvallinen käsittely

API-avain (vk_...) on yhtä arvokas kuin salasana - sen tuntija voi lähettää viestejä tilin nimissä ja kuluttaa saldon. Siksi sitä ei koskaan kirjoiteta lähdekoodiin, joka viedään reposition. Sen paikka on ympäristömuuttujassa (process.env.VOLAI_API_KEY Node.js:ssä) tai hosting-palveluntarjoajan salaisuuksien hallinnassa.

javascript
// .env.local (älä koskaan vie reposition)
// VOLAI_API_KEY=vk_sinun_avaimesi

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

Kutsu rajapintaa aina palvelimelta, ei selaimesta - avaimen selaimen kehittäjätyökaluista lukeva voi alkaa lähettää omia viestejään tililtä. Jos avain on vuotanut (esimerkiksi vahingossa commitiin), luo portaalissa uusi ja estä vanha - vanha arvo lakkaa toimimasta heti.

Kokeile ensin turvallisesti

Ennen kuin tekstiviestien lähetys kytketään tuotantoprosessiin (esimerkiksi tilausvahvistukseen), lähetä ensimmäiset viestit omaan puhelinnumeroon. Silloin näkyy täsmälleen se, minkä asiakas näkee - miltä lähettäjä SMSinfo näyttää, kuinka pitkä toimitusaika on ja lasketaanko segmentit odotetusti. Vasta sen jälkeen vaihda to asiakkaan oikeaan numeroon.

Mitä tehdä, kun rajapinta palauttaa virheen?

Epäonnistunut vastaus on aina muotoa {error: {code, message}}, ja HTTP-tila riippuu virheen tyypistä:

TilaKoodiMitä se tarkoittaa
400invalid_numberEi kelvollinen tšekkiläinen tai slovakialainen puhelinnumero.
400invalid_bodyViestin tekstin pituuden on oltava 1-765 merkkiä.
400unsupported_countryNumero Tšekin ja Slovakian ulkopuolella, sinne emme lähetä tekstiviestejä.
400recipient_cannot_receive_smsLankanumero - tekstiviesti ei menisi perille. Mitään ei veloiteta.
402insufficient_creditSaldo ei riitä viestin kaikkien segmenttien hintaan, tai tilille ei ole vielä ladattu saldoa - tekstiviestit lähtevät vasta ensimmäisen latauksen jälkeen, tervetulosaldoa ei voi käyttää niihin.
429rate_limitedYli 1 tekstiviesti 2 sekunnissa tai yli 100 tekstiviestiä tiliä kohden vuorokaudessa.
502send_failedPuhelinverkko hylkäsi kutsun. Saldoa ei veloiteta, yritä uudelleen.
502send_unknownViesti luovutettiin verkolle, mutta vahvistus jäi saamatta - viesti veloitetaan, älä lähetä sitä uudelleen umpimähkään.

Mitä tiloja viestillä voi olla?

Kenttä status luettelossa (GET /v1/messages) ja yksittäisen viestin tiedoissa saa viisi arvoa: pending (tallennettu, vielä lähtemättä), sent (operaattori on vahvistanut lähetyksen), failed (operaattori hylkäsi - ei veloiteta), unknown (toimitusvahvistus jäi saamatta, tyypillisesti operaattorin aikakatkaisu - veloitetaan silti täysimääräisesti, koska viesti on voinut mennä perille) ja received (vain vastaanotetuille viesteille eli kun direction=in; lähetetyillä viesteillä sitä ei ole).

Jokaisella viestillä on myös kentät direction (out lähetetyille, in vastaanotetuille), smsNumber (numero, josta viesti lähti tai johon se saapui; yhteisellä nimellä SMSinfo lähetetyillä viesteillä se on null) ja deliveryStatus (delivered tai undelivered, operaattorin toimitusraportti; syntyy vain matkapuhelinnumerosta lähetetyille tekstiviesteille, muilla viesteillä se on null).

Miten monta tekstiviestiä lähetetään kerralla?

Nopeusraja sallii enintään yhden tekstiviestin kahdessa sekunnissa tiliä kohden ja enintään 100 tekstiviestiä vuorokaudessa. Kun viestejä lähetetään kerralla monta (esimerkiksi tapaamismuistutuksia), on yksinkertaisempaa odottaa hetki kutsujen välillä kuin napata rate_limited ja yrittää uudelleen:

javascript
const message = "Muistutus huomisesta ajastasi - Oma sovellus";

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

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

  // Raja on enintään 1 tekstiviesti 2 sekunnissa tiliä kohden - lyhyt tauko
  // kutsujen välillä on yksinkertaisempi kuin rate_limited-virheen
  // käsittely ja uudelleenyritys.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Tekstiviestejä vastaanottaa kahdenlaiset numerot

volain puhenumerot eivät vastaanota tekstiviestejä, joten vastaus yhteisellä nimellä SMSinfo lähetettyyn viestiin ei ilmesty minnekään. Tekstiviestien vastaanottamiseen ja lähettämiseen omasta numerosta on lisäpalvelu matkapuhelinnumero: tšekkiläinen matkapuhelinnumero pelkkiä tekstiviestejä varten, ilman puheluita, 12,09 € 30 päivältä ilman arvonlisäveroa. Vaihtoehto on numero puheluille ja tekstiviesteille: lankanumero Prahassa, jolla vastaanotetaan sekä puheluita että tekstiviestejä, 2,05 € 30 päivältä ilman arvonlisäveroa (maksu veloitetaan vasta aktivoinnin jälkeen, johon menee yleensä enintään 1 arkipäivä). Kummassakin vastaanotetut tekstiviestit sisältyvät hintaan. Vastaanotetut viestit luetaan kutsulla GET /v1/messages?direction=in, MCP-työkalulla list_messages tai webhookilla message.received ja säilytämme ne 90 päivää; matkapuhelinnumerosta lähettäminen maksaa 0,0792 € segmentiltä, palvelusta numero puheluille ja tekstiviesteille 0,105 € segmentiltä, ja viestit kulkevat vain tšekkiläisiin numeroihin. Numerosta tekstiviestit lähetetään kentällä fromNumber kutsussa POST /v1/messages (numero haetaan kutsulla GET /v1/sms-numbers tai kutsulla GET /v1/voice-sms-numbers). Numerosta lähettämisen päiväkatto on 20 tekstiviestiä tiliä kohden numeron oston jälkeisten ensimmäisten 30 päivän ajan, sen jälkeen 50. Yhdellä tilillä voi olla enintään kaksi matkapuhelinnumeroa, ja ne voi ostaa vasta saldon ensimmäisen latauksen jälkeen; sama koskee palvelua numero puheluille ja tekstiviesteille: enintään kaksi tiliä kohden, ja ne voi tilata vasta ensimmäisen latauksen jälkeen. Palveluiden (pankit, Google ja vastaavat) vahvistuskoodeja emme takaa, numerot on tarkoitettu ihmisten väliseen viestintään ja vastaanoton olemme todentaneet O2:n verkossa. Yksityiskohdat ovat API-dokumentaation osioissa Matkapuhelinnumerot ja numero puheluille ja tekstiviesteille. Milloin Twilio on parempi valinta tekstiviestien vastaanottoon, kerrotaan Twilion ja volain vertailussa.

Yhteenveto: yksi kutsu POST /v1/messages kentillä to ja body lähettää tekstiviestin, otsake Idempotency-Key suojaa prosessin kaksoislähetykseltä, kun kutsu toistetaan, ja hinta lasketaan segmenttikohtaisesti sen mukaan, sisältääkö teksti GSM-7:n ulkopuolisia merkkejä. Pidä avain poissa repositoriosta ja lähetä ensimmäinen viesti itsellesi.

Mitä seuraavaksi

REST-rajapinnan täydellinen referenssi (numerot, puhelut, webhookit, agentit) on osoitteessa /docs/api. Haluatko tietää heti, kun volai on luovuttanut viestin operaattorille, ilman että kyselet GET /v1/messages? Tilaa tapahtuma message.sent - se vahvistaa vain, että operaattori on ottanut viestin vastaan, ei toimitusta puhelimeen (yhteisellä nimellä lähetetyistä viesteistä volai ei sitä näe, ks. yllä; omasta matkapuhelinnumerosta lähetetyillä viesteillä on toimitusraportti) - ks. webhookien dokumentaatio. Ja jos tekstiviestien lisäksi tarvitaan puhelinnumero, joka vastaa puheluihin itse, tutustu tekoälyvastaanottovirkailijaan.

Kokeile volaita - ensimmäiset 2 € saat meiltä

Tili luodaan minuutissa, ja aloitussaldo puheluihin ja yhteen numeroon on heti käytettävissä - tekstiviestejä voi lähettää ensimmäisen latauksen jälkeen.

Kokeile ilmaiseksi