Sms versturen via API in 10 minuten met Node.js

Om vanuit Node.js een sms te versturen, hebt u één POST-verzoek nodig naar https://volai.cz/v1/messages met een header Authorization: Bearer vk_... en een JSON-body met {to, body}. Node 20 heeft fetch standaard ingebouwd, dus u hoeft geen pakket te installeren. Direct hieronder volgt een werkend voorbeeld, inclusief foutafhandeling en idempotentie, zodat een netwerkstoring niet hetzelfde bericht twee keer verstuurt.

Wat u nodig hebt

• Node.js 18 of nieuwer - fetch is vanaf deze versie ingebouwd; wij raden de momenteel ondersteunde LTS-lijn aan (24, per 2 september 2026).
• Een volai-account en een API-sleutel uit het portaal (Instellingen -> API en MCP) in de vorm vk_....
• Minstens één keer tegoed opwaarderen. Sms werkt pas na de eerste opwaardering; het welkomsttegoed dekt het niet - u kunt er gesprekken mee uitproberen, maar geen sms-berichten.
• Een ontvangernummer in Tsjechië of Slowakije (+420 of +421) - naar andere landen versturen wij geen sms.
• Een eigen telefoonnummer hebt u NIET nodig. Berichten gaan uit onder de gedeelde afzendernaam SMSinfo - providers staan in Tsjechische netwerken alleen goedgekeurde afzendernamen toe, dus een eigen afzendernaam is bij de gedeelde afzender niet mogelijk, en ontvangers kunnen niet antwoorden op SMSinfo. Zet uw identiteit daarom in de berichttekst zelf, zoals in het voorbeeld hieronder. Wilt u antwoorden ontvangen, verstuur dan vanaf uw eigen mobiele nummer (een extra optie, zie de opmerking hieronder).

Verstuur uw eerste sms

Het verzoek heeft maar twee velden nodig: to (nummer van de ontvanger) en body (berichttekst). Het antwoord bevat de id van het bericht, de status, de prijs in hellers (priceHal) en het aantal segmenten (segments) - op beide komen we zo terug.

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_UW_SLEUTEL",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Hallo van volai! - Mijn 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 }

Wat kost een sms, en wat zijn segmenten?

Een sms van één segment kost 1.36 CZK exclusief btw (prijs per 2 september 2026). Uit hoeveel segmenten een bericht bestaat, hangt af van de vraag of het tekens buiten het GSM-7-alfabet bevat - providers tellen sms volgens de norm GSM 03.38:

Eén enkel teken buiten het basisalfabet van GSM-7 (typografische aanhalingstekens “ ”, emoji, de meeste niet-Latijnse schriften, Tsjechische tekens zoals ě š č ř ž, maar ook ë of ï) schakelt het HELE bericht om naar UCS-2, ook als het het enige zulke teken in de tekst is. Tip: om zeker binnen één segment te blijven, gebruikt u alleen eenvoudige GSM-7-tekens en rechte aanhalingstekens.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_UW_SLEUTEL",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Goedendag, wij herinneren u aan uw afspraak morgen om 10:00 uur. Past het niet, meld u dan gewoon aan voor een “nieuwe” afspraak.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotentie: veilig opnieuw proberen

Voeg een header Idempotency-Key toe met een tekenreeks naar keuze, bijvoorbeeld een bestel-id. Mislukt het verzoek door een netwerkfout en probeert uw workflow het opnieuw met DEZELFDE header, dan geeft volai het opgeslagen antwoord van de eerste poging terug in plaats van het bericht een tweede keer te versturen - de sleutel is 24 uur geldig.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_UW_SLEUTEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bestelling-4471" \
  -d '{"to": "+420777123456", "body": "Uw bestelling nr. 4471 is ontvangen."}'

Bewaar uw API-sleutel veilig

Een API-sleutel (vk_...) weegt even zwaar als een wachtwoord - wie hem heeft, kan in uw naam berichten versturen en tegoed van uw account uitgeven. Schrijf hem daarom nooit in broncode die u naar een repository commit. Hij hoort in een omgevingsvariabele (process.env.VOLAI_API_KEY in Node.js) of in de secretsmanager van uw hostingprovider.

// .env.local (nooit committen naar de repository)
// VOLAI_API_KEY=vk_uw_sleutel

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

Roep het endpoint aan vanaf een server, nooit vanuit de browser - iedereen kan de sleutel uit de ontwikkelaarstools van de browser halen en op uw account berichten gaan versturen. Lekt een sleutel ooit uit (bijvoorbeeld door een onbedoelde commit), genereer dan in het portaal een nieuwe en trek de oude in - de oude waarde werkt direct niet meer.

Test eerst veilig

Voordat u het versturen van sms in een echt proces inbouwt (bijvoorbeeld bestelbevestigingen), verstuurt u de eerste berichten naar uw eigen telefoonnummer. Dan ziet u precies wat de klant ziet - hoe de afzendernaam SMSinfo eruitziet, hoe lang de bezorging duurt en of de segmentatie zich gedraagt zoals u verwacht. Pas daarna zet u to om naar het nummer van een echte klant.

Wat doet u als de API een fout teruggeeft?

Een foutantwoord heeft altijd de vorm {error: {code, message}}, met een HTTP-status die bij de soort fout past:

Welke statussen kan een bericht hebben?

Het veld status, zowel in de lijst (GET /v1/messages) als bij een enkel bericht, kent vijf mogelijke waarden: pending (opgeslagen, wordt nog verzonden), sent (de provider heeft de verzending bevestigd), failed (de provider heeft het geweigerd - niet in rekening gebracht), unknown (er kwam geen bevestiging van bezorging, meestal een timeout aan de kant van de provider - het wordt volledig in rekening gebracht, omdat het bericht mogelijk is aangekomen) en received (alleen voor inkomende berichten, dus met direction=in; verzonden berichten hebben die status nooit).

Elk bericht bevat bovendien de velden direction (out voor verzonden berichten, in voor ontvangen berichten), smsNumber (het nummer waarvan het bericht is verzonden of waarop het is ontvangen; null bij berichten onder de gedeelde afzendernaam SMSinfo) en deliveryStatus (delivered of undelivered, een bezorgrapport van de provider; het bestaat alleen bij berichten die vanaf een mobiel nummer zijn verzonden en is bij alle andere null).

Hoe verstuurt u een reeks sms-berichten?

De limiet staat maximaal één sms per twee seconden per account toe, tot 100 sms per dag. Verstuurt u meerdere berichten tegelijk (bijvoorbeeld afspraakherinneringen), dan is een korte pauze tussen de verzoeken eenvoudiger dan rate_limited afvangen en opnieuw proberen:

const message = "Herinnering: uw afspraak is morgen - Mijn App";

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

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

  // De limiet is maximaal 1 sms per 2 seconden per account - een korte
  // pauze tussen de verzoeken is eenvoudiger dan rate_limited afvangen
  // en het opnieuw proberen.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Kort samengevat: één POST /v1/messages met to en body verstuurt de sms, een header Idempotency-Key beschermt een workflow die opnieuw probeert tegen dubbel versturen, en de prijs geldt per segment, afhankelijk van de vraag of de tekst tekens buiten GSM-7 bevat. Houd de sleutel buiten uw repository en verstuur het eerste bericht naar uzelf.

Hoe nu verder

De volledige REST-API-referentie (nummers, gesprekken, webhooks, agenten) vindt u op /docs/api. Wilt u meteen weten wanneer volai een bericht aan de provider overdraagt, zonder GET /v1/messages te pollen? Abonneer u dan op het event message.sent - dat bevestigt alleen dat de provider het bericht heeft aangenomen, niet dat het op de telefoon is aangekomen (bij berichten onder de gedeelde naam kan volai dat niet zien, zie hierboven; berichten die vanaf uw eigen mobiele nummer zijn verzonden krijgen wel een bezorgrapport) - zie de webhookdocumentatie. En als u naast sms ook een telefoonnummer nodig hebt dat zelf gesprekken beantwoordt, kijk dan eens naar de AI-receptionist.

Wat nu