SMSStunter gateway API

SMSStunter gateway API Inhoud 1. Verbinden met de gateway 2. Parameters 3. Antwoord codes / Error meldingen 4. Opvragen Credits 5. Voorbeelden 6. DLR 7. Email 2 SMS 1

1. Verbinden met de gateway Er kan alleen verbinding gemaakt worden met de gateway via het internet. De gateway is gelokaliseerd op het internet en momenteel alleen bereikbaar via het http protocol op poort 80. Het adres is: http://gateway.smsstunter.nl Er kan verbonden worden met de gateway door middel van GET en POST requests met een content type: application/x-www-form-urlencoded. Meer hierover vindt u op: http://nl.wikipedia.org/wiki/html-formulier#codering Om de gateway te beveiligen wordt er gebruik gemaakt van een gebruikersnaam en wachtwoord. Meer hierover vindt u in het tweede hoofdstuk van dit document. 2

2. Parameters De volgende parameters worden gebruikt door onze gateway: Username: gebruikersnaam van de klant Password: wachtwoord van de klant Sender: Afzender (zichtbaar in sms) Recipient: Ontvanger (meerdere door, gescheiden) Message: Het sms bericht Route: De route die gebruikt wordt voor het versturen. Het type geeft aan of het een lange sms is of niet. username De gebruikersnaam waarmee u toegang heeft tot SMSStunter Parameter: username Type: string Waarden: alfanumeriek (A-Za-z0-9) Min lengte: 2 Max lengte: 25 Verplicht: ja Voorbeeld: Ferry password Het wachtwoord dat bij de gebruikersnaam hoort. Parameter: password Type: string Waarden: alfanumeriek (A-Za-z0-9) Min lengte: 6 Max lengte: 25 Verplicht: ja Voorbeeld: sk8e49nds sender De afzender die wordt weergegeven op de telefoon van de ontvanger. Deze overschrijft de standaard waarde voor de afzender. Parameter: sender Type: string Waarden: alfanumeriek (A-Za-z0-9) Min lengte: 1 Max lengte: 11 Verplicht: nee Voorbeeld: SMSStunter reference Een zelf te kiezen referentie code die meegestuurd wordt in de DLR (zie hoofdstuk 6) 3

message Het bericht dat verzonden dient te worden. Parameter: message Type: string Waarden: @ $ è é ù ì ò Ç LF Ø ø CR Å å Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ ESC Æ æ ß É SP! " # % & ' ( ) * +, -. / 0 1 2 3 4 5 6 7 8 9 : ; < = >? A B C D E F G H I J K L M N O P Q R S T U V W X Y Z Ä Ö Ñ Ü a b c d e f g h i j k l m n o p q r s t u v w x y z ä ö ñ ü à (1 teken) FF ^{ } \[ ~ ] (2 tekens) Min lengte: 1 Max lengte: 764 Verplicht: ja Extra: Let op, ook al worden er maar 160 karakters verzonden. Er zijn een paar karakters die dubbel tellen. Het euro teken bijvoorbeeld, neemt 2 plaatsen in gebruik. Een sms met het euroteken kan daarom maar 159 karakters lang zijn. Het bericht moet urlencoded aangeleverd worden. Voorbeeld: Dit%20is%20een%20test%20bericht. route De route waarover het sms bericht verstuurd dient te worden. Parameter: route Type: string Waarden: alfanumeriek (A-Za-z0-9) Min lengte: 3 Max lengte: 3 Verplicht: ja Extra: De code voor de route is te vinden in het beveiligde gedeelte van SMSStunter. Log in om bij dit gedeelte te komen om te zien welke code gebruikt dient te worden. Voorbeeld: biz type Het type van een sms bericht. Dit overschrijft de standaard waarde die is ingegeven op SMSStunter. Parameter: type Type: string Waarden: alfanumeriek (a-z) Min lengte: 4 Max lengte: 4 Verplicht: nee Extra: Stuur deze parameter alleen mee als u niet op de website heeft ingesteld dat u de mogelijkheid wil hebben voor langere berichten dan 160 karakters. Deze parameter overschrijft de vastgestelde waarde op SMSStunter onder uw account. Voorbeeld: long SMSStunter gateway API v1.0 Laatst gewijzigd: 23-09- 2013 4

3. Antwoord codes / Error meldingen Bij een succesvolle verzending krijgt u de volgende melding terug: accepted [31612345678] accepted [31612345679] failed [0] Dit betekend dat de ontvangers door de controles zijn gekomen en het sms bericht verstuurd zal worden. Mocht één van de ontvangers niet juist zijn, dan wordt dat als volgt weergegeven: accepted [31612345678] failed [316123456789] Hierbij is het eerste nummer wel door de controles gekomen, maar het tweede niet. Error meldingen 010 username/password not specified De username of het wachtwoord is niet meegestuurd. Er kan dus niet gecontroleerd worden of er toegang gegeven mag worden voor het versturen van de berichten. 020 username/password invalid De username en het wachtwoord is wel meegestuurd, maar deze komt niet voor in ons systeem. Het kan zijn dat het wachtwoord, of de username verkeerd is. Er mogen met deze gegevens dus geen sms berichten verstuurd worden. 030 no message specified Er is geen bericht meegestuurd. We gaan er van uit dat het niet de bedoeling is om lege berichten te versturen, dus het systeem stopt en geeft deze melding terug. 040 no recipients specified Er zijn geen ontvangers meegestuurd met het bericht. 050 no route specified Er is geen route gespecificeerd waar de sms over verzonden dient te worden. De route aanduiding kunt u vinden bij de route instellingen. 060 message to long [xx] max 160 Dit bericht krijgt u wanneer het bericht dat u stuurt langer is dan 160 karakters. U kunt met de parameter type ervoor zorgen dat u wel langere berichten mag versturen. U kunt het vinkje bij de instellingen aanzetten op smsstunter.nl bij uw gegevens. In de [xx] staat hoe lang het gestuurde bericht is. 5

070 message to long [xx] max 764 Dit bericht krijgt u terug wanneer u wel gebruik maakt van lange sms berichten, maar het totale bericht groter is dan 764 karakters. In de [xx] staat hoe lang het gestuurde bericht is. SMS Stunter gateway API v0.1 Laatst gewijzigd: 23-03-2009 080 all recipients invalid Deze melding krijgt u als u wel ontvangers heeft meegestuurd, maar dat de ontvangers die meegestuurd zijn niet voldoen aan de bij parameter recipient opgelegde voorwaarden. Het formaat van een nummer moet namelijk <landcode zonder + of 00><nummer zonder 0> dus: 31612345678 090 route invalid Het kan zijn dat de route die u meegestuurd heeft niet in ons systeem bestaat. U krijgt dan deze melding. 100 no <route_name> route credits U heeft geen sms tegoeden om uw sms berichten te versturen. Waardeer eerst uw tegoed op. 110 insufficient <route_name> route credits [xx] available [xx] needed Er zijn niet genoeg tegoeden beschikbaar op deze route om de sms berichten te versturen. 120 sender not specified Deze melding wordt gegeven wanneer u geen sender meegeeft aan de gateway en uw default sender niet ingesteld is in ons systeem. 130 sender not alphanumeric U heeft een ongeldige afzender meegestuurd aan de gateway. Kijk bij de parameter sender voor meer informatie. 140 internal error. please contact us Als het goed zult u deze melding nooit krijgen. Deze verschijnt alleen als er iets ernstigs is gebeurd met de gateway. Mocht u deze melding krijgen neem dan direct contact met ons op. 6

4. Opvragen credits Voor het opvragen van credits kunt u de volgende instellingen gebruiken: http://gateway.smsstunter.nl/credit.php?username=uwusername&password=uwpassword &route=??? In de URL kunt u aangeven voor welke route u de gegevens wilt weergeven: Business route = biz Economy route = eco Alle routes = all 5. Voorbeelden Hier vindt u twee voorbeelden voor het verzenden van een sms bericht via de gateway. Let op dat deze voorbeelden niet functioneel zijn en puur fictief als voorbeeld. Voorbeeld 1 Bij dit voorbeeld gaan we ervan uit dat u alles via de website heeft geconfigureerd en alleen de noodzakelijke waardes worden meegestuurd. http://gateway.smsstunter.nl/?username=ferry&password= sk8e49nds&recipient=31612345678 &message=dit%20is%20een%20test%20bericht.&route=biz Voorbeeld 2 Bij dit voorbeeld gaan we ervan uit dat u bepaalde vaste waardes wilt overschrijven die zijn ingesteld op SMSStunter. We maken gebruik van de lange sms bericht mogelijkheid en we sturen een andere afzender mee. Dit is te zien bij de laatste twee parameters. http://gateway.smsstunter.nl/?username=ferry&password= sk8e49nds&recipient=31612345678 &message=dit%20is%20een%20test%20bericht%20die%20bestaat%20uit%20meer%20d an%20160%20karakters%20en%20dus%20eigenlijk%20te%20lang%20is%20voor%20ee n%20normaal%20sms%20bericht,%20maar%20wel%20ondersteund%20wordt%20door% 20de%20smsstunter%20gateway%20en%20waar%20wij%20dus%20op%20dit%20mome nt%20gebruik%20van%20maken%20door%20het%20parameter%20type%20mee%20te %20sturen.&route=biz&sender=smsstunter&type=long 7

6. DLR Als u bij uw gegevens een DLR URL opgeeft zal de gateway na het versturen van een SMS deze URL op de volgende wijze aanroepen: [UW_DLR_URL]?reference=[UWREFERENTIE]&recipient=[TELNUMMER]&status=[STATUS] UWREFERENTIE is de referentie welke u heeft meegegeven bij de HTTP request. TELNUMMER is het (evt. aangepaste) telefoonnummer in de vorm 31612345678. Het nummer wordt aangepast als deze door U in een andere vorm wordt meegegeven bij de HTTP request (06x, +31x, 0031x) STATUS is een numerieke waarde met de volgende betekenis: 0 => Buffered / Unknown 1 => Delivered 2 => Not Delivered 7. Email 2 SMS Als u bij uw settings heeft aangegeven dat u Mail2SMS wil versturen over een bepaalde route (biz of eco), dan is er de mogelijkheid om een sms te versturen door een email te sturen naar [telefoonnummer]@sms.smstunter.nl. Alle telefoonnummers in het To veld zullen de sms ontvangen, cc en bcc worden genegeerd. Het From adres van de email dient overeen te komen met het door u opgegeven email adres in uw settings. Het onderwerp van de email kan gebruikt worden om de afzender van de sms mee te geven, m.a.w. de ontvanger van de sms ziet als afzender wat u in het onderwerp heeft ingevuld. Alle tekst in de email wordt doorgestuurd in de sms. Als u meer tekens verstuurt dan er in een sms bericht passen zal deze niet worden verstuurd. Als u niet heeft ingesteld dat u lange smsjes wil kunnen versturen is het maximum aantal tekens 160, anders 764. 8