SMS Webservice Implementatie handleiding Versie 1.2
Inhoudspagina Versiebeheer..................................................................................... Overzicht webservice......................................................................... Begrippenlijst................................................................................... Starten met de straightXS webservice.................................................. Algemene beschrijving van de webservice methodes.............................. cancelSMS functie............................................................................. queryCoverage functie....................................................................... querySMSbalance functie................................................................... sendSMS functie...............................................................................
-1-
2 2 2 3 3 4 5 6 6
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
Verstuur een SMS
/straightXS_SMS.asmx?op=sendSMS
-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: Parameter
Omschrijving
username
Uw gebruikersnaam
Ja
password
Uw wachtwoord
Ja
uniqueID
Uw API ID
messageID
Verplicht
Ja
Bericht identificatienummer
customerReference Uw eigen identificatienummer
Nee 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: Parameter
Omschrijving
Verplicht
username
Uw gebruikersnaam
Ja
password
Uw wachtwoord
Ja
uniqueID
Uw API ID
Ja Ja
destinationNumber Mobiel telefoonnummer
-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. Parameter
Omschrijving
username
Uw gebruikersnaam
Ja
password
Uw wachtwoord
Ja
uniqueID
Uw API ID
messageID
Verplicht
Ja
Bericht identificatienummer
customerReference Uw eigen identificatienummer 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-
Nee Nee
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. Parameter
Omschrijving
Verplicht
username
Uw gebruikersnaam
Ja
password
Uw wachtwoord
Ja
uniqueID
Uw API ID
Ja
sendSMS functie Voor het verzenden van SMS berichten gebruikt u de sendSMS functie van de webservice. Deze functie kent onderstaande methodes: Parameter
Omschrijving
Verplicht
username
Uw gebruikersnaam
Ja
password
Uw wachtwoord
Ja
uniqueID
Uw API ID
Ja
destinationNumber Mobiel telefoonnummer
Ja
senderID
Ja
Uw geregistreerde zender ID
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
Omschrijving
SMS_TEXT
Standaard SMS bericht
SMS_FLASH
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-
