SMS-Versand per API in 10 Minuten mit Node.js

Um aus Node.js eine SMS zu senden, genügt eine einzige POST-Anfrage an https://volai.cz/v1/messages mit dem Header Authorization: Bearer vk_... und einem JSON-Body aus {to, body}. Node 20 bringt fetch von Haus aus mit, Sie müssen also kein Paket installieren. Ein funktionierendes Beispiel folgt direkt darunter, samt Fehlerbehandlung und Idempotenz, damit ein Netzwerkaussetzer nicht dieselbe Nachricht doppelt versendet.

Was Sie brauchen

• Node.js 18 oder neuer - fetch ist seit dieser Version eingebaut; wir empfehlen die aktuell unterstützte LTS-Linie (24, Stand 2. September 2026).
• Ein volai-Konto und einen API-Schlüssel aus dem Portal (Einstellungen -> API und MCP) in der Form vk_....
• Mindestens eine Guthabenaufladung. SMS funktionieren erst nach der ersten Aufladung; das Startguthaben deckt sie nicht ab - Anrufe können Sie damit ausprobieren, Textnachrichten nicht.
• Eine Empfängernummer in Tschechien oder in der Slowakei (+420 oder +421) - in andere Länder versenden wir keine SMS.
• Eine eigene Telefonnummer brauchen Sie NICHT. Die Nachrichten gehen unter dem gemeinsamen Absendernamen SMSinfo hinaus - die Netzbetreiber lassen in tschechischen Netzen nur genehmigte Absendernamen zu, ein eigener Absendername ist beim gemeinsamen Absender daher nicht möglich, und auf SMSinfo kann der Empfänger nicht antworten. Schreiben Sie Ihre Identität deshalb direkt in den Nachrichtentext, wie im Beispiel unten. Wenn Antworten möglich sein sollen, senden Sie von Ihrer eigenen Mobilnummer (ein Zusatzangebot, siehe den Hinweis unten).

Die erste SMS senden

Die Anfrage braucht nur zwei Felder: to (Empfängernummer) und body (Nachrichtentext). Die Antwort liefert die id der Nachricht, ihren status, den Preis in Hellern (priceHal) und die Anzahl der Segmente (segments) - auf beides kommen wir gleich zurück.

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

Was kostet eine SMS, und was sind Segmente?

Eine SMS mit einem Segment kostet 1,36 kr ohne MwSt. (Preis mit Stand 2. September 2026). Wie viele Segmente eine Nachricht belegt, hängt davon ab, ob sie Zeichen außerhalb des GSM-7-Alphabets enthält - die Netzbetreiber zählen SMS nach dem Standard GSM 03.38:

Ein einziges Zeichen außerhalb des GSM-7-Grundalphabets (typografische Anführungszeichen „ “, Emoji, die meisten nicht lateinischen Schriften, tschechische Zeichen wie ě š č ř ž) schaltet die GESAMTE Nachricht auf UCS-2 um, auch wenn es das einzige derartige Zeichen im Text ist. Umlaute und ß gehören dagegen zu GSM-7. Tipp: Um zuverlässig in einem Segment zu bleiben, verwenden Sie nur einfache GSM-7-Zeichen und gerade Anführungszeichen.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_IHR_SCHLUESSEL",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Guten Tag, wir erinnern Sie an Ihren Termin morgen um 10:00 Uhr. Passt er nicht, melden Sie sich einfach für einen „neuen“ Termin.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotenz: Anfragen sicher wiederholen

Fügen Sie einen Idempotency-Key-Header mit einer beliebigen selbst gewählten Zeichenfolge hinzu, etwa einer Bestell-ID. Schlägt die Anfrage wegen eines Netzwerkfehlers fehl und Ihr Workflow wiederholt sie mit demselben Header, liefert volai die gespeicherte Antwort des ersten Versuchs zurück, statt die Nachricht ein zweites Mal zu senden - der Schlüssel gilt 24 Stunden.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bestellung-4471" \
  -d '{"to": "+420777123456", "body": "Ihre Bestellung Nr. 4471 wurde angenommen."}'

API-Schlüssel sicher aufbewahren

Ein API-Schlüssel (vk_...) wiegt so schwer wie ein Passwort - wer ihn kennt, kann in Ihrem Namen Nachrichten senden und Guthaben Ihres Kontos ausgeben. Schreiben Sie ihn daher niemals in Quellcode, den Sie in ein Repository committen. Er gehört in eine Umgebungsvariable (process.env.VOLAI_API_KEY in Node.js) oder in den Secrets-Manager Ihres Hostinganbieters.

// .env.local (niemals in das Repository committen)
// VOLAI_API_KEY=vk_ihr_schluessel

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

Rufen Sie den Endpunkt immer von einem Server aus auf, nie aus dem Browser - jeder könnte den Schlüssel in den Entwicklerwerkzeugen des Browsers auslesen und auf Ihrem Konto eigene Nachrichten versenden. Ist ein Schlüssel einmal abgeflossen (etwa durch einen versehentlichen Commit), erzeugen Sie im Portal einen neuen und widerrufen den alten - der alte Wert funktioniert sofort nicht mehr.

Zuerst gefahrlos ausprobieren

Bevor Sie den SMS-Versand in einen echten Prozess einbauen (etwa Bestellbestätigungen), schicken Sie die ersten Nachrichten an Ihre eigene Telefonnummer. So sehen Sie genau das, was der Kunde sieht - wie der Absendername SMSinfo aussieht, wie lange die Zustellung dauert und ob die Segmentierung so ausfällt, wie Sie es erwarten. Erst dann stellen Sie to auf eine echte Kundennummer um.

Was tun, wenn die API einen Fehler zurückgibt?

Eine fehlgeschlagene Antwort hat immer die Form {error: {code, message}} mit einem HTTP-Status passend zur Art des Fehlers:

Welche Status kann eine Nachricht haben?

Das Feld status nimmt sowohl in der Liste (GET /v1/messages) als auch in der Einzelansicht einer Nachricht fünf Werte an: pending (gespeichert, wird noch gesendet), sent (der Netzbetreiber hat den Versand bestätigt), failed (vom Netzbetreiber abgelehnt - wird nicht berechnet), unknown (die Zustellbestätigung ist ausgeblieben, typischerweise ein Timeout beim Netzbetreiber - wird dennoch in voller Höhe berechnet, weil die Nachricht angekommen sein kann) und received (nur bei eingehenden Nachrichten, also mit direction=in; gesendete Nachrichten haben ihn nie).

Jede Nachricht trägt außerdem die Felder direction (out bei gesendeten, in bei empfangenen), smsNumber (die Nummer, von der die Nachricht gesendet oder auf der sie empfangen wurde; bei Nachrichten unter dem gemeinsamen Namen SMSinfo ist es null) und deliveryStatus (delivered oder undelivered, ein Zustellbericht des Netzbetreibers; er entsteht nur bei SMS, die von einer Mobilnummer gesendet wurden, bei allen anderen Nachrichten ist er null).

Wie versende ich viele SMS auf einmal?

Das Ratenlimit erlaubt höchstens eine SMS alle zwei Sekunden pro Konto und höchstens 100 SMS pro Tag. Beim Versand mehrerer Nachrichten auf einmal (etwa Terminerinnerungen) ist eine kurze Pause zwischen den Anfragen einfacher, als rate_limited abzufangen und es erneut zu versuchen:

const message = "Erinnerung: Ihr Termin ist morgen - Meine App";

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

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

  // Das Limit liegt bei höchstens 1 SMS pro 2 Sekunden und Konto - eine
  // kurze Pause zwischen den Anfragen ist einfacher, als rate_limited
  // abzufangen und es erneut zu versuchen.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Kurz gefasst: Ein einziges POST /v1/messages mit den Feldern to und body sendet die SMS, der Header Idempotency-Key schützt einen Workflow vor doppeltem Versand bei wiederholten Anfragen, und der Preis wird pro Segment berechnet, je nachdem, ob der Text Zeichen außerhalb von GSM-7 enthält. Halten Sie den Schlüssel aus dem Repository heraus und senden Sie die erste Nachricht an sich selbst.

Wie geht es weiter

Die vollständige REST-API-Referenz (Nummern, Anrufe, Webhooks, Agenten) finden Sie unter /docs/api. Möchten Sie sofort wissen, wann volai eine Nachricht an den Netzbetreiber übergibt, ohne GET /v1/messages abzufragen? Abonnieren Sie das Ereignis message.sent - es bestätigt nur die Annahme durch den Netzbetreiber, nicht die Zustellung auf dem Telefon (bei Nachrichten unter dem gemeinsamen Namen sieht volai das nicht, siehe oben; Nachrichten, die von Ihrer eigenen Mobilnummer gesendet wurden, haben einen Zustellbericht) - siehe die Webhook-Dokumentation. Und wenn Sie neben SMS auch eine Telefonnummer brauchen, die selbst Anrufe annimmt, werfen Sie einen Blick auf die KI-Rezeption.

Wie es weitergeht