SMS sender API

SMS Sender API je programsko orodje za prejemanje in pošiljanje SMS sporočil. API lahko uporabljate praktično v vsakem programskem jeziku, ki omogoča pošiljanje zahtev.

Kako ga uporabiti?

Za uporabo tega API potrebujete uporabniški račun. Vsak račun ima lahko več projektov in vsak projekt lahko pošlje določeno število SMS sporočil na dan. Ob vsakem (ne)uspešnem zapisu v bazo, dobite vrnjeno obvestilo. Z API lahko komunicirate na tri načine:

  • Z uporabo GET metode (ne varno)
  • Z uporabo POST metode
  • Z uporabo POST metode in JSON telesa (Content-type mora biti nastavljen na application/json)

Pošiljanje sporočil

Če želite poslati sporočilo, potrebujete narejen račun in projekt. SMS pošljete s pošiljanjem zahteve /sendSMS.

Sporočilo po dolžini API ne omejuje. Priporočljivo pa je, da je SMS sporočilo čim krajše. Saj daljše kot je sporočilo, dlje traja, da ga sistem obdela in pošlje. Če je sporočilo daljše kot 1000 znakov, se razdeli in ga pošlje po delih.

Prejemanje sporočil

Za prejemanje sporočil potrebujete narejen uporabniški račun in projekt, prav tako pa povezavo, ki jo bo API obiskal ob vsakem prispelem sporočilu. Uporabnik na številko SMSsenderAPIja pošlje sporočilo z izbrano ključno besedo in parametri, SMSsenderAPI pa vas bo obvestil o prihodu novega sporočila z obiskom vaše povezave.

Če je dohodno sporočilo enako “STOP” morate takoj odstraniti vse podatke pridobljene iz te telefonske številke, prav tako pa uporabnika odjaviti iz vseh naročil. Ker API sistem to sporoči vašemu projektu kot SMS sporočilo predlagam, da na to sporočilo uporabniku ne odgovorite.

Osnovni podatki o API

Povezave do API

Do API lahko dostopate preko spodnjih povezav:

Priporočljivo pa je, da uporabite https povezavo. API pa se bo na vse povezave odzval enako.

Zahteve

/sendSMS

Ta zahtevek vpiše novo SMS sporočilo za pošiljanje.

Zahtevani parametri: key, message, phone

Primer odgovora

{
   "Request":"sendSMS",
   "TimeStamp":"2022-09-10 20:23:06",
   "Status":"OK"
}

/getOneSMS

Ta zahtevek vrne najstarejše neprebrano sporočilo za določen projekt.

Zahtevani parametri: key

Primer odgovora

{
   "Request":"getOneSMS",
   "TimeStamp":"2022-09-10 20:25:35",
   "SMS":{
      "Sender":"+386xxxxxxx",
      "Content":"sporo\u010dilo",
      "Received":"2022-09-10 22:25:12"
   }
}

ali

{
   "Request":"getAllSMS",
   "TimeStamp":"2022-09-10 20:26:24",
   "SMS": null
}

/getAllSMS

Ta zahtevek vrne vsa neprebrana sporočila za določen projekt.

Zahtevani parametri: key

Primer odgovora

{
   "Request":"getAllSMS",
   "TimeStamp":"2022-09-10 20:26:13",
   "SMSs":[
      {
         "IDSMS":"23",
         "Sender":"+386xxxxxxxx",
         "Content":"sporo\u010dilo",
         "Received":"2022-09-10 22:25:12"
      },
      {
         "IDSMS":"24",
         "Sender":"+386xxxxxxxx",
         "Content":"123",
         "Received":"2022-09-10 22:25:31"
      }
   ]
}

ali

{
   "Request":"getAllSMS",
   "TimeStamp":"2022-09-10 20:26:24",
   "SMSs":[
      
   ]
}

/SMSlength

Ta zahtevek vrne dolžino podanega SMS sporočila.

Zahtevani parametri: message

Primer odgovora

{
   "Request":"SMSlength",
   "TimeStamp":"2022-09-10 20:26:56",
   "LengthOfSMS":1,
   "Status":"OK"
}

/ProjectStatistics

Ta zahtevek vrne vse podatke o trenutnem projektu.

Zahtevani parametri: key

Primer odgovora

{
   "Request":"ProjectStatistics",
   "TimeStamp":"2022-09-10 20:27:14",
   "ProjectName":"Testni projekt",
   "ShortName":"test",
   "CreationDate":"2022-06-05 19:40:38",
   "AllowedIPs":192.168.1.1;153.5.44.2",
   "NumberOfSMSPerDay":"10",
   "Active":"1",
   "AddressOfServer":"https:\/\/nikigre.si",
   "SMSSentToday":"1",
   "Status":"OK"
}

/UpdateProject

Ta zahtevek posodobi podatke o izbranem projektu. Ta zahteva mora biti poslana s POST metodo v obliki “appliaction/json”.

Zahtevani parametri:

  • Username – uporabniško ime, ki vam je bil dodeljen.
  • Password – geslo, ki vam je bilo dodeljeno.
  • Key – API ključ za projekt, katarega želite spreminjati.

Neobvezni parametri (vsaj eden mora biti podan):

  • ProjectName – Ime projekta.
  • ShortName – Ključna beseda vašega projekta. Sprememba ni priporočljiva. Če je ključna beseda že zasedena, bo API vrnil napako.
  • AllowedIPs – IP naslovi ločeni z “;” iz katerih želite pošiljati SMS sporočila. Če želite to preverjanje izklopiti, to polje nastavite na “*”.
  • Active – Ali je projekt aktiven. Če projekt ni aktiven, SMS sporočil ne morete pošiljati.
  • AddressOfServer – URL naslov strežnika na katerega želite prejemati obvestila o prispelih SMS sporočilih.

Primer zahteve

{
   "Username":"UPORABNIŠKO IME",
   "Password":"GESLO USERJA",
   "key":"API key",

   "ProjectName":"Testni projekt",
   "ShortName":"kjucnaBeseda",
   "AllowedIPs":192.168.1.1;153.5.44.2",
   "Active":"1",
   "AddressOfServer":"https:\/\/nikigre.si"
}

Primer odgovora

{
    "Request": "UpdateProject",
    "TimeStamp": "2022-09-10 21:59:26",
    "Status": "OK"
}

/session

Ta zahtevek upravlja sejo uporabnika. Če je type=start bo SMSSenderAPI začel sejo s številko v parametru phone. Ko želite prenehati s sejo, nastavite type=stop. Sejo obvezno prekinite takoj, ko je komunikacija z uporabnikom končana, saj s tem omogočimo uporabniku komunikacijo z ostalimi projekti.

Uporaba seje pomeni, da lahko z uporabnikom komunicirate brez ključne besede. Primer je kviz. Ko uporabnik pošlje ključno besedo “kviz”, se začne seja, v odgovor dobi vprašanje, na katero mora odgovoriti. Odgovor bo v vsakem primeru posredovan vašemu projektu, ne glede na ključno besedo.

Zahtevani parametri: key, phone, type

Primer odgovora

Če seja za številko še ne obstaja, dobimo spodnje sporočilo.

{
    "Request": "session",
    "TimeStamp": "2023-09-23 08:07:57",
    "Status": "OK"
}

Če seja še ni bila začeta in jo želimo ustaviti, dobimo spodnje sporočilo.

{
    "Request": "session",
    "TimeStamp": "2023-09-23 07:57:38",
    "Error": "Session for that phone number and project was not found. Was it even started?",
    "Status": "FAIL",
    "ErrorCode": 20
}

Če seja za številko že obstaja in je lastnik seje drug projekt, dobimo spodnje sporočilo.

{
    "Request": "session",
    "TimeStamp": "2023-09-23 08:08:41",
    "Error": "Some other project has this number in session!",
    "Status": "FAIL",
    "ErrorCode": 17
}

Parametri

key

Vrednost tega parametra je API ključ vašega projekta.

phone

Vrednost tega parametra je slovenska telefonska številka na katero želite poslati SMS sporočilo.

message

Vrednost tega parametra je sporočilo, ki ga želite poslati.

type

Vrednost tega parametra je start in stop. Če je karkoli drugega, se zahteva zavrne.

Napake

ErrorCode: 1

Dovoljeni metodi sta le GET in POST.

ErrorCode: 2

API ključ ni pravilen! Preverite, da ste sploh podali ključ in da je le-ta pravilen.

ErrorCode: 3

Vaš projekt je onemogočen! Zato SMS sporočila ne morete poslati.

ErrorCode: 4

Phone parameter je pri tej zahtevi obvezen! Preverite, da ste parameter nastavili.

ErrorCode: 5

Message parameter je pri tej zahtevi obvezen! Preverite, da ste parameter nastavili.

ErrorCode: 6

IP naslov se ne ujema s podatki vpisanimi v nastavitvah projekta. Preverite, da pošiljate zahteve iz pravega IP naslova. Če se je IP naslov spremenil, spremenite IP naslov v podatkih.

ErrorCode: 10

Zahteva iz tega IP naslova ni dovoljena! Preverite, da pošiljate zahteve iz pravega IP naslova. Če se je IP naslov spremenil, spremenite IP naslov v podatkih.

ErrorCode: 12

Username parameter je pri tej zahtevi obvezen! Preverite, da ste parameter nastavili.

ErrorCode: 13

Password parameter je pri tej zahtevi obvezen! Preverite, da ste parameter nastavili.

ErrorCode: 14

Uporabniško ime ali geslo ni pravilno. Preverite vpisane podatke!

ErrorCode: 15

Napaka pri nastavljanju podatkov za projekt. Preverite vse parametre in njihove tipe.

ErrorCode: 16

Seja z uporabnikom je že bila ustvarjena za ta projekt. Vsa sporočila bodo poslana projektu, ki je začel sejo.

ErrorCode: 17

Telefonska številka že ima sejo z drugim projektom.

ErrorCode: 18

Parameter type ni pravilno nastavljen!

ErrorCode: 19

Type parameter je pri tej zahtevi obvezen! Preverite, da ste parameter nastavili.

ErrorCode: 20

Telefonska številka nima aktivne seje.

ErrorCode: 21

Pri upravljanju seje je prišlo do težave. Takoj kontaktirajte administratorja.

Primer projekta Wiki

Kot konkreten testni primer si lahko pogledamo projekt Wiki. Namen tega programa je, da uporabniku vrne prvi odstavek članka, ki se ujema z njegovo iskano zahtevo.

Osnovni podatki

Programska koda

Programska koda, ki pridobi wiki članek in pošlje SMS se nahaja tukaj: https://www.dev.nikigre.si/wiki_sms/koda.php

Potek od prejetega sporočila do odgovora

  • Ko uporabnik pošlje: »wiki Borut Pahor« na telefonsko številko SMS Sender API, se v podatkovno bazo shrani telefonska številka, sporočilo, ki ga je uporabnik poslal (brez imena projekta (»wiki«)) ter kdaj je bilo to sporočilo prejeto.
  • Po vpisu v bazo, API odpre povezavo navedeno zgoraj in počaka 10s. Če po 10s ne dobi odgovora od spletene strani, pošlje uporabniku sporočilo, da se strežnik ne odziva.
  • Programska koda pridobi prejeto sporočilo in pogleda, ali je uporabnik zahteval pomoč in če jo ni, poskusi najti ustrezen članek.
  • V obeh primerih, ali je članek najden ali ne, koda pošlje odgovor na telefonsko številko iz katere je prišla zahteva. Ta pa lahko vsebuje prvi odstavek Wiki članka ali pa le obvestilo o tem, da članek ni bil najden.
  • Ko ta programska koda pošlje sporočilo, se v roku 5 s sporočilo prenese iz podatkovne baze ga sistem pošlje.

Več informacij

Če bi želeli uporabiti pošiljanje in prejemanje sporočil v vaši aplikaciji, mi pišite na info (at) nikigre.si.