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 -
fetchon 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 (
+420tai+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.
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ä) | 160 | 153 |
| UCS-2 (GSM-7:n ulkopuolisilla tai ei-latinalaisilla merkeillä) | 70 | 67 |
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 €:
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.
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.
// .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ä:
| Tila | Koodi | Mitä se tarkoittaa |
|---|---|---|
| 400 | invalid_number | Ei kelvollinen tšekkiläinen tai slovakialainen puhelinnumero. |
| 400 | invalid_body | Viestin tekstin pituuden on oltava 1-765 merkkiä. |
| 400 | unsupported_country | Numero Tšekin ja Slovakian ulkopuolella, sinne emme lähetä tekstiviestejä. |
| 400 | recipient_cannot_receive_sms | Lankanumero - tekstiviesti ei menisi perille. Mitään ei veloiteta. |
| 402 | insufficient_credit | Saldo 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. |
| 429 | rate_limited | Yli 1 tekstiviesti 2 sekunnissa tai yli 100 tekstiviestiä tiliä kohden vuorokaudessa. |
| 502 | send_failed | Puhelinverkko hylkäsi kutsun. Saldoa ei veloiteta, yritä uudelleen. |
| 502 | send_unknown | Viesti 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:
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.
Mitä seuraavaksi
Aiheeseen liittyvät artikkelit
Viisi kysymystä ennen tekoälyvastaanottovirkailijan hankintaa
Hinta, käyttöönotto 5 minuutissa, numeron siirto O2:lta, T-Mobilelta ja Vodafonelta, slovakialaiset numerot ja ALV: viisi vastausta suoraan volain hinnastosta ja asetuksista.
Soita asiakkaalle n8n-työnkulusta
Soita asiakkaalle suoraan n8n:stä: HTTP Request -solmu volain REST API:in, työnkulun tiedot agentin kehotteeseen ja puhelun tulos takaisin webhookilla.
Näin annat Claude Codelle puhelinnumeron MCP:n kautta
Asenna volai Claude Codeen yhdellä komennolla, anna sille puhelinnumero ja anna sen soittaa ja lähettää tekstiviestejä pelkällä kehotteella - ilman koodia ja ilman API-dokumentaatiota.