SMS vārteja caur API 10 minūtēs Node.js vidē

Lai nosūtītu SMS no Node.js, pietiek ar vienu POST pieprasījumu uz https://volai.cz/v1/messages ar galveni Authorization: Bearer vk_... un JSON pamattekstu {to, body}. Node 20 ir iebūvēts fetch, tāpēc nekādu papildu pakotni nevajag. Darbojošs piemērs ir tūlīt zem šīs rindkopas, ieskaitot kļūdu apstrādi un idempotenci, lai tīkla pārtraukums neizraisītu vienas un tās pašas ziņas nosūtīšanu divreiz.

Kas jums būs nepieciešams

• Node.js 18 vai jaunāks - fetch ir iebūvēts kopš šīs versijas; iesakām pašreizējo atbalstīto LTS līniju (24, stāvoklis uz 2026. gada 2. septembri).
• volai konts un API atslēga no portāla (Iestatījumi -> API un MCP) formā vk_....
• Vismaz viens kredīta papildinājums. SMS sāk darboties tikai pēc pirmā papildinājuma, apsveikuma kredīts uz tām neattiecas - ar to var izmēģināt zvanus, bet ne īsziņas.
• Saņēmēja tālruņa numurs Čehijā vai Slovākijā (+420 vai +421) - uz citām valstīm SMS nesūtām.
• Savs tālruņa numurs JUMS NAV vajadzīgs. Ziņas aiziet zem kopīgā sūtītāja vārda SMSinfo - operatori Čehijas tīklos atļauj tikai apstiprinātus sūtītāju vārdus, tāpēc ar kopīgo sūtītāju savu sūtītāja vārdu iestatīt nevar, un uz SMSinfo saņēmējs atbildēt nevar. Tādēļ savu identitāti norādiet pašā ziņas tekstā, kā piemērā zemāk. Ja vēlaties, lai var atbildēt, sūtiet ziņu no sava SMS numura (papildu pakalpojums, skatiet piezīmi zemāk).

Nosūtiet savu pirmo SMS

Pieprasījumam pietiek ar diviem laukiem: to (saņēmēja numurs) un body (ziņas teksts). Atbildē tiek atgriezts ziņas id, status, cena helleros (priceHal) un segmentu skaits (segments) - pie abiem pēc brīža atgriezīsimies.

const response = await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_JUSU_ATSLEGA",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Sveiki no volai! - Mana lietotne",
  }),
});

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 }

Cik maksā SMS un kas ir segmenti?

Viena SMS vienā segmentā maksā 1,36 kr bez PVN (cena spēkā uz 2026. gada 2. septembri). Cik segmentu ziņa aizņem, atkarīgs no tā, vai tā satur rakstzīmes ārpus GSM-7 alfabēta - operatori SMS sadala pēc standarta GSM 03.38:

Pietiek ar VIENU rakstzīmi ārpus pamata GSM-7 alfabēta (burti ar diakritiskajām zīmēm, emocijzīmes, lielākā daļa nelatīņu rakstības), un VISA ziņa pārslēdzas uz UCS-2, pat ja tekstā tāda ir tikai viena. Padoms: ja vēlaties droši ietilpt vienā segmentā, rakstiet bez garumzīmēm un mīkstinājuma zīmēm.

await fetch("https://volai.cz/v1/messages", {
  method: "POST",
  headers: {
    Authorization: "Bearer vk_JUSU_ATSLEGA",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+420777123456",
    body: "Labdien, atgādinām par rītdienas pieņemšanu plkst. 10:00 - ja laiks nederēs, atbildiet mums, un mēs atradīsim citu laiku. Paldies.",
  }),
});
// -> { id: "msg_9a3f1c7d", status: "sent", priceHal: 272, segments: 2 }

Idempotence: droša pieprasījuma atkārtošana

Papildus nosūtiet galveni Idempotency-Key ar jebkuru savu virkni, piemēram, pasūtījuma ID. Ja pieprasījums neizdodas tīkla pārtraukuma dēļ un jūsu darbplūsma to atkārto ar TO PAŠU galveni, volai atgriež saglabāto atbildi no pirmā mēģinājuma un ziņu nesūta otrreiz - atslēga ir spēkā 24 stundas.

curl -X POST https://volai.cz/v1/messages \
  -H "Authorization: Bearer vk_JUSU_ATSLEGA" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pasutijums-4471" \
  -d '{"to": "+420777123456", "body": "Jūsu pasūtījums Nr. 4471 ir pieņemts."}'

Droši rīkojieties ar API atslēgu

API atslēgai (vk_...) ir tāda pati nozīme kā parolei - kas to zina, var jūsu vārdā sūtīt ziņas un tērēt kredītu no jūsu konta. Tāpēc nekad neierakstiet to pirmkodā, ko iekļaujat repozitorijā. Tai jābūt vides mainīgajā (process.env.VOLAI_API_KEY Node.js vidē) vai noslēpumu pārvaldniekā, ko izmanto jūsu hostings.

// .env.local (nekad neiekļaujiet commit repozitorijā)
// VOLAI_API_KEY=vk_jusu_atslega

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

Galapunktu izsauciet vienmēr no servera, nevis no pārlūkprogrammas - kas atslēgu izlasītu pārlūka izstrādātāju rīkos, varētu sākt sūtīt savas ziņas uz jūsu konta rēķina. Ja atslēga ir nopludināta (piemēram, kļūdaini commit), portālā izveidojiet jaunu un veco anulējiet - vecā vērtība pārstāj darboties nekavējoties.

Vispirms droši izmēģiniet

Pirms SMS sūtīšanu pieslēdzat īstam procesam (piemēram, pasūtījuma apstiprinājumam), nosūtiet pirmās pāris ziņas uz savu tālruņa numuru. Redzēsiet tieši to, ko redzēs klients - kā izskatās sūtītājs SMSinfo, cik ilgi ilgst piegāde un vai segmenti tiek skaitīti tā, kā gaidāt. Tikai tad pārslēdziet to uz klienta īsto numuru.

Ko darīt, ja API atgriež kļūdu?

Neveiksmīgā atbilde vienmēr ir formā {error: {code, message}} ar HTTP statusu atkarībā no kļūdas veida:

Kādi statusi ziņai var būt?

Lauks status sarakstā (GET /v1/messages) un vienas ziņas detaļās pieņem piecas vērtības: pending (saglabāta, vēl tiek sūtīta), sent (operators nosūtīšanu apstiprinājis), failed (operators noraidījis - netiek rēķināta), unknown (piegādes apstiprinājums nav saņemts, parasti taimauts operatora pusē - tomēr tiek rēķināta pilnā cenā, jo ziņa varēja nonākt) un received (tikai saņemtajām ziņām, tātad ar direction=in; nosūtītajām tā nav).

Katrai ziņai ir arī lauki direction (out nosūtītajām, in saņemtajām), smsNumber (numurs, no kura ziņa nosūtīta vai uz kuru saņemta; ziņām zem kopīgā vārda SMSinfo tas ir null) un deliveryStatus (delivered vai undelivered, operatora piegādes atskaite; rodas tikai SMS, kas nosūtītas no SMS numura, pārējām ziņām tas ir null).

Kā izsūtīt vairākas SMS vienlaikus?

Rate limit atļauj ne vairāk kā vienu SMS ik pēc divām sekundēm uz kontu un ne vairāk kā 100 SMS dienā. Izsūtot vairākas ziņas vienlaikus (piemēram, tikšanās atgādinājumus), vienkāršāk ir starp pieprasījumiem īsi uzgaidīt, nekā ķert rate_limited un mēģināt vēlreiz:

const message = "Atgādinājums: rīt jums ir pieraksts - Mana lietotne";

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

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

  // Limits ir ne vairāk kā 1 SMS ik pēc 2 sekundēm uz kontu - īsa pauze
  // starp pieprasījumiem ir vienkāršāka nekā rate_limited apstrāde un atkārtošana.
  await new Promise((resolve) => setTimeout(resolve, 2100));
}

Kopsavilkums: viens izsaukums POST /v1/messages ar laukiem to un body nosūta SMS, galvene Idempotency-Key pasargā darbplūsmu no dubultas nosūtīšanas, atkārtojot pieprasījumu, un cena tiek skaitīta pa segmentiem atkarībā no tā, vai teksts satur rakstzīmes ārpus GSM-7. Atslēgu glabājiet ārpus repozitorija un pirmo ziņu nosūtiet sev.

Kas tālāk

Pilna REST API atsauce (numuri, zvani, webhook, aģenti) ir lapā /docs/api. Vēlaties uzzināt uzreiz, kad volai ziņu nodod operatoram, bez GET /v1/messages aptaujāšanas? Abonējiet notikumu message.sent - tas apstiprina tikai to, ka operators ziņu pieņēmis, nevis to, ka tā nonākusi tālrunī (ziņām zem kopīgā vārda volai to neredz, skatiet augstāk; ziņām, kas nosūtītas no sava SMS numura, ir piegādes atskaite) - skatiet webhook dokumentāciju. Un, ja bez SMS jums vajadzīgs arī tālruņa numurs, kas pats atbild uz zvaniem, apskatiet AI recepcionistu.

Kas tālāk