SMS gateway API : Technische informatie
Met de SMS-tools gateway API kunt u SMS berichten versturen via uw eigen software of website.
Dit kan naar individuele personen en grote groepen. Wij maken enkel gebruik van de hoogste kwaliteit SMS (premium) routes.
We beschikken over een HTTP-interface die via een HTTP request uw sms berichten aanvaardt.
URL :
http://217.19.227.48/module/gateway.php?klantuser=USERNAME&klantpwd=PASSWORD&bericht=BERICHT&naar=NAAR&afzender=SENDER
| Antwoord | Uitleg | Opmerking |
| OK | Uw SMS werd succesvol verzonden | Uw SMS werd succesvol verzonden |
| ERROR xxx | Er was een probleem + error code | Een overzicht van mogelijke error codes kan u hier terugvinden. |
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!
Parameters :
| Parameter | Uitleg | Opmerking |
| klantuser | uw gebruikersnaam | De gebruikersnaam die u van ons ontvangen heeft |
| klantpwd | uw wachtwoord | Het wachtwoord dat u van ons ontvangen heeft (u kunt dit wachtwoord ook encoderen met SHA-1 voor extra veiligheid) |
| Bericht | het SMS bericht | Let op: het bericht moet urlencoded zijn vooraleer u verstuurd. (dit is een test = dit%20is%20een%20test) |
| naar | 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) |
| afzender | de afzendernaam | maximaal 11 tekens indien afzendernaam, 14 cijfers indien afzendernummer |
| 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. |
| 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). |
| 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 groep | U heeft uw gsmnummers is ons systeem staan maar wil 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. |
Error codes :
Als uw bericht niet succesvol verzonden is geeft de gateway een error + nr terug.
Hier kan u een overzicht terugvinden van de 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 tekens bevatten. Let op : Belgische afzendernummers (bvb 32479123456 , +32479123456 , 0479464892) worden niet meer toegelaten omdat Mobistar deze blokkeert. |
| 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 te halen uit het systeem maar gaf geen aantal op. |
| 124 | U probeerde een rapport te halen uit het systeem maar het aantal 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. |
| 150 | Onze module is tijdelijk buiten gebruik wegens werkzaamheden. |
Afleverrapporten opvragen :
Om afleverrapporten te gebruiken moet u altijd eerst de parameter "delivery=ja" gebruiken.
U krijgt dan als antwoord OK + ID terug . bvb OK 1234567
Deze antwoorden dient u op te slaan.
Via deze pagina kan u vervolgens de afleverstatussen opvragen :
http://217.19.227.48/module/gatewayrapport.php?smsid=1234567
| Parameter | Uitleg | Opmerking |
| smsid | Het sms ID | Het unieke ID van het bericht waarvan u het afleverrapport wenst op te vragen |
| datum=ja | Rapport datum (dd/mm/yyyy uu:mm:ss) |
Indien u parameter datum=ja meegeeft zal onze API de status + laatste update datum/tijd weergeven. Bvb : DELIVERED 01/02/2012 10:23:10 Let op: indien het bericht nog onderweg is (SUBMITTED) of er geen rapport beschikbaar is (NONE) is er geen afleverrapportdatum beschikbaar. |
Het systeem geeft vervolgens een code terug naargelang de status van het bericht.
| Aflevercode | Uitleg |
| DELIVERED | Dit bericht werd succesvol afgeleverd. |
| NOT DELIVERED | Dit bericht was niet afgeleverd. Mogelijke reden: ontvanger langdurig buiten bereik van netwerk, netwerk problemen, ontvanger in buitenland. |
| BUFFERED | Dit bericht werd afgeleverd bij de operator maar nog niet afgeleverd bij de eindontvanger. |
| REJECTED | Dit bericht werd geweigerd door de operator. |
| SUBMITTED | Dit bericht werd afgeleverd bij de operator maar hebben we nog geen afleverrapport van ontvangen. |
| NO REPORT AVAILABLE | Er is geen afleverrapport beschikbaar van dit bericht. |
Opvragen van resterend aantal credits :
U kan ook uw aantal resterende credits opvragen aan de gateway.
http://217.19.227.48/module/gateway.php?klantuser=USERNAME&klantpwd=PASSWORD&action=credits
Dit geeft een getal terug : bvb 476
Dit is het aantal credits dat u nog op uw SMS account heeft staan.
Berichten verwijderen uit outbox :
U kan via de gateway ook de berichten uit uw outbox beheren.
Om 1 bericht te verwijderen:
http://217.19.227.48/module/gateway.php?klantuser=USERNAME&klantpwd=PASSWORD&action=verwijderbericht&naar=NUMMER
of
http://217.19.227.48/module/gateway.php?klantuser=USERNAME&klantpwd=PASSWORD&action=verwijderbericht&id=OUTBOXID
Om de gehele outbox leeg te maken:
http://217.19.227.48/module/gateway.php?klantuser=USERNAME&klantpwd=PASSWORD&action=verwijderoutbox
Deze actie geeft terug : OK of ERROR 122 (geen bericht gevonden in outbox)
Afleverrapport:
U kan via de gateway ook een realtime groepsrapport opvragen.
http://217.19.227.48/module/gateway.php?klantuser=USERNAME&klantpwd=PASSWORD&action=rapport&aantal=100
Deze actie geeft een tabel terug met de laatste 100 verzonden berichten, in tabelvorm, met hierbij hun afleverrapport.
Support :
U kan ons steeds contacteren als u problemen heeft met het implementeren van onze gateway in uw scripts.
