Πύλη SMS μέσω API σε 10 λεπτά με Node.js

Για να στείλετε ένα SMS από το Node.js, αρκεί ένα αίτημα POST στο https://volai.cz/v1/messages με κεφαλίδα Authorization: Bearer vk_... και σώμα JSON {to, body}. Το Node 20 διαθέτει ενσωματωμένο το fetch, οπότε δεν χρειάζεται να εγκαταστήσετε κανένα πακέτο. Ένα λειτουργικό παράδειγμα ακολουθεί αμέσως παρακάτω, με χειρισμό σφαλμάτων και idempotency, ώστε ένα πρόβλημα δικτύου να μη στείλει το ίδιο μήνυμα δύο φορές.

Τι θα χρειαστείτε

• Node.js 18 ή νεότερο - το fetch είναι ενσωματωμένο από αυτή την έκδοση· προτείνουμε την τρέχουσα υποστηριζόμενη γραμμή LTS (24, κατάσταση στις 2 Σεπτεμβρίου 2026).
• Έναν λογαριασμό στο volai και ένα κλειδί API από την πύλη (Ρυθμίσεις -> API και MCP) της μορφής vk_....
• Τουλάχιστον μία φόρτιση υπολοίπου. Τα SMS λειτουργούν μόνο μετά την πρώτη φόρτιση, το υπόλοιπο καλωσορίσματος δεν τα καλύπτει - με αυτό δοκιμάζετε κλήσεις, όχι μηνύματα.
• Τηλεφωνικό αριθμό παραλήπτη στην Τσεχία ή τη Σλοβακία (+420 ή +421) - σε άλλες χώρες δεν στέλνουμε SMS.
• ΔΕΝ χρειάζεστε δικό σας τηλεφωνικό αριθμό. Τα μηνύματα φεύγουν με το κοινόχρηστο όνομα SMSinfo - οι πάροχοι στα τσεχικά δίκτυα επιτρέπουν μόνο εγκεκριμένα ονόματα αποστολέα, οπότε με τον κοινόχρηστο αποστολέα δεν μπορείτε να ορίσετε δικό σας όνομα και ο παραλήπτης δεν μπορεί να απαντήσει στο SMSinfo. Γράψτε λοιπόν την ταυτότητά σας απευθείας στο κείμενο του μηνύματος, όπως στο παράδειγμα παρακάτω. Αν θέλετε να μπορεί να σας απαντήσει, στείλτε το μήνυμα από δικό σας αριθμό κινητού (πρόσθετο, δείτε την επισήμανση παρακάτω).

Στείλτε το πρώτο σας SMS

Το αίτημα χρειάζεται μόνο δύο πεδία: to (αριθμός παραλήπτη) και body (κείμενο μηνύματος). Η απάντηση επιστρέφει το id του μηνύματος, το status, την τιμή σε εκατοστά της κορώνας (priceHal) και τον αριθμό τμημάτων (segments) - και για τα δύο θα μιλήσουμε σε λίγο.

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_TO_KLEIDI_SAS",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Γεια σας από το volai! - Η εφαρμογή μου",
  }),
});

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 }

Πόσο κοστίζουν τα SMS και τι είναι τα τμήματα;

Ένα SMS ενός τμήματος κοστίζει 1,36 kr χωρίς ΦΠΑ (τιμή ισχύος στις 2 Σεπτεμβρίου 2026). Το πόσα τμήματα καταλαμβάνει ένα μήνυμα εξαρτάται από το αν περιέχει χαρακτήρες εκτός του αλφαβήτου GSM-7 - οι πάροχοι χωρίζουν τα SMS σύμφωνα με το πρότυπο GSM 03.38:

Αρκεί ΕΝΑΣ χαρακτήρας εκτός του βασικού αλφαβήτου GSM-7 (γράμματα με τόνους, emoji, οι περισσότερες μη λατινικές γραφές) και ΟΛΟΚΛΗΡΟ το μήνυμα μεταβαίνει σε UCS-2, ακόμη και αν είναι ο μοναδικός τέτοιος χαρακτήρας στο κείμενο. Συμβουλή: για να χωράτε με βεβαιότητα σε ένα τμήμα, χρησιμοποιήστε μόνο απλούς χαρακτήρες GSM-7.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_TO_KLEIDI_SAS",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Καλημέρα, σας υπενθυμίζουμε το αυριανό ραντεβού στις 10:00 - αν δεν σας βολεύει, απαντήστε μας και θα βρούμε άλλη ώρα. Ευχαριστούμε.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotency: ασφαλής επανάληψη αιτήματος

Προσθέστε μια κεφαλίδα Idempotency-Key με οποιαδήποτε δική σας συμβολοσειρά, για παράδειγμα το αναγνωριστικό της παραγγελίας. Αν το αίτημα αποτύχει λόγω σφάλματος δικτύου και η ροή εργασίας σας το επαναλάβει με την ΙΔΙΑ κεφαλίδα, το volai επιστρέφει την αποθηκευμένη απάντηση της πρώτης προσπάθειας και δεν στέλνει το μήνυμα δεύτερη φορά - το κλειδί ισχύει για 24 ώρες.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_TO_KLEIDI_SAS" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: paraggelia-4471" \
  -d '{"to": "+420777123456", "body": "Η παραγγελία σας αρ. 4471 ελήφθη."}'

Χειριστείτε με ασφάλεια το κλειδί API

Το κλειδί API (vk_...) έχει το ίδιο βάρος με έναν κωδικό πρόσβασης - όποιος το γνωρίζει μπορεί να στέλνει μηνύματα στο όνομά σας και να ξοδεύει υπόλοιπο από τον λογαριασμό σας. Για αυτό μην το γράφετε ποτέ στον πηγαίο κώδικα που κάνετε commit στο αποθετήριο. Ανήκει σε μια μεταβλητή περιβάλλοντος (process.env.VOLAI_API_KEY στο Node.js) ή στον διαχειριστή μυστικών που χρησιμοποιεί η φιλοξενία σας.

// .env.local (ποτέ μην το κάνετε commit στο αποθετήριο)
// VOLAI_API_KEY=vk_to_kleidi_sas

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

Καλείτε το endpoint πάντα από διακομιστή, ποτέ από τον περιηγητή - όποιος διάβαζε το κλειδί στα εργαλεία προγραμματιστή του περιηγητή θα μπορούσε να αρχίσει να στέλνει δικά του μηνύματα από τον λογαριασμό σας. Αν το κλειδί διέρρευσε (για παράδειγμα με ένα κατά λάθος commit), δημιουργήστε νέο στην πύλη και ανακαλέστε το παλιό - η παλιά τιμή παύει να λειτουργεί αμέσως.

Δοκιμάστε πρώτα με ασφάλεια

Πριν συνδέσετε την αποστολή SMS σε μια πραγματική διαδικασία (για παράδειγμα επιβεβαίωση παραγγελίας), στείλτε τα πρώτα μηνύματα στον δικό σας αριθμό. Θα δείτε ακριβώς ό,τι θα δει ο πελάτης - πώς φαίνεται ο αποστολέας SMSinfo, πόση ώρα παίρνει η παράδοση και αν τα τμήματα μετρώνται όπως περιμένετε. Μόνο μετά αλλάξτε το to στον πραγματικό αριθμό του πελάτη.

Τι κάνετε όταν το API επιστρέψει σφάλμα;

Μια ανεπιτυχής απάντηση έχει πάντα τη μορφή {error: {code, message}} και κατάσταση HTTP ανάλογα με τον τύπο του σφάλματος:

Ποιες καταστάσεις μπορεί να έχει ένα μήνυμα;

Το πεδίο status, τόσο στη λίστα (GET /v1/messages) όσο και στο λεπτομερές μήνυμα, παίρνει πέντε τιμές: pending (αποθηκευμένο, αποστέλλεται ακόμη), sent (ο πάροχος επιβεβαίωσε την αποστολή), failed (ο πάροχος το απέρριψε - δεν χρεώνεται), unknown (δεν ήρθε επιβεβαίωση παράδοσης, συνήθως timeout από την πλευρά του παρόχου - χρεώνεται ωστόσο πλήρως, επειδή το μήνυμα μπορεί να έφτασε) και received (μόνο στα εισερχόμενα μηνύματα, δηλαδή με direction=in· τα απεσταλμένα μηνύματα δεν το έχουν).

Κάθε μήνυμα φέρει επίσης τα πεδία direction (out στα απεσταλμένα, in στα ληφθέντα), smsNumber (ο αριθμός από τον οποίο έφυγε το μήνυμα ή στον οποίο έφτασε· στα μηνύματα με το κοινόχρηστο όνομα SMSinfo είναι null) και deliveryStatus (delivered ή undelivered, αναφορά παράδοσης από τον πάροχο· υπάρχει μόνο στα SMS που στάλθηκαν από αριθμό κινητού, στα υπόλοιπα είναι null).

Πώς στέλνετε πολλά SMS μαζί;

Το rate limit επιτρέπει το πολύ ένα SMS ανά δύο δευτερόλεπτα ανά λογαριασμό και το πολύ 100 SMS την ημέρα. Όταν στέλνετε πολλά μηνύματα μαζί (για παράδειγμα υπενθυμίσεις ραντεβού), είναι απλούστερο να κάνετε μια σύντομη παύση ανάμεσα στα αιτήματα παρά να πιάνετε το rate_limited και να δοκιμάζετε ξανά:

const message = "Υπενθύμιση: το ραντεβού σας είναι αύριο - Η εφαρμογή μου";

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

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

  // Το όριο είναι το πολύ 1 SMS ανά 2 δευτερόλεπτα ανά λογαριασμό - μια
  // σύντομη παύση ανάμεσα στα αιτήματα είναι απλούστερη από το να
  // χειρίζεστε το rate_limited και να δοκιμάζετε ξανά.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Συνοπτικά: μία κλήση POST /v1/messages με τα πεδία to και body στέλνει το SMS, η κεφαλίδα Idempotency-Key προστατεύει τη ροή εργασίας από διπλή αποστολή όταν επαναλαμβάνεται το αίτημα, και η τιμή υπολογίζεται ανά τμήμα ανάλογα με το αν το κείμενο περιέχει χαρακτήρες εκτός GSM-7. Κρατήστε το κλειδί έξω από το αποθετήριο και στείλτε το πρώτο μήνυμα στον εαυτό σας.

Τι ακολουθεί

Η πλήρης τεκμηρίωση του REST API (αριθμοί, κλήσεις, webhooks, πράκτορες) βρίσκεται στο /docs/api. Θέλετε να μάθετε αμέσως πότε το volai παραδίδει ένα μήνυμα στον πάροχο, χωρίς polling του GET /v1/messages; Εγγραφείτε στο συμβάν message.sent - επιβεβαιώνει μόνο ότι το μήνυμα παραλήφθηκε από τον πάροχο, όχι ότι έφτασε στο τηλέφωνο (στα μηνύματα με το κοινόχρηστο όνομα το volai δεν το βλέπει, δείτε παραπάνω· τα μηνύματα που στέλνονται από δικό σας αριθμό κινητού έχουν αναφορά παράδοσης) - δείτε την τεκμηρίωση των webhooks. Και αν εκτός από SMS χρειάζεστε και έναν τηλεφωνικό αριθμό που σηκώνει μόνος του τις κλήσεις, δείτε την AI ρεσεψιονίστ.

Τι ακολουθεί