Teknisk Dokumentation för SMS-tjänsten

Teknisk Dokumentation för SMS-tjänsten

Innehållsförteckning 1. Innehållsförteckning 1. INNEHÅLLSFÖRTECKNING... 2 2. DOKUMENTHISTORIK... 3 3. INLEDNING... 4 3.1 OM MANUALEN... 4 3.2 OM SMS-TJÄNSTEN... 4 3.3 MANUALENS UPPLÄGG... 4 4. MOTIVERING... 5 4.1 FÖRDELEN MED SMS... 5 4.2 NÅGRA EXEMPEL... 5 4.3 HUR EHOSTER ANVÄNDER SMS-TJÄNSTEN... 5 5. SYSTEMÖVERSIKT... 6 5.1 ÖVERSIKT... 6 5.2 KOMMUNIKATIONSFLÖDE... 6 6. ANVÄNDNING... 8 6.1 ALLMÄNT... 8 6.2 METOD 1: PHP-FUNKTION... 8 6.3 METOD 2: API-LÖSNING ÖVER HTTPS... 9 7. PARAMETRAR... 11 7.1 TABELL ÖVER TILLGÄNGLIGA PARAMETRAR... 11 7.2 OBLIGATORISKA PARAMETRAR... 11 7.2.1 Mottagare (to)... 11 7.2.2 Meddelande (msg)... 11 7.3 FRIVILLIGA ARGUMENT... 11 7.3.1 Strikt läge (strict)... 11 7.3.2 Meddelandetyp (type)... 12 7.3.3 Avsändare (from)... 12 7.3.4 Fördröjning (delay)... 12 7.3.5 Referens (ref)... 12 8. APPENDIX... 13 A. FELKODER... 13 2

Dokumenthistorik 2. Dokumenthistorik Version Datum Förändring 1.2.0 2009-03-23 Dokumentation för att använda egna avsändarnummer. Ny felkod för registrerade men ännu inte aktiverade nummer. 1.1.0 2008-07-24 Ny parameter (type). Möjligt att skicka flashmeddelanden. Några oanvända felkoder har tagits bort. Antal referenser har sänkts från två till en. 1.0.1 2007-12-06 Valfritt avsändarnamn inte längre möjligt. 1.0.0 2007-10-02 Första versionen. Figur 1. Dokumenthistorik. 3

Inledning 3. Inledning 3.1 Om manualen Denna manual är skriven och helt anpassad för ehosters system. Manualen beskriver hur vår SMS-tjänst fungerar och hur den kan användas. Den senaste versionen av manualen kan alltid laddas ner från vår hemsida, http://ehoster.se. 3.2 Om SMS-tjänsten SMS-tjänsten är en tjänst för att skicka SMS från ehosters webbservrar. SMS-tjänsten är enbart tillgänglig för kunder hos ehoster och måste först aktiveras via ehosters kontrollpanel Kundavdelning innan den kan användas. Mer information om SMS-tjänsten hittas på ehosters hemsida. 3.3 Manualens upplägg Först av att allt ges lite motiveringar/inspiration till hur SMS-tjänsten kan användas. Sedan beskrivs tjänsten uppbyggnad och hur man använder den. 4

Motivering 4. Motivering 4.1 Fördelen med SMS SMS kan naturligtvis inte mäta sig med mail när det gäller att skicka stora och avancerade meddelanden. SMS har dock ett triumfkort och det är direktkontakt. Förutsatt att mottagaren har sin mobiltelefon på sig kan ett meddelande nå fram med bara 5-10 sekunders fördröjning. Motsvarig tid för mail kan vara några timmar upp till flera dygn beroende på hur ofta mottagaren läser av sin mailbox. 4.2 Några exempel Det finns många bra exempel på hur man kan använda SMS-tjänsten, nedanför finns några. Nya mail. Skicka ett SMS när du har fått ett nytt mail. Smidigt om du har en mailbox som tar emot relativt små mängder mail. Imponera på kunderna genom att svara inom loppet av några minuter. Exempelscript finns att ladda ner från Kundavdelningen (Mailbevakaren). Validering. Om du driver en community eller liknande kan det vara bra om nya medlemmar validerar sina uppgifter. Detta kan göras genom att skicka ut ett mail med en aktiveringslänk vilket validerar att mailadressen är äkta. Det är dock lätt att skapa nya mailadresser så ett bättre sätt är att validera mobilnummer via SMS då det är betydligt krångligare att skaffa nya mobilnummer. Notifiering. Meddela dig själv via SMS när något speciellt händer på din hemsida. Exempelvis vid ny beställning. Kvitto. Skicka ett kvitto/tackmeddelande till dina kunder när de köpt något på din hemsida. Varför inte använda SMS-tjänsten för att skicka ut leveransinformation? Massutskick. Att skicka SMS till många mottagare kan vara krångligt och ta tid, varför inte använda SMS-tjänsten för detta ändamål? Exempelscript finns att ladda ner från Kundavdelningen (SMS-listan). 4.3 Hur ehoster använder SMS-tjänsten Nedanför följer några goda exempel på hur vi utnyttjar SMS-tjänsten: Supportärenden. När ett supportärende inte har besvarats inom en bestämd tid eller när ett akutärende skapas används SMS-tjänsten för att skicka notifierings-sms. Detta gör att vi kan svara på akutärenden direkt och aldrig missa ett supportärende. Betalningspåminnelse. Via Kundavdelningen kan våra kunder välja om de vill ha betalningspåminnelse via SMS. Detta minskar antal försenade fakturor. Ny kund. När en ny kund registrerar sig på vår hemsida skickas ett SMS vilket gör att vi snabbt kan granska och aktivera kundens konto. Snabb behandling ger ett bra första intryck. Driftstatus. Våra servrar bevakar varandra jämt och ständigt. Om något fel upptäcks blir vi meddelade via SMS och kan därmed börja bearbeta problemet tidigt. 5

Systemöversikt 5. Systemöversikt 5.1 Översikt SMS-tjänsten är väldigt lätt att använda. Vi har satsat mycket tid på att få systemet så användarvänligt som möjligt utan att för den delen begränsa möjligheterna. Själva processen att skicka ett SMS är däremot en komplicerad historia där många företag, servrar och nät är inblandade men var lugn, den biten tar vi hand om! 5.2 Kommunikationsflöde Kommunikationsflödet/dataflödet är följande: 1. En användare besöker din hemsida via en webbläsare eller annat verktyg. 2. Din hemsida skickar nödvändig data till ehosters SMS-server för att skicka ett SMS. 3. SMS-servern registrerar data och skickar vidare uppgifter till en av flera SMS-leverantörer. 4. SMS-leverantören skickar SMS-meddelandet till mottagarens (mobil)operatör. 5. Operatören använder GSM-nätet för att skicka SMS:et till mottagaren. 6. Eventuell leveransrapport skickas hela vägen tillbaka till hemsidan. Se illustrationen på nästa sida för att få en klarare bild över flödet. Som synes är flödet ganska stort/långt vilket indirekt betyder tillgänglighetsproblem. Om någon del av kedjan krånglar betyder det att SMS-tjänsten blir otillgänglig. Som användare bör du vara införstådd med detta och använda dig av felhantering för att hantera de fall då det inte går att skicka SMS. Då SMS-tjänsten i skrivande stund är relativt ny är det svårt att uppskatta tillgängligheten, men räkna med att den fungerar åtminstone 99% av tiden. 6

Systemöversikt Internet Webbklient Sändare/Aktiverare API Lokal SMS-server PHP-funktion Lokalt nätverk Lokal webbserver Systemöversikt för SMS-tjänsten Internet GSM-nätverket SMSleverantör SMS-klient Mottagare Figur 2. SMS-tjänstens systemöversikt 7

Användning 6. Användning 6.1 Allmänt SMS-tjänsten kan användas på två sätt. Antingen använder man vår enkla och specialutvecklade PHP-funktion (som redan är implementerad på våra servrar), eller så använder man en traditionell API-lösning över HTTPS-protokollet. Båda metoder bjuder på samma funktionalitet, vilken som väljs har därför liten betydelse om man använder PHP som scriptspråk. Generellt kan man säga att avancerade användare bör använda API-lösningen (ju mindre beroende desto bättre) medan övriga användare bör använda PHP-funktionen då den är betydligt enklare att förstå sig på. För att kunna använda SMS-tjänsten måste man först aktivera tjänsten. Detta görs via Kundavdelningen. Om API-metoden används måste också ett lösenord sättas vilket också görs via Kundavdelningen. SMS:en utformas med hjälp av parametrar. Obligatoriska parametrar är to och msg men fler kan läggas till efter eget behag. Samtliga parametrar beskrivs i nästa kapitel. 6.2 Metod 1: PHP-funktion PHP-funktionen har utvecklats för att göra det lätt att skicka SMS. Allt du behöver för att skicka ett SMS med meddelandet Hej till mobilnumret 0701234567 är följande PHP-rad: @ehoster_sms_send('0701234567', 'Hej'); Funktionen ehoster_sms_send är definierad enligt: array ehoster_sms_send(string $to, string $msg [, array $params]) Funktionen ehoster_sms_send tar alltså två obligatoriska argument, mottagarens nummer och själva meddelandet. För att använda fler parametrar används ett tredje argument som innehåller en array med parametrar. Notera @-tecknet innan funktionsnamnet i exemplet ovan, detta gör att eventuella PHP-felmeddelande inte visas. För att sätta avsändarnamnet till Företag AB kan följande PHP-rad användas: @ehoster_sms_send('0701234567', 'Hej', array('from'=>'företag AB')); OBS! Från och med december 2007 måste avsändarnamn/nummer registreras innan de kan användas som avsändare. Detta för att minska risken för spoofing. Registrering sker i Kundavdelningen. För att dessutom fördröja SMS:et 60 minuter kan följande PHP-rad användas: @ehoster_sms_send('0701234567', 'Hej', array('from'=>'företag AB', 'delay'=>60)); Funktionen returnerar en array med en statuskod och ett statusmeddelande för det skickade meddelandet. Denna array kan användas för felhantering om utskicket skulle misslyckas. Följande PHP-rader är exempel på grundläggande felhantering. $result = @ehoster_sms_send('0701234567', 'Hej'); if ($result['errcode']!= 0) 8

Användning echo 'SMS:et kunde inte skickas. Orsak: '.$result['errmsg']; Testa med att byta ut mobilnumret till exempelvis 123 för att testa felhanteringen. Alla statuskoder/felkoder kan hittas i appendix. 6.3 Metod 2: API-lösning över HTTPS API-lösningen är till för dig som kan lite mer om PHP. API-lösningen kräver fler rader kod än PHP-funktionen, men är mindre beroende av att PHP-funktionen är tillgänglig. Notera att API-lösningen enbart kan användas från ehosters webbservrar. Anrop från andra servrar ignoreras. API-metoden består av två delar, dels måste en API-sträng byggas upp och dels så måste den skickas iväg. Exempel på hur API-strängen byggs upp: $api_string = 'https://sms.ehoster.se/api.php?user=1234&pass=mittlösenord'; $api_string.= '&to=0701234567'; $api_string.= '&msg='.urlencode('mitt meddelande'); För att sedan skicka API-strängen kan följande rader kod användas: // Använd curl om möjligt. if (extension_loaded('curl')) { $ch = curl_init($api_string); curl_setopt($ch, CURLOPT_HEADER, 0); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); curl_setopt($ch, CURLOPT_TIMEOUT, 20); $result = curl_exec($ch); if(curl_error($ch)!="") { curl_close($ch); die('fel vid anslutning med curl'); } curl_close($ch); } // I annat fall, använd fopen. else { $result = ''; $handler = @fopen($api_string, 'r'); if ($handler) { while ($line = @fgets($handler,1024)) $result.= $line; fclose($handler); } else die('fel vid anslutning med fopen'); } 9

Användning För felhantering undersöks variabeln $result. Formatet på resultatet är XXXXRRRRRRRRMSG där XXXX är statuskoden/felkoden, RRRRRRRR reserverade tecken, och MSG en beskrivning av statuskoden. Om SMS:et skickats iväg utan problem ges följande resultat: 000000000000SMS:et skickat Låt säga att mottagarnumret är för kort, då ges följande resultat. 003400000000Mottagare: För kort nummer (min: 9) Data kan hämtas ut från strängen och lagras i variabler på följande vis: $errcode = intval(substr($result, 0, 4)); $errmsg = substr($result, 12); Samtliga statuskoder finns listade i appendix. 10

Parametrar 7. Parametrar SMS-tjänsten kan anropas på två olika sätt enligt kapitel 6. Gemensamt för båda tillvägagångssätten är dess parametrar som beskrivs i detta kapitel. 7.1 Tabell över tillgängliga parametrar Parameter Beskrivning Datatyp Giltiga värden Standardvärde to * Mottagare Heltal 9-15 siffror msg * Meddelande Sträng 1-160 tecken strict Strikt läge Heltal 0 = inaktiverad 0 1 = aktiverad type Meddelandetyp Sträng sms, flash sms from Avsändare Sträng Registrerad avsändare ehoster SMS delay Fördröjning Heltal 1-10080 Används ej (Antal minuter) ref Referens Heltal 0-999999999 0 Figur 3. Tabell över tillgängliga argument. * Obligatoriskt argument. 7.2 Obligatoriska parametrar 7.2.1 Mottagare (to) Numret till mottagaren. Numret får bara innehålla siffror och måste skrivas på internationell form (landskod + nummer utan nolla i början). Numret 070-1234567 blir alltså 46701234567 på internationell form. Om strikt läge (parameter strict) är inaktiverat kommer systemet att försöka rätta till numret om något uppenbart fel hittas. T.ex kan typiska mobilnummer som saknar landskod korrigeras (0701234567 översätts automatiskt till 46701234567) 7.2.2 Meddelande (msg) SMS:ets meddelande. Kan vara upp till 160 tecken långt. Om strikt läge är inaktiverat och meddelandet är över 160 tecken kommer allt efter de första 160 tecknen att klippas bort. 7.3 Frivilliga argument 7.3.1 Strikt läge (strict) Används för att aktivera strikt läge. Vid strikt läge stoppas alla SMS som innehåller ett eller flera fel. När strikt läge är inaktiverat (standard) försöker systemet att lösa problem automatiskt om möjligt (exempelvis kapas meddelande längre än 160 tecken och mottagarnummer som saknar landskod får landskod 46). 11

Parametrar 7.3.2 Meddelandetyp (type) Även om SMS-tjänsten främst är till för att skicka SMS går det även att skicka andra meddelandetyper. Detta kan göras genom att sätta parametern type. Värde Typ av meddelande Beskrivning sms SMS-meddelande Vanligt SMS-meddelande. flash Flashmeddelande Meddelandet dyker upp direkt på displayen vilket gör att mottagaren blir tvungen att läsa meddelandet. Meddelandet lagras däremot inte hos mottagaren (vilket ett vanligt SMS gör). 7.3.3 Avsändare (from) Parametern from sätter meddelandets avsändare. Avsändaren kan antingen vara ett nummer upp till 15 siffror eller en textsträng på upp till 11 tecken. För tillfället går det bara att använda nummer som avsändare samt namnet ehoster SMS. Från och med december 2007 måste avsändarnamn/nummer registreras innan de kan användas som avsändare. Detta för att minska risken för spoofing. Registrering sker i Kundavdelningen. Om strikt läge är inaktiverat kommer ehoster SMS att sättas som avsändare om valt avsändarnamn/nummer inte är registrerat. OBS! Notera att avsändarfunktionen inte fungerar för SMS som skickas till USA. 7.3.4 Fördröjning (delay) Parametern delay ger möjlighet att fördröja ett meddelande upp till en vecka. Fördröjningen anges i antal minuter. Korta fördröjningar (< 10 minuter) kan ge oprecisa resultat. 7.3.5 Referens (ref) Parametern ref kan användas för att märka SMS så att de kan spåras i efterhand via ehoster kontrollpanel Kundavdelningen. Exempelvis kan en community, där medlemmarna tillåts skicka SMS, binda medlemmarnas ID till varje SMS. 12

Appendix 8. Appendix A. Felkoder KOD BESKRIVNING OMRÅDE 0 Inget fel, SMS:et skickat 1 Parameterfel 1-9 2 Anslutning till SMS-server Fel relaterade till PHPfunktionen 3 Tolkning av data 4 Oväntat lokalt fel 5 PHP-relaterat fel 6-9 RESERVERADE KODER 10 Parameterfel 10-29 11 Ogiltig IP-adress Fel relaterade till SMSservern 12 Tjänsten inaktiverad och SMS- 13 Authentisering misslyckad leverantörer 14 SMS-konto ej aktiverat 15 Daglig SMS-kvot nådd 16 Månatlig SMS-kvot nådd 17 Fel vid anslutning till SMS-leverantör 18 Fel vid tolkning av data från SMS-leverantör 19 Oväntat fel på SMS-servern 20 Oväntat fel hos SMS-leverantör 21 PHP-relaterat fel 21-29 RESERVERADE KODER 30 För kort meddelande 30 99 31 För långt meddelande Ogiltiga parametrar 32-33 RESERVERADE KODER 34 För kort mottagarnummer 35 För långt mottagarnummer 36 Ogiltigt nummerformat 37-39 RESERVERADE KODER 40 Avsändare inte aktiverad (än) 41 Avsändare ej registrerad 42 RESERVERAD KOD 43 Referens icke-numerisk 44 Referens för litet (< 0) 45 Referens för stort (>999999999) 46-47 RESERVERADE KODER 48 Meddelandetyp ej giltig 49-52 RESERVERADE KODER 30-33: Meddelande 34-39: Mottagare 40-42: Avsändare 43-47: Referens 48-52: Meddelandetyp 53-57: Delay 13

Appendix 53 Icke-numerisk fördröjning 54 För kort fördröjning (< 1) 55 För lång fördröjning (> 10800) 56-57 RESERVERADE KODER 14