Sms-gateway via API på 10 minuter i Node.js

För att skicka ett sms från Node.js räcker ett enda POST-anrop till https://volai.cz/v1/messages med rubriken Authorization: Bearer vk_... och en JSON-kropp {to, body}. Node 20 har fetch inbyggt, så inget extra paket behövs. Ett fungerande exempel finns direkt under det här stycket, med felhantering och idempotens, så att ett nätverksavbrott inte skickar samma meddelande två gånger.

Det här behövs

• Node.js 18 eller nyare - fetch är inbyggt från och med den versionen; vi rekommenderar den aktuella LTS-linjen som stöds (24, läge per 2 september 2026).
• Ett konto hos volai och en API-nyckel från portalen (Inställningar -> API och MCP) i formen vk_....
• Minst en påfyllning av saldot. Sms går iväg först efter den första påfyllningen, välkomstsaldot kan inte användas till dem - samtal går att prova med det, textmeddelanden inte.
• Mottagarens telefonnummer i Tjeckien eller Slovakien (+420 eller +421) - till andra länder skickar vi inte sms.
• Något eget telefonnummer behövs INTE. Meddelandena går ut under det delade namnet SMSinfo - operatörerna i de tjeckiska näten tillåter bara godkända namn, ett eget avsändarnamn kan inte ställas in för den delade avsändaren, och på SMSinfo kan mottagaren inte svara. Ange därför identiteten direkt i meddelandetexten, som i exemplet nedan. Om det ska gå att svara, skicka meddelandet från ett eget mobilnummer (tillägg, se anmärkningen längre ner).

Skicka det första sms:et

Anropet behöver bara två fält: to (mottagarens nummer) och body (meddelandetexten). Svaret innehåller meddelandets id, status, priset i hundradelar (priceHal) och antalet segment (segments) - till båda kommer vi strax tillbaka.

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_DIN_NYCKEL",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Hej från volai! - Min app",
  }),
});

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 }

Vad kostar sms och vad är segment?

Ett sms i ett segment kostar 1,36 kr exklusive moms (pris enligt läget per 2 september 2026). Hur många segment ett meddelande tar beror på om det innehåller tecken utanför GSM-7-alfabetet - operatörerna delar upp sms enligt standarden GSM 03.38:

Det räcker med ETT tecken utanför det grundläggande GSM-7-alfabetet (tecken med diakritiska tecken, emoji, de flesta icke-latinska skrifter) så växlar HELA meddelandet till UCS-2, även om bara en enda bokstav i texten har ett diakritiskt tecken. Tips: för att säkert rymmas i ett segment, skriv utan diakritiska tecken.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_DIN_NYCKEL",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Hej, vi påminner om din tid i morgon kl. 10:00 - passar den inte, svara på det här meddelandet så hittar vi en annan tid. Tack!",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotens: säker omsändning av anropet

Skicka dessutom rubriken Idempotency-Key med en valfri egen sträng, till exempel beställnings-ID. Om anropet misslyckas på grund av ett nätverksavbrott och flödet upprepar det med SAMMA rubrik returnerar volai det sparade svaret från det första försöket och skickar inte meddelandet en andra gång - nyckeln gäller i 24 timmar.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_DIN_NYCKEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bestallning-4471" \
  -d '{"to": "+420777123456", "body": "Din beställning nr 4471 har tagits emot."}'

Hantera API-nyckeln säkert

API-nyckeln (vk_...) väger lika tungt som ett lösenord - den som känner till den kan skicka meddelanden i kontots namn och göra av med saldot. Skriv den därför aldrig i källkod som checkas in i repot. Den hör hemma i en miljövariabel (process.env.VOLAI_API_KEY i Node.js) eller i den hemlighetshanterare som hostingleverantören erbjuder.

// .env.local (checka aldrig in i repot)
// VOLAI_API_KEY=vk_din_nyckel

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

Anropa endpointen alltid från servern, inte från webbläsaren - den som läser nyckeln i webbläsarens utvecklarverktyg kan börja skicka egna meddelanden från kontot. Om nyckeln har läckt (till exempel av misstag i en commit), skapa en ny i portalen och spärra den gamla - det gamla värdet slutar fungera omedelbart.

Prova först på ett säkert sätt

Innan sms-utskicket kopplas till en skarp process (till exempel orderbekräftelse), skicka de första meddelandena till ett eget telefonnummer. Då syns exakt det kunden kommer att se - hur avsändaren SMSinfo ser ut, hur lång leveranstiden är och om segmenten räknas som väntat. Byt först därefter ut to mot kundens riktiga nummer.

Vad gör man när API:et returnerar ett fel?

Ett misslyckat svar har alltid formen {error: {code, message}} och en HTTP-status som beror på typen av fel:

Vilka statusar kan ett meddelande ha?

Fältet status i listan (GET /v1/messages) och i detaljen för ett enskilt meddelande antar fem värden: pending (sparat, skickas ännu), sent (operatören har bekräftat avsändningen), failed (operatören avvisade - debiteras inte), unknown (leveransbekräftelsen uteblev, typiskt en timeout hos operatören - debiteras ändå fullt ut, eftersom meddelandet kan ha nått fram) och received (bara för mottagna meddelanden, alltså med direction=in; skickade meddelanden har det inte).

Varje meddelande har också fälten direction (out för skickade, in för mottagna), smsNumber (numret som meddelandet gick ut från eller kom in på; för meddelanden under det delade namnet SMSinfo är det null) och deliveryStatus (delivered eller undelivered, leveranskvitto från operatören; uppstår bara för sms som skickats från ett mobilnummer, för övriga meddelanden är det null).

Hur skickar man många sms på en gång?

Hastighetsgränsen tillåter högst ett sms per två sekunder och konto och högst 100 sms per dag. Vid utskick av flera meddelanden på en gång (till exempel påminnelser om möten) är det enklare att vänta en kort stund mellan anropen än att fånga rate_limited och försöka igen:

const message = "Påminnelse om din tid i morgon - Min app";

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

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

  // Gränsen är högst 1 sms per 2 sekunder och konto - en kort paus mellan
  // anropen är enklare än att hantera rate_limited och försöka igen.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Sammanfattning: ett anrop till POST /v1/messages med fälten to och body skickar ett sms, rubriken Idempotency-Key skyddar flödet mot dubbla utskick när anropet upprepas, och priset räknas per segment beroende på om texten innehåller tecken utanför GSM-7. Håll nyckeln utanför repot och skicka det första meddelandet till dig själv.

Vad händer härnäst

Den fullständiga referensen till REST-API:et (nummer, samtal, webhooks, agenter) finns på /docs/api. Vill du veta direkt när volai lämnat över meddelandet till operatören, utan att polla GET /v1/messages? Prenumerera på händelsen message.sent - den bekräftar bara att operatören tagit emot meddelandet, inte leverans till telefonen (för meddelanden under det delade namnet ser volai det inte, se ovan; meddelanden som skickats från ett eget mobilnummer har leveranskvitto) - se dokumentationen om webhooks. Och om förutom sms också ett telefonnummer som självt svarar på samtal behövs, ta en titt på AI-receptionisten.

Vad händer härnäst