SMS GATEWAY API Via onze HTTP gateway API kan u onze diensten op een eenvoudige manier integreren in uw bestaande software. Wij beschikken over een HTTP-interface die via een HTTP GET request uw sms berichten aanvaardt.
VERSTUREN VAN EEN SMS BERICHT
API URL : http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&message= MESSAGE&to=RECEIVER&sender=FROM Antwoord
Uitleg
Opmerking
OK
Uw SMS werd succesvol verzonden
Uw SMS werd succesvol verzonden
ERROR xxx
Er was een probleem + error code
Let op : U moet de bovenstaande url steeds encoderen voordat u deze verzend omdat deze o.a. geen spaties mag bevatten. Bvb : bericht=dit is een test , dit moet in de praktijk worden: bericht=dit%20is%20een%20test In PHP is hier een zeer eenvoudige functie voor : urlencode($url); Deze url encodering moet ook gebeuren voor de afzendernaam!
Uitzonderingen Ons systeem verwerkt berichten in UTF8 en zet deze zelf om naar GSM unicode. Er zijn 9 tekens die als 2 tekens beschouwd worden in GSM unicode. Gebruikt u 1 van deze tekens in uw bericht dan zal uw bericht in werkelijkheid dus langer zijn. Hierdoor kunnen er fouten optreden. Bvb. U heeft een bericht van 160 tekens en deze bevat 2 x € tekens, dan is dit bericht in werkelijkheid 162 tekens lang. Onderstaande tabel geeft de uitzonderingen weer: Symbol Name € Euro symbol [ ]
Open bracket Close bracket
\ ^ {
Backslash Caret Left brace
} ~ |
Right brace Tilde Vertical bar
Voorbeeldscripts in diverse programmeertalen : Hier kan u diverse voorbeeldscripts terugvinden.
Parameters : Parameter
Uitleg
Opmerking
username
uw gebruikersnaam
De gebruikersnaam die u van ons ontvangen heeft
password
uw wachtwoord
Het wachtwoord dat u van ons ontvangen heeft (u kunt dit wachtwoord ook encoderen met SHA-1 voor extra veiligheid)
message
het SMS bericht
Let op: het bericht moet urlencoded zijn vooraleer u verstuurd. (dit is een test = dit%20is%20een%20test)
de ontvanger(s)
Een geldig sms nummer (steeds beginnen met de juiste landcode : bvb 32478123456) U kan ook meerdere nummers gebruiken door deze te scheiden met een komma (&naar=32478123456,31600123456)
de afzendernaam
maximaal 11 tekens indien afzendernaam, 14 cijfers indien afzendernummer. Klik hier voor meer informatie over afzendernummers indien u naar Belgische ontvangers stuurt.
to
sender
Optionele parameters logging=ja
Loggingsfunctie
Indien u logging=ja toevoegd zullen alle smsverzendingen automatisch opgeslagen worden in de historiek van de sms module. Indien u logging=nee gebruikt zullen de sms verzendingen niet gelogd worden in de historiek van de sms module.
delivery=ja
Afleverrapporten
Indien u delivery=ja toevoegd krijgt u bij een succesvolle verzending OK + een smsID terug. bvb : OK 1234567 U kan dit SMS ID opvangen en kunt hier een callback action op uitvoeren om het rapport op te vragen.
datum=yyyymmddhhii
SMS inplannen op specifieke datum/tijd
Indien u verstuurdatum=yyyymmddhhii gebruikt worden uw smsjes ingepland op de opgegeven datum/tijd.alleen datums in de toekomst zijn toegestaan. - vul altijd alle velden volledig in (bvb 201206152000) (een jaartal altijd in 4 cijfers,maand,dag,uur en minuut altijd met 2 cijfers!) - uw berichten komen te staan in de outbox van de sms module en kan u nog verwijderen indien gewenst. - mogelijk uren zijn van 0 tot 23 ; mogelijke minuten zijn 00,15,30,45 U kan nog een 2de parameter meegeven: vb: datum=201510261215&outboxid=ja
U krijgt dan OK + unieke outboxID terug die u kan gebruiken om later berichten terug te verwijderen uit de outbox. emailen=nee
Bevestiging e-mail versturen
Indien u een SMS inpland op een specifieke datum stuurt het systeem standaard een e-mail wanneer de SMS verzonden werd. Met deze parameter kunt u deze bevestigingsemail uitschakelen.
naar=groep&groep=groepnaam Versturen naar een U heeft uw gsmnummers is ons systeem staan maar wil groep toch via de API een koppeling maken naar deze groepen? Dat kan op deze manier: U gebruikt de parameters: naar=groep&groep=groepnaam. Groep naam moet overeenkomen met een groepnaam uit uw adressenlijst. (gebruik hiervoor best geen spaties en/of speciale tekens in uw adressenlijst). U kunt dit ook combineren met de datum parameter om een groepsverzending in te plannen op een later tijdstip. Zie ook: error 125 en 126 test=ja
Testen van het systeem
Het systeem zal wel alle controles uitvoeren (correcte gebruikersnaam,wachtwoord ,bericht, afzendernaam, ...) maar zal geen effectieve SMS versturen. Er worden ook geen credits afgetrokken.
referentie=12345678
Uw referentie (maximaal 75 tekens).
U kan hier een unieke ID meegeven die u bij het ontvangen een afleverrapport terugkrijgt van ons systeem.
type=long
Versturen van lange berichten
Indien u type=long toevoegd kan u berichten > 160 tekens versturen. Het bericht wordt in dit geval opgesplitst in meerdere SMS-berichten en vervolgens op de telefoon als één bericht weergegeven. U kan een bericht aanleveren tot maximum 459 tekens en wij splitsen het op naar maximaal 3 SMS-berichten. Let op : je kan per SMS maar 153 tekens gebruiken (de andere 7 tekens worden gebruikt om aan te geven dat het om een "long SMS" gaat).
type=flash
Versturen van flash Indien u type=flash toevoegd zal uw bericht verzonden berichten worden als flash sms.
validity=123
Geldigheidsduur Indien u validity=123 toevoegd zal uw bericht een opgeven van een geldigheid meekrijgen van 123 minuten. bericht in minuten Als u geen validity meegeeft is de standaard geldigheid 1440 minuten. Validity kan een getal zijn tussen 15 en 2880.
OVERZICHT ERROR CODES Als er een probleem optreed geeft de API een error + nummer terug. Hier kan u een overzicht terugvinden van alle mogelijke errors. Error nr
Uitleg
100
Gebruikersnaam-waarde is leeg en mag niet leeg zijn
101
Wachtwoord-waarde is leeg en mag niet leeg zijn
102
SMS bericht bevat geen inhoud
103
Gsmnummer bevat geen inhoud
104
Geen geldige gebruikersnaam en/of wachtwoord combinatie
105
Bericht bevat meer tekens dan toegestaan (> 160 tekens)
106
Geen geldig GSMnr. Een geldig nummer start altijd met de landcode gevolgt door het nummer : bvb 32478123456
107
Geen geldige landcode. U kan geen smsjes versturen naar dit land. Gelieve ons te contacteren of we dit mogelijk kunnen maken.
108
U heeft niet voldoende credits meer
109
De afzendernaam is leeg
110
U maakt gebruik van een afzendernummer, maar deze moet altijd met een +teken beginnen.
111
U maakt gebruik van een ongeldige afzendernaam. Dit veld mag maximaal 11 alfanumerieke tekens bevatten of 14 cijfers
112
U maakt gebruik van een ongeldige landcode
113
Uw afzendernaam/nummer bevat speciale tekens die niet op alle netwerken zijn toegelaten.
114
Geen geldige landcode (land niet toegestaan).
115
Uw account werd geblokkeerd omdat uw betaling nog niet in orde is.
116
Uw account werd geblokkeerd om een bepaalde reden. U kan contact met ons opnemen voor meer informatie.
117
Deze afzendernaam is niet toegestaan.
118
Indien u een lange SMS wil versturen (> 160 tekens) mag deze maximaal 3 berichten lang zijn, (max 153 tekens per bericht) dus maximaal 459 tekens lang.
119
Voor versturen van smsjes naar dit land , kan u de mogelijkheid om lange smsjes (> 160 tekens) te versturen niet gebruiken.
120
Er was een probleem met onze gateway. Gelieve ons te contacteren.
121
U maakt gebruik van een verzending op vooraf opgegeven datum/tijd maar de datum ligt in het verleden of is niet juist !
122
U probeerde een SMS bericht uit de outbox te verwijderen maar er werd geen overeenkomstig bericht gevonden.
123
U probeerde een rapport op te vragen maar gaf geen aantal records op.
124
U probeerde een rapport op te vragen maar het aantal records was niet geldig. vb: aantal=100
125
U probeerde een SMS naar een groep te versturen maar deze groep kunnen we echter niet terugvinden in uw telefoonlijst.
126
U probeerde een SMS naar een groep te versturen maar deze groep bevat geen gsmnummer.
127
U probeerde een rapport op te vragen maar het aantal was hoger dan toegelaten. Maximum aantal records = 1000.
128
U probeerde een nummer toe te voegen aan een telefoonlijst groep die onbestaande is of waarvan u geen eigenaar bent. Groepid is onjuist.
129
U probeerde een nummer toe te voegen dat reeds voorkwam in deze groep
130
U gebruikte een foutieve tijdsduur waarde. De geldigheidsduur parameter moet een getal zijn in minuten gelegen tussen 1 en 2880
150
Onze module is tijdelijk buiten gebruik wegens werkzaamheden.
200
Toegang tot de gateway API is niet toegestaan omdat uw IP adres niet toegestaan is.
300
Deze aanvraag voor een afleverrapport is tijdelijk niet mogelijk. Ons systeem is momenteel zwaar belast.
AFLEVERRAPPORTEN ONTVANGEN OP EEN API Hier kan u een URL opgeven waarnaar wij afleverrapporten sturen. Ons systeem zal een GET uitvoeren op dit script met volgende parameters: smsid, datum (yyyymmdduummss), status,status2, referentie.
Parameter Uitleg smsid
Het smsid is het unieke ID wat u van ons terugkrijgt nadat u een sms verzonden heeft via de API.
status
de status is de bericht status waar u hieronder een lijst van kan vinden.
status2
dit is een detailstatus die soms extra meegestuurd wordt (bvb als een bericht niet afgeleverd kon worden om een specifieke reden mee te delen.
referentie dit is de unieke referentiecode die u meegegeven had bij het verzenden van een bericht. Opslaan
(Voorbeeld: http://www.mijndomein.com/mijnscript.php)
Afleverrapporten statussen Status Aflevercode
Uitleg
0
SUBMITTED
Dit bericht werd afgeleverd bij de operator maar hebben we nog geen afleverrapport van ontvangen.
1
DELIVERED
Dit bericht werd succesvol afgeleverd.
2
NOT DELIVERED
Dit bericht was niet afgeleverd. Mogelijke reden: ontvanger langdurig buiten bereik van netwerk, netwerk problemen, ontvanger in buitenland.
3
BUFFERED
Dit bericht werd afgeleverd bij de operator maar nog niet afgeleverd bij de eindontvanger.
4
REJECTED
Dit bericht werd geweigerd door de operator.
5
NO REPORT AVAILABLE
Er is geen afleverrapport beschikbaar van dit bericht.
9
UNKNOWN
Er is geen afleverrapport beschikbaar van dit bericht.
Afleverrapporten detail statussen (status2) Status
Uitleg
10
Ontvanger nummer onbestaande
11
Ontvanger tijdelijk buiten bereik van netwerk operator
12
Telefoon gerelateerd probleem.
13
Operator netwerk probleem
14
Bericht verlopen - onbekende reden
15
Ontvanger staat op een blacklist
16
Bericht inhoud probleem
17
Ontvanger kan niet afgerekend worden
18
Operator weigert dit bericht wegens spam
OPVRAGEN VAN RESTEREND AANTAL CREDITS Met deze functie kan u het aantal resterende sms credits opvragen aan de API. http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=cred its Dit geeft een getal terug : bvb 476 Dit is het aantal credits dat u nog op uw SMS account heeft staan.
BEHEER OUTBOX U kan via de API ook berichten uit de outbox beheren.
Overzicht functies http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=ove rviewoutbox Deze actie geeft een overzicht van de outbox in XML formaat.
Verwijderen Om 1 bericht te verwijderen: http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=rem ovemessage&to=NUMBER of http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=rem ovemessage&id=OUTBOXID Om de gehele outbox leeg te maken: http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=rem oveoutbox Deze actie geeft terug : OK of ERROR 122 (geen bericht gevonden in outbox)
GROEPSRAPPORT OPVRAGEN
Opvragen van de sms historiek in HTML tabel formaat. http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=rep ort&number=100 Deze actie geeft een tabel terug met de laatste 100 verzonden berichten, in tabelvorm, met hierbij hun afleverrapport.
TELEFOONLIJST BEHEREN VIA API Via deze functies kan u de telefoonlijst bijwerken met behulp van de API.
Overzicht groepen in XML http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=gro upoverview Hiermee krijgt u een overzicht van alle groepen uit uw telefoonlijst met hun ID in XML formaat. Vb:
1My first group2My second group
Bekijk telefoonlijst groep http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=vie wgroup&groupid=123 Deze actie geeft een overzicht van de inhoud van een telefoonlijst groep in XML formaat.
Toevoegen nummer aan een groep http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=add number&group=12345&number=32478123123&firstname=abc&lastname=abc&extra1=abc&extra2=abc&ext ra3=abc&extra4=abc&dd=01&mm=01&yyyy=1990 Hiermee voegt u nummer toe aan een bestaande telefoonlijst. De velden group en number zijn verplichte velden. De andere velden zijn optioneel in te vullen. Het groepid van een groep kan u verkrijgen via de bovenstaande functie.De velden dd,mm,yyyy zijn de velden van de geboortedatum. De functie geeft een OK terug of een error code.
Uitschrijven van een nummer uit een groep http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=uns ubscribe&group=12345&number=32478123123
Hiermee gaat u een nummer uitschrijven uit een bestaande telefoonlijst. De velden group en number zijn verplichte velden.
Uitgeschreven nummer terug inschrijven http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=sub scribe&group=12345&number=32478123123 Hiermee gaat u een uitgeschreven nummer terug inschrijven in een bestaande telefoonlijst. De velden group en number zijn verplichte velden.
OVERIGE FUNCTIES
Overzicht klant details http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=cust omerdetails Deze geeft een overzicht van alle klant details terug in XML formaat. (credits, contact gegevens)
Overzicht afzendernamen in XML formaat http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=sen dernames Deze geeft een overzicht van alle afzendernamen terug in XML formaat.
Overzicht landcodes in XML formaat http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=cou ntrycodes&language=en Deze geeft een overzicht van alle landcodes terug in XML formaat in de juiste taal (en, nl, fr, de).
Overzicht standaard teksten. http://www.smsgatewayapi.com/gateway.php?username=USERNAME&password=PASSWORD&action=def aulttext Deze actie geeft een overzicht van de standaard teksten in XML formaat.
SUPPORT U kan ons steeds contacteren als u problemen heeft met het implementeren van onze gateway in uw scripts.
