K U U L A L A A K E R I LUOTTAMUKSELLINEN 1(6)

Transkriptio

1 K U U L A L A A K E R I LUOTTAMUKSELLINEN 1(6) Messto HTTP API Messto HTTP API on sovelluskehittäjiä varten kehitetty helppo tapa toteuttaa tekstiviesti- ja multimediaviestisovelluksia. Rajapinnan avulla voidaan esimerkiksi integroida tekstiviestinlähetys olemassaoleviin sovelluksiin ja palveluihin. Messto Basicin avulla voidaan lähettää tekstiviestejä kaikkiin suomalaisiin matkapuhelinliittymiin. Messto Pron avulla voidaan lisäksi vastaanottaa teksti- ja multimediaviestejä kaikista suomalaisista matkapuhelinliittymistä. Messto Pro sisältää myös Messto Basicin ominaisuudet. Sisältö Lähetys...2 Palvelimen URL... 2 Pakolliset muuttujat tekstiviesteille (SMS)...2 Valinnaiset muuttujat tekstiviesteille (SMS)...2 Muuttujat multimediaviesteille (MMS)...3 Maksulliset push-viestit (SMS)...3 Esimerkki (SMS ja MMS)...3 Vastaanotto...4 Palvelun kytkeminen...4 Palvelun asetukset...4 Sovellusten luominen...4 Sovellukselle välitettävät muuttujat...4 Esimerkki QLA MS text sovelluksesta...5 Esimerkki QLA MS extended sovelluksesta...6 Virhelogi...6

2 K U U L A L A A K E R I LUOTTAMUKSELLINEN 2(6) Lähetys Palvelimen URL Salaamattomana: SSL-salauksella: Tekstiviestin (SMS) lähetyksessä voidaan käyttää HTTP POST (suositus) tai HTTP GET-muotoa. Multimediaviestin (MMS) lähetyksessä pitää käyttää HTTP POST muotoa. Pakolliset muuttujat tekstiviesteille (SMS) sms_username sms_password sms_dest sms_text Messto HTTP API-palvelun käyttäjätunnus. Messto HTTP API-palvelun salasana. Vastaanottajan matkapuhelinnumero, kansainvälisessä (+358 ) muodossa. Lähetettävä tekstiviesti ISO merkistöllä. Jos haluat lähettää moniosaisia tekstiviestejä, voit antaa sms_text-kenttään yli 160-merkkiä pitkän viestin. Messto huolehtii viestin jakamisesta osiin. Valinnaiset muuttujat tekstiviesteille (SMS) sms_binary Voidaan käyttää sms_text:n sijaan lähetettäessä binääriviestejä. sms_unicode Voidaan käyttää sms_text:n sijaan lähetettäessä unicode-viestejä. sms_udh Viestiin liitettävä User Data Header. sms_source Viestin lähettäjänä näkyvä teksti. Sallitu teksti on hyväksyttävä ensin Kuulalaakeri Oy:llä. URL jota kutsutaan, kun viestille on saatu sms_receipt toimituskuittaus. Pyyntöön lisätään onnistuneessa toimituksessa arvo &receipt_value=ack tai epäonnistuneessa &receipt_value=nack. sms_delayed_abs Viestin viivästetty lähetys, muodossa yyyymmddhhmm (UTC ajassa) sms_delayed_rel Viestin viivästetty lähetys sekunteina nykyisestä sms_valid_abs Viestin viimeinen voimassaoloaika, muodossa yyyymmddhhmm. sms_valid_rel Viestin voimassaoloaika sekunteina nykyisestä sms_pid Protocol identifier (GSM 03.40). sms_class Viestin luokka (GSM 03.40). sms_tariff Viestin hintaluokka, katso kohta maksulliset pushviestit. Odotetaan vastausviestiä ilman avainsanaa. sms_magicmapping Muuttujan arvoksi annetaan kaksisuuntaisen palvelun avainsana ilman yrityskohtaista alkuosaa (esim. QLA TILAUS -> TILAUS). 1 sms_magicmapping_ttl Vaustausviestin odotusaika sekunteina (max = 1 vuorokausi, oletus 86400) Binääriviesti ja UDH tulee enkoodata 8-bitin ryhmissä, esimerkiksi XYZ on enkoodattuna 58595a. Unicode-viestit tulee enkoodata 16-bitin ryhmissä, esimerkiksi XYZ on enkoodattuna a.

3 K U U L A L A A K E R I LUOTTAMUKSELLINEN 3(6) Muuttujat multimediaviesteille (MMS) username password from to subject content_namex content_typex content_bodyx Messto HTTP API-palvelun käyttäjätunnus. Messto HTTP API-palvelun salasana. Viestin lähettäjä (ei pakollinen). Hyväksyttävä ensin Kuulalaakeri Oy:llä. Vastaanottajan matkapuhelinnumero, kansainvälisessä (+358 ) muodossa. Viestin otsikko UTF-8 merkistöllä. Liitetiedoston nimi (X=1-99). Liitetiedoston mime-tyyppi (X=1-99). Liitetiedoston sisältö (X=1-99). Multimediaviestit koostuvat yhdestä tai useammasta osasta (teknisesti ottaen liitetiedostoja), esimerkiksi tekstistä (.txt text/plain), kuvista (.jpg image/jpeg tai.gif image/gif) ja smil-esityksestä (.smil application/smil). Suositeltava merkistökoodaus tekstiliitteille on UTF-8 (text/plain; charset=utf-8). Sisältö enkoodataan asciiheksaksi 8-bitin ryhmissä, esimerkiksi Messto on enkoodattuna 4d f. Maksulliset push-viestit (SMS) Push-viestien tilaajan tulee liittyä Messton push-ryhmään erikseen Kuulalaakeri Oy:n kanssa sovittavalla avainsanalla. Messto poistaa tilaajat push-ryhmästä automaattisesti lopetusviestin tullessa (esim : PUSH SULJE tai 17252: STOP). Avainsanaa käytetään sms_tariff parametrinä lähetettäessä maksullisia push-viestejä. Ennen lähetystä voi Messton osoitekirjasta kysyä aktiiviset push-tilaajat http-kyselyllä: Push-ryhmän nimi on muotoa palvelunumero + välilyönti + avainsana, ylläolevassa esimerkissä se on push. Jos tilaaja ei kuulu push-ryhmään lähetys ei onnistu ja http-kysely palauttaa virhetekstin. Esimerkki (SMS ja MMS) Lähetetään alla mainittu HTTP-pyyntö palvelimelle. Tekstiviesti (SMS): kehveli&sms_dest=%2b &sms_text=Terveisi%e4+Messtosta Multimediaviesti (MMS): &to=%2b &subject=otsikko&content_name1=text.txt &content_type1=text%2fplain%3b+charset%3dutf-8 &content_body1= c3a4204d f Palvelin vastaa seuraavasti (Content-Type: text/plain, rivinvaihtona \n ): Onnistunut lähetys: rivi 1: OK rivi 2: <lisätietoa lähetyksestä tai rivi 2 puuttuu kokonaan> Epäonnistunut lähetys (esim. virheellinen tunnus tai virheelliset parametrit): rivi 1: ERROR rivi 2: <virheteksti>

4 K U U L A L A A K E R I LUOTTAMUKSELLINEN 4(6) Vastaanotto Messton HTTP-lisäpalvelulla voit ohjata saapuneita teksti- (sms) ja multimediaviestejä (mms) omalle sovelluksellesi. Sovellus voi lähettää vastauksen viestiin. Palvelun kytkeminen Luo tarvittaessa uusi avainsana, jota haluat käyttää HTTPlisäpalvelun kanssa. Valitse Kaksisuuntaiset Palvelut valikosta avainsana, johon saapuneet viestit haluat ohjata HTTP-lisäsovellukselle. Valitse Saapunut viesti -pudotusvalikosta vaihtoehto Ohjataan lisäpalvelulle:http. Aseta muutokset voimaan klikkaamalla Muuta-painiketta. Palvelun asetukset Palveluun ohjatut avainsanat näkyvät Lisäpalvelut-valikon alla. Valitse Lisäpalvelut-valikon alta avainsana, jonka asetuksia haluat muuttaa. Määrittele avainsanalle sovelluksesi URL, jota kutsutaan viestin saapuessa palveluun. Tuettu protokolla on Aseta rajapinnan tyypiksi QLA MS text (suositus) tai QLA MS extended. Aseta muutokset voimaan klikkaamalla Muuta-painiketta. Sovellusten luominen Sovelluksissa on käytettävä QLA MS text tai QLA MS extended - rajapintaa. Rajapinta vaikuttaa siihen miten sovelluksen pitää lähettää vastausviesti tilaajalle. Käytettäessä QLA MS text rajapintaa kaikki sovelluksen palauttama teksti 160 merkkiin saakka välitetään tilaajalle tekstiviestinä. QLA MS text -rajapinnalla ei voi lähettää unicode- tai binääriviestejä. QLA MS extended -rajapintaa käytettessä sovelluksen pitää palauttaa riveittäin avain=arvo -pareja, joiden perusteella vastausviesti lähetetään. QLA MS extended -rajapinnalla voidaan lähettää myös binääriviestejä (esim. soittoääniä ja logoja) sekä unicode-merkistöllä olevia viestejä. Sovellukselle välitettävät muuttujat Tekstiviesteille (sms) sovellus saa Messtolta seuraavat muuttujat: sms_source Tilaajan numero kansainvälisessä muodossa. sms_dest Numero johon viesti on lähetty. sms_command Viestin avainsana. sms_params Viestin avainsanan jälkeinen osa. sms_text Tekstiviesti alkuperäisessä muodossa. Messto koostaa automaattisesti yli 160-merkkiset moniosaiset tekstiviestit yhdeksti pitkäksi viestiksi.

5 K U U L A L A A K E R I LUOTTAMUKSELLINEN 5(6) Multimediaviestit (mms) koostuvat yhdestä tai usemmasta osasta, esim. tekstistä, kuvista, äänistä, videoista ja smil-esityksistä. Sovellus saa Messtolta seuraavat muuttujat: From to subject parts content_typex content_namex content_bodyx Tilaajan numero kansainvälisessä muodossa. Numero johon viesti on lähetty. Viestin aihe. Osien lukumäärä. Mime-tyyppi (X = 1... parts). Tiedostonimi (X = 1... parts). Binääridata heksamuodossa (X = 1... parts) Sovelluksen palauttamat muuttujat Sovelluksen Messtolle antamat avain=arvo parit käytetettäessä QLA MS extended -rajapintaa: sms_text Tekstiviesti ISO merkistöllä. sms_binary Voidaan käyttää sms_text:n sijasta lähetettäessä binääriviestejä. sms_unicode Voidaan käyttää sms_text:n sijasta lähetettäessä Unicode-viestejä sms_udh Viestiin liitettävä User Data Header. URL jota kutsutaan kun viestille on saatu sms_receipt toimituskuittaus. URL:ään loppuun onnistuneessa toimituksessa &receipt_value=ack ja epäonnistuneessa &receipt_value=nack. sms_delayed_abs Viestin viivästetty lähetys, muodossa yyyymmddhhmm. sms_delayed_rel Viestin viivästetty lähetys sekunteina nykyisestä sms_valid_abs Viestin viimeinen voimassaoloaika, muodossa yyyymmddhhmm. sms_valid_rel Viestin voimassaoloaika sekunteina nykyisestä sms_pid Protocol identifier (GSM 03.40). sms_class Viestin luokka (GSM 03.40). Viestin hinta (esim. 0.50e tai 0.00e). Tarkista sms_tariff ajantasaiset tariffiluokat Kuulalakeri Oy:ltä ennen käyttöönottoa. Binääriviesti ja UDH tulee esittää heksana 8 bitin ryhmissä, esimerkiksi QLA on enkoodattuna 514c41. Unicode-viesti tulee esittää heksana 16 bitin ryhmissä, esimerkiksi QLA on enkoodattuna c0041. Esimerkki QLA MS text sovelluksesta Sovellus lähettää vastausviestin Time: 14:42, Your GSM-number is Bye!. example_text.php: <? // PHP Example of QLA MS / Messto HTTP API text) // QLA MS accepts only text/plain, not needed for Messto HTTP API header("content-type: text/plain"); // Returns fancy message to subscriber printf("time: %s. Your GSM-number is %s. Bye!", strftime("%h:%m"), $sms_source);?>

6 K U U L A L A A K E R I LUOTTAMUKSELLINEN 6(6) Esimerkki QLA MS extended sovelluksesta Virhelogi Sovellus lähettää vastausviestinä soittoäänen. example_extended.php: <? // PHP Example of QLA MS / Messto HTTP API (extended) // QLA MS accepts only text/plain, not needed for Messto HTTP API header("content-type: text/plain"); $udh = " "; $binary = "024a3a59c995ada5c994041ea4c956a0d a492a1a4a89d a39449a a8ad125525d2a e2544e e24e24aa4aa4d24d25a4e c51ca24d20bb09a a92a82ec51aa24aa09b10712a b944d "; print "sms_dest=$sms_source\n"; print "sms_udh=$sms_udh\n"; print "sms_binary=$sms_binary\n";?> Valitse Lisäpalvelut valikosta lisäpalvelu HTTP. Jos palvelun logissa on epäonnistuneita HTTP-pyyntöjä tai muita virheita, ne listataan virhelogissa. Virhelogissa jokainen virhe näkyy omana rivinään, joka alkaa päivämäärällä, jota seuraa varsinainen virhekoodi ja viimeisenä sulkujen sisällä palvelunumero ja avainsana. Uusin virhetilanne näkyy viimeisenä listassa. Voit tyhjentää virhelogin painamalla tyhjennä-linkkiä.