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 POST spremenljivke strežniku.

Kako ga uporabiti?

Za uporabo tega API potrebujete uporabniški račun, registriran v sistem. Vsak račun lahko pošlje določeno število SMS sporočil na dan. Zahteve API se pošiljajo preko POST metode. Ob vsakem (ne)uspešnem zapisu v bazo, dobite vrnjeno obvestilo.

Pošiljanje sporočil

Za pošiljanje sporočil, potrebujete uporabniško ime. Pošiljanje sporočil izvajate z ustreznimi parametri navedenimi spodaj.

Prejemanje sporočil

Za prejemanje sporočil potrebujete uporabniško ime, ime projekta (prva beseda, ki jo mora uporabnik poslati) in povezavo ki naj jo API obišče, ko dobi sporočilo (Ko API obišče to povezavo, pomeni, da je vaš projekt prejel novo sporočilo).

Za programski jezike .NET je napisana knjižnica, ki vam precej olajša pošiljanje in prejemanje sporočil. Demo projekt in knjižnico si lahko prenesete tukaj.

Osnovni podatki o API

Povezave do API

Do API lahko dostopate preko spodnjih povezav:

  • http://dev.nikigre.si/sms/api.php
  • https://dev.nikigre.si/sms/api.php
  • https://www.dev.nikigre.si/sms/api.php

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

Spremenljivke

func

Obvezno. Ta spremenljivka pove, kaj želite narediti. Parametre nastavljate s 1 in 0. 1 pomeni DA in 0 NE. Vedno morate podati vse štiri parametre! Četudi želite poslati samo sporočilo.

Pozicija številk:

  1. Pošlji SMS
  2. Vrni koliko SMS se še lahko pošlje danes
  3. Vrni dolžino vpisanega SMS
  4. Vrni prejeta sporočila, glede na projekt

Primer: func=1010 -> API bo poslal SMS in vrnil koliko SMS sporočil je zavzelo poslano besedilo.

message

To spremenljivko nastavite na sporočilo, ki ga želite poslati.

Primer: message=Hej! Testiranje sporočila.

phone

To spremenljivko nastavite na telefonsko številko, na katero želite poslati SMS. Trenutno so podprte samo številke +386.

Primer: phone=+38670823455

user

To spremenljivko nastavite na vaše API uporabniško ime.

Primer: user=testapi

date

To spremenljivko nastavite na datum, po katerem želite prikazovati prejete SMS. Priporočljiva je uporaba: YYY-MM-DD HH:MM:SS (API uporablja LIKE ukaz za iskanje po datumu).

Primer: date=2019-01-01, date=20:00:00

Napake

Error: 0

Uporabniško ime je nepravilno.

Error: 1

Sporočilo ki ga želite poslati je preveliko. Vaša kvota bi bila s tem sporočilom presežena!

Error: 2

Napaka pri vpisu v podatkovno bazo! Poizkusite znova kasneje.

Error: 3

Spremenljivka func ni bila nastavljena pravilno! Preverite, da ste nastavili vse tri potrebne parametre te spremenljivke.

Error: 4

Preverite, ali so spremenljivke message, phone, user pravilno nastavljene!

Error: 5

Spremenljivka user ni pravilno nastavljena.

Error: 6

Spremenljivka message ni pravilno nastavljena.

Error: 7

Sporočilo je prazno (zasede 0 sporočil).

Odgovor API

API ob vsaki zahtevi vrne nekakšen odgovor (razen v primeru nedelujočega strežnika). Vrne pa lahko:

  • Koliko SMS sporočil še lahko uporabnik pošlje (Left:X)
  • Koliko SMS sporočil zasede poslano besedilo (Length:X)
  • Obvestilo o uspehu (OK)
  • Obvestilo o napaki (Error:X – ali MySQL napako)

Primeri uporabe pošiljanja ukazov API

Primer 1

Link: http://dev.nikigre.si/sms/api.php

POST spremenljivke:

  • func=1100
  • message=Zdravo! Tukaj je primer API. 🙂
  • phone=+386745343221
  • user=testapi

Opis

Zgornji primer bo poslal sporočilo “Zdravo! Tukaj je primer API. 🙂 ” na telefonsko številko “+386745343221” preko računa “testapi” in vrnil koliko SMS sporočil še lahko uporabnik “testapi” pošlje danes.

Primer 2

Link: http://dev.nikigre.si/sms/api.php

POST spremenljivke:

  • func=0010
  • message=Zdravo! Tukaj je primer API.

Opis

Zgornji primer bo preveril dolžino sporočila “Zdravo! Tukaj je primer API.” in vrnil koliko SMS sporočil zasede besedilo.

Primer 3

Link: http://dev.nikigre.si/sms/api.php

POST spremenljivke:

  • func=0001
  • user=testapi

Opis

Zgornji primer bo vrnil, vsa prejeta sporočila, ki se začnejo z imenom vašega projekta, ki jih še niste obdelali (Sporočila se označijo za obdelana takoj, ko API dostopa do njih).

Koda vrne: ‘+38631568778’, ‘prikaži 123’, ‘2019-09-01 19:21:24’; ‘+386312214567’, ‘prikaži 321’, ‘2019-09-01 19:55:24’;

Primer 4

Link: http://dev.nikigre.si/sms/api.php

POST spremenljivke:

  • func=0001
  • user=testapi
  • date=2019-09-23

Opis

Zgornji primer bo vrnil, prejeta sporočila, ki se začnejo z imenom vašega projekta in so bila prejeta na določen datum.

Koda vrne: ‘+38631568778’, ‘prikaži 123’; ‘+386312214567’, ‘prikaži 321’;

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 potrebujete več informacij, odgovore na vprašanja ali pa uporabniško ime, izpolnite obrazec tukaj.