tästä - Kuulalaakeri Oy
Transcription
tästä - Kuulalaakeri Oy
KUULALAAKERI 1(6) LUOTTAMUKSELLINEN 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 30.12.2010 Kuulalaakeri Oy PL 271 20101 TURKU Puh: (02) 334 3000 Faksi: (02) 334 3100 Kotisivu: www.kuulalaakeri.fi Y-tunnus: 1545919-9 Kotipaikka: Turku KUULALAAKERI 2(6) LUOTTAMUKSELLINEN Lähetys Palvelimen URL Salaamattomana: http://www.messto.com/send SSL-salauksella: https://www.messto.com/send 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) Parametri sms_username sms_password Selitys Messto HTTP API-palvelun käyttäjätunnus. Messto HTTP API-palvelun salasana. Vastaanottajan matkapuhelinnumero, kansainvälisessä (+358…) muodossa. Lähetettävä tekstiviesti ISO-8859-1 merkistöllä. sms_dest sms_text 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) Parametri Selitys Voidaan käyttää sms_text:n sijaan lähetettäessä binääriviestejä. Voidaan käyttää sms_text:n sijaan lähetettäessä unicode-viestejä. Viestiin liitettävä User Data Header. 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 toimituskuittaus. Pyyntöön lisätään onnistuneessa toimituksessa arvo &receipt_value=ack tai epäonnistuneessa &receipt_value=nack. Viestin viivästetty lähetys, muodossa yyyymmddhhmm (UTC ajassa) Viestin viivästetty lähetys sekunteina nykyisestä hetkestä. Viestin viimeinen voimassaoloaika, muodossa yyyymmddhhmm. Viestin voimassaoloaika sekunteina nykyisestä hetkestä. Protocol identifier (GSM 03.40). Viestin luokka (GSM 03.40). Viestin hintaluokka, katso kohta maksulliset pushviestit. Odotetaan vastausviestiä ilman avainsanaa. Muuttujan arvoksi annetaan kaksisuuntaisen palvelun avainsana ilman yrityskohtaista alkuosaa (esim. QLA TILAUS -> TILAUS). 1 Vaustausviestin odotusaika sekunteina (max 86400 = 1 vuorokausi, oletus 86400) sms_binary sms_unicode sms_udh sms_source sms_receipt sms_delayed_abs sms_delayed_rel sms_valid_abs sms_valid_rel sms_pid sms_class sms_tariff sms_magicmapping sms_magicmapping_ttl 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 00580059005a. 30.12.2010 Kuulalaakeri Oy PL 271 20101 TURKU Puh: (02) 334 3000 Faksi: (02) 334 3100 Kotisivu: www.kuulalaakeri.fi Y-tunnus: 1545919-9 Kotipaikka: Turku KUULALAAKERI 3(6) LUOTTAMUKSELLINEN Muuttujat multimediaviesteille (MMS) Parametri username password Selitys 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). from to subject content_nameX content_typeX content_bodyX 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 4d657373746f. 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. 17252: 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ä: https://user:pass@www.messto.com/xtras/abhelper.phtml?search[]=&limit[group_and]=17252+push Push-ryhmän nimi on muotoa palvelunumero + välilyönti + avainsana, ylläolevassa esimerkissä se on “17252 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): https://www.messto.com/send?sms_username=kalle&sms_password= kehveli&sms_dest=%2b358401 234567&sms_text=Terveisi%e4+Messtosta Multimediaviesti (MMS): https://www.messto.com/send?username=kalle&password=kehveli &to=%2b358401234567&subject=Otsikko&content_name1=text.txt &content_type1=text%2fplain%3b+charset%3dUTF-8 &content_body1=5465727665697369c3a4204d657373746f737461 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> 30.12.2010 Kuulalaakeri Oy PL 271 20101 TURKU Puh: (02) 334 3000 Faksi: (02) 334 3100 Kotisivu: www.kuulalaakeri.fi Y-tunnus: 1545919-9 Kotipaikka: Turku KUULALAAKERI 4(6) LUOTTAMUKSELLINEN 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 http://. 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: Parametri Selitys 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. 30.12.2010 Kuulalaakeri Oy PL 271 20101 TURKU Puh: (02) 334 3000 Faksi: (02) 334 3100 Kotisivu: www.kuulalaakeri.fi Y-tunnus: 1545919-9 Kotipaikka: Turku KUULALAAKERI 5(6) LUOTTAMUKSELLINEN Multimediaviestit (mms) koostuvat yhdestä tai usemmasta osasta, esim. tekstistä, kuvista, äänistä, videoista ja smil-esityksistä. Sovellus saa Messtolta seuraavat muuttujat: Parametri From to subject parts content_typeX content_nameX content_bodyX Selitys 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: Parametri sms_text Selitys Tekstiviesti ISO 8859-1 merkistöllä. Voidaan käyttää sms_text:n sijasta lähetettäessä binääriviestejä. Voidaan käyttää sms_text:n sijasta lähetettäessä Unicode-viestejä Viestiin liitettävä User Data Header. URL jota kutsutaan kun viestille on saatu toimituskuittaus. URL:ään loppuun onnistuneessa toimituksessa &receipt_value=ack ja epäonnistuneessa &receipt_value=nack. Viestin viivästetty lähetys, muodossa yyyymmddhhmm. Viestin viivästetty lähetys sekunteina nykyisestä hetkestä. Viestin viimeinen voimassaoloaika, muodossa yyyymmddhhmm. Viestin voimassaoloaika sekunteina nykyisestä hetkestä. Protocol identifier (GSM 03.40). Viestin luokka (GSM 03.40). Viestin hinta (esim. 0.50e tai 0.00e). Tarkista ajantasaiset tariffiluokat Kuulalakeri Oy:ltä ennen käyttöönottoa. sms_binary sms_unicode sms_udh sms_receipt sms_delayed_abs sms_delayed_rel sms_valid_abs sms_valid_rel sms_pid sms_class sms_tariff 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 0051004c0041. Esimerkki QLA MS text –sovelluksesta Sovellus lähettää vastausviestin “Time: 14:42, Your GSM-number is +358408421895. 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); ?> 30.12.2010 Kuulalaakeri Oy PL 271 20101 TURKU Puh: (02) 334 3000 Faksi: (02) 334 3100 Kotisivu: www.kuulalaakeri.fi Y-tunnus: 1545919-9 Kotipaikka: Turku KUULALAAKERI 6(6) LUOTTAMUKSELLINEN Esimerkki QLA MS extended –sovelluksesta 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 = "06050415810000"; $binary = "024a3a59c995ada5c994041ea4c956a0d512692839449a492a1a4a89d126927 12a39449a4176134a8ad125525d2a354495413620e2544e88345728e24e24aa4aa4d24d25a4e8934 834938c51ca24d20bb09a5456892a92a82ec51aa24aa09b10712a2744932b944d2552692000"; print "sms_dest=$sms_source\n"; print "sms_udh=$sms_udh\n"; print "sms_binary=$sms_binary\n"; ?> Virhelogi 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ä. 30.12.2010 Kuulalaakeri Oy PL 271 20101 TURKU Puh: (02) 334 3000 Faksi: (02) 334 3100 Kotisivu: www.kuulalaakeri.fi Y-tunnus: 1545919-9 Kotipaikka: Turku