SMS Webservice Implementatie handleiding Versie 1.2
Inhoudspagina Versiebeheer... 2 Overzicht webservice... 2 Begrippenlijst... 2 Starten met de straightxs webservice... 3 Algemene beschrijving van de webservice methodes... 3 cancelsms functie... 4 querycoverage functie... 5 querysmsbalance functie... 6 sendsms functie... 6-1 -
Versie Versiebeheer van dit document : Versie Datum Omschrijving 1.0 20 september 2009 1.1 25 oktober 2009 sendsms call aangepast voor flash SMS 1.2 3 december 2009 Aanpassing cancelsms feauture Overzicht webservice In dit document wordt de SMS webservice van straightxs beschreven. Alvorens u van start gaat met implementatie van deze dienst dient u : - Te beschikken over basis kennis voor gebruik van webservices binnen uw ontwikkelomgeving; - Een getekende overeenkomst voor gebruik van deze dienst aan straightxs te hebben overlegd; - Te beschikken over een gebruikersnaam, wachtwoord en API ID uitgegeven door straightxs; Er zijn verschillende manier om de SMS gateway van straightxs middels deze webservice te benaderen: - HTTP / HTTPS, het verzenden van GET of POST bericht naar de webservice; - XML, het verzenden van een XML bericht over HTTP(s) naar de webservice; - SOAP, het verzenden van een SOAP bericht over HTTP(s) naar de webservice; Indien gewenst kan een SMPP verbinding tussen uw platform en de webservice van straightxs gerealiseerd worden. Deze optie is alleen van toepassing bij zeer gebruik van 10.000+ berichten per dag. Begrippenlijst Bericht identificatienummer Uniek door straightxs toegekend berichtnummer van uw SMS. Uw eigen identificatienummer Een door u toegekende identificatie aan een bericht. Het toekennen van een identificatie geschied bij het verzenden van het bericht en is niet meer te wijzigen. Deze identificatie hoeft niet uniek te zijn. - 2 -
Starten met de straightxs SMS webservice Om te starten met de SMS webservice doorloopt u de navolgende stappen: Stap 1 - Aanvragen account bij straightxs U dient een account aan te vragen bij straightxs om toegang te krijgen tot het SMS platform. U ontvangt van straightxs bij aanvraag van een account een gebruikersnaam, wachtwoord en API identifier. U heeft deze unieke combinatie nodig om u te identificeren bij de webservice. Stap 2 - Aanvragen senderid status bij straightxs U kunt een eigen senderid status verkrijgen bij straightxs. De senderid status is een tekst string van 8 tekens welke als afzender van een SMS wordt meegegeven. Het reguliere SMS gateway nummer welke standaard als afzender wordt gegeven vervalt hiermee. Stap 3 - Inkoop SMS credits Alvorens u van start kunt gaan met het verzenden van SMS berichten dient u een tegoed in te kopen. Raadpleeg het bestelformulier bij u overeenkomst voor de juiste werkwijze. Algemene beschrijving van de webservice methodes De straightxs SMS webservice kent een 5-tal functies welke u kunt gebruiken. Alle methodes zijn voorzien van een Service Description (SD). De webservice is toegankelijk middels de navolgende URL: http://sms.straightxs.nl/straightxs_sms.asmx De Service Description (SD) welke u kunt gebruiken in uw ontwikkelomgeving (bijvoorbeeld Visual Studio) heeft de navolgende URL: http://sms.straightxs.nl/straightxs_sms.asmx?wsdl De navolgende methodes zijn actief : Methode URL Omschrijving CancelSMS /straightxs_sms.asmx?op=cancelsms Annulering aflevering van een sms querycoverage /straightxs_sms.asmx?op=querycoverage Controleer routing SMS bericht querysms /straightxs_sms.asmx?op=querysms Track de aflevering van een SMS querysmsbalance /straightxs_sms.asmx? op=querysmsbalance Opvragen SMS tegoed sendsms /straightxs_sms.asmx?op=sendsms Verstuur een SMS - 3 -
cancelsms functie De cancelsms functie stelt u in staat om de aflevering van een SMS te annuleren. Wanneer u een SMS verzend naar een toestel welke uit staat wordt deze in een aflever queu bij de desbetreffende telecomprovider geplaatst. U kunt een bericht uit deze queu halen door de cancelsms functie te gebruiken. Let op, u kunt de aflevering van een bericht welke al is ontvangen door de ontvangende telefoon niet annuleren daar deze niet meer in de aflever queu aanwezig is. De cancelsms functie kent de navolgende methodes: messageid Bericht identificatienummer Nee customerreference Uw eigen identificatienummer Nee querycoverage functie De querycoverage functie stelt u in staat om te controleren of een bericht aan een opgegeven mobiel nummer kan worden afgeleverd. Deze functie wordt veelal gebruikt om te controleren of problemen van SMS aflevering na porteringen van nummers tussen telecomproviders hierdoor veroorzaakt worden. De querycoverage functie kent de navolgende methodes: destinationnumber Mobiel telefoonnummer Ja - 4 -
querysms functie De querysms functie stelt u in staat een SMS bericht te tracken.u kunt realtime controleren wat de afleverstatus van een bericht is.de status kunt u middels een bericht identificatienummer of een eigen identificatienummer opvragen. messageid Bericht identificatienummer Nee customerreference Uw eigen identificatienummer Nee De webservice functie retourneert de navolgende status codes: Status code Omschrijving 001 Afgeleverd bij ontvangen 002 Bericht niet bekend binnen webservice 003 Bericht is in de aflever queu geplaatst 004 Bericht is verzonden aan de telecom gateway 005 Fout in bericht inhoud, niet afgeleverd 006 Aflevering geannuleerd door opdrachtgever 007 Fout bij het afleveren van het bericht 008 Bericht ontvangen door secundaire gateway 009 Bericht routeringsfout, controleer routing path 010 Bericht bewaartijd verstreken, bericht verwijderd 011 Bericht is ingepland voor aflevering op later tijdstip 012 Geen SMS tegoed meer aanwezig 013 De nummer prefix wordt niet ondersteund 014 Authenticatie met de webservice onjuist - 5 -
querysmsbalance functie Deze functie gebruikt u om het SMS tegoed wat binnen uw account aanwezig is realtime op te vragen. Mocht u bij het verzenden of tracken van een SMS de foutcode 012 geretourneerd krijgen kunt u deze functie gebruiken om het balans tegoed te raadplegen. sendsms functie Voor het verzenden van SMS berichten gebruikt u de sendsms functie van de webservice. Deze functie kent onderstaande methodes: destinationnumber Mobiel telefoonnummer Ja senderid Uw geregistreerde zender ID Ja customerreference Uw eigen identificatienummer Ja messagecontent Inhoud van uw SMS bericht Ja messagetype Het type bericht dat u verzend Ja De functie retourneert een uniek identificatienummer. Dit bericht identificatienummer kunt u eveneens gebruiken om berichten te tracken middels de de querysms functie. Enkele parameters worden onderstaand nader toegelicht: SenderID : De sender ID tekst string dient identiek te zijn aan de door u geregistreerde tekst string. Deze is eveneens hoofdletter gevoelig. messagecontent : De inhoud van uw bericht. Let wel, er vindt een SPAM scanning plaats op de uitgezonden berichten. messagetype : Hierin kunt u het type bericht opgeven. Ook deze tekst string is hoofdletter gevoelig. In de tabel binnen deze paragraaf treft u een overzicht van de actieve messagetype waarden. - 6 -
De functie messagetype kent de navolgende waarden: messagetype SMS_TEXT SMS_FLASH Omschrijving Standaard SMS bericht Netwerk operator bericht, wordt niet opgeslagen SMS_NOKIAOLOGO Netwerk operator logo voor een Nokia toestel SMS_NOKIAGLOGO Group logo voor een Nokia toestel SMS_NOKIA_VCAL Event business calander verzoek voor een Nokia toestel De SMS_FLASH waarde toont het bericht direct op een telefoon. Nadat het bericht is gelezen kan deze niet worden opgeslagen op de telefoon. Bij een succesvolle transactie retourneert de webservice een uniek identificatienummer van het bericht. Echter, bij een onsuccelvolle transactie wordt de navolgende status code lijst gehanteerd: Status code Omschrijving 001 Afgeleverd bij ontvangen 002 Bericht niet bekend binnen webservice 003 Bericht is in de aflever queu geplaatst 004 Bericht is verzonden aan de telecom gateway 005 Fout in bericht inhoud, niet afgeleverd 006 Aflevering geannuleerd door opdrachtgever 007 Fout bij het afleveren van het bericht 008 Bericht ontvangen door secundaire gateway 009 Bericht routeringsfout, controleer routing path 010 Bericht bewaartijd verstreken, bericht verwijderd 011 Bericht is ingepland voor aflevering op later tijdstip 012 Geen SMS tegoed meer aanwezig 013 De nummer prefix wordt niet ondersteund 014 Authenticatie met de webservice onjuist - 7 -